networks.rst
1 .. _networks-main: 2 3 ***************** 4 Building Networks 5 ***************** 6 7 This chapter will provide you with the high-level knowledge needed to build networks with 8 Reticulum. It will not, however tell you all you need to know to succesfully 9 design and configure every kind of network you can imagine. For this, you will 10 most likely need to read this manual in its entirity, invest significant time 11 into experimenting with the stack, and learning functionality intuitively. 12 13 Still, after reading this chapter, you should be well equipped to *start* that 14 journey. While Reticulum is **fundamentally different** compared to other 15 networking technologies, it can often be easier than using traditional stacks. 16 If you've built networks before, you will probably have to forget, or at least 17 temporarily ignore, a lot of things at this point. It will all makes sense in 18 the end though. Hopefully. 19 20 If you're used to protocols like IP, let's at least start with some relief: 21 You don't have to worry about coordinating addresses, subnets and routing for an 22 entire network that you might not know how will evolve in the future. With 23 Reticulum, you can simply add more segments to your network when it becomes 24 necessary, and Reticulum will handle the convergence of the entire network 25 automatically. There's plenty more neat aspects like that to Reticulum, but 26 we're getting ahead of ourselves. Let's cover the basics first. 27 28 Concepts & Overview 29 -------------------- 30 31 Before you start building your own networks, it's important to understand the 32 fundamental principles that distinguish Reticulum networks from traditional 33 networking approaches. These principles shape how you design your network, 34 what trade-offs you encounter, and what capabilities you can rely on. 35 36 Reticulum is not a single network you "join", it is a toolkit for *creating* networks. 37 You decide what mediums to use, how nodes connect, what trust boundaries exist, 38 and what the network's purpose is. Reticulum provides the cryptographic foundation, 39 the transport mechanisms, and the convergence algorithms that make your design 40 workable. You provide the intent and the structure. 41 42 This approach offers tremendous flexibility, but it requires thinking in terms of 43 different abstractions than those used in conventional networking. 44 45 Introductory Considerations 46 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 47 48 There are important points that need to be kept in mind when building networks 49 with Reticulum: 50 51 * | In a Reticulum network, any node can autonomously generate as many addresses 52 (called *destinations* in Reticulum terminology) as it needs, which become 53 globally reachable to the rest of the network. There is no central point of 54 control over the address space. 55 56 * | Reticulum was designed to handle both very small, and very large networks. 57 While the address space can support billions of endpoints, Reticulum is 58 also very useful when just a few devices needs to communicate. 59 60 * | Low-bandwidth networks, like LoRa and packet radio, can interoperate and 61 interconnect with much larger and higher bandwidth networks without issue. 62 Reticulum automatically manages the flow of information to and from various 63 network segments, and when bandwidth is limited, local traffic is prioritised. 64 You will, however, need to configure your interfaces correctly. If you tell 65 Reticulum to pass all announce traffic from a gigabit link to a LoRa interfaces, 66 it will try as best as possible to comply with this, while still respecting 67 bandwidth limits, but you *will* waste a lot of precious bandwidth and airtime, 68 and your LoRa network will not work very well. 69 70 * | Reticulum provides sender/initiator anonymity by default. There is no way 71 to filter traffic or discriminate it based on the source of the traffic. 72 73 * | All traffic is encrypted using ephemeral keys generated by an Elliptic Curve 74 Diffie-Hellman key exchange on Curve25519. There is no way to inspect traffic 75 contents, and no way to prioritise or throttle certain kinds of traffic. 76 All transport and routing layers are thus completely agnostic to traffic type, 77 and will pass all traffic equally. 78 79 * | Reticulum can function both with and without infrastructure. When *transport 80 nodes* are available, they can route traffic over multiple hops for other 81 nodes, and will function as a distributed cryptographic keystore. When there 82 is no transport nodes available, all nodes that are within communication range 83 can still communicate. 84 85 * | Every node can become a transport node, simply by enabling it in it's 86 configuration, but there is no need for every node on the network to be a 87 transport node. Letting every node be a transport node will in most cases 88 degrade the performance and reliability of the network. 89 90 *In general terms, if a node is stationary, well-connected and kept running 91 most of the time, it is a good candidate to be a transport node. For optimal 92 performance, a network should contain the amount of transport nodes that 93 provides connectivity to the intended area / topography, and not many more 94 than that.* 95 96 * | Reticulum is designed to work reliably in open, trustless environments. This 97 means you can use it to create open-access networks, where participants can 98 join and leave in a free and unorganised manner. This property allows an 99 entirely new, and so far, mostly unexplored class of networked applications, 100 where networks, and the information flow within them can form and dissolve 101 organically. 102 103 * | You can just as easily create closed networks, since Reticulum allows you to 104 add authentication to any interface. This means you can restrict access on 105 any interface type, even when using legacy devices, such as modems. You can 106 also mix authenticated and open interfaces on the same system. See the 107 :ref:`Common Interface Options<interfaces-options>` section of the :ref:`Interfaces<interfaces-main>` 108 chapter of this manual for information on how to set up interface authentication. 109 110 111 Reticulum allows you to mix very different kinds of networking mediums into a 112 unified mesh, or to keep everything within one medium. You could build a "virtual 113 network" running entirely over the Internet, where all nodes communicate over TCP 114 and UDP "channels". You could also build such a network using other already-established 115 communications channels as the underlying carrier for Reticulum. 116 117 However, most real-world networks will probably involve either some form of 118 wireless or direct hardline communications. To allow Reticulum to communicate 119 over any type of medium, you must specify it in the configuration file, by default 120 located at ``~/.reticulum/config``. See the :ref:`Supported Interfaces<interfaces-main>` 121 chapter of this manual for interface configuration examples. 122 123 Any number of interfaces can be configured, and Reticulum will automatically 124 decide which are suitable to use in any given situation, depending on where 125 traffic needs to flow. 126 127 Destinations, Not Addresses 128 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 129 130 In traditional networking, addresses are allocated from a managed space. If you want to 131 communicate with another node, you need to know its address, and that address 132 must be unique within the network segment. This requires coordination, either 133 through manual assignment, DHCP servers, or other allocation mechanisms. 134 135 Reticulum replaces addresses with **destinations**. A destination is identified by a 16-byte 136 hash (128 bits) derived from a SHA-256 hash of the destination's identifying 137 characteristics. This hash serves as the address on the network. On the network, it 138 is represented in binary, but when displayed to human users, it will usually look something like 139 this ``<13425ec15b621c1d928589718000d814>``. 140 141 The critical difference is that *any node can generate as many destinations as it 142 needs, without coordination*. A destination's uniqueness is guaranteed by the 143 collision resistance of SHA-256 and the inclusion of the node's public key in the 144 hash calculation. Two nodes can both use the destination name 145 ``messenger.user.inbox``, but they will have different destination hashes because 146 their public keys differ. Both can coexist on the same network without conflict. 147 148 This has profound implications for network design: 149 150 * **No address allocation planning:** You never need to reserve address ranges, 151 plan subnets, or coordinate with other network operators. Nodes simply generate 152 destinations and announce them. 153 154 * **Global portability:** A destination is not tied to a physical location or 155 network segment. A node can move its destinations across interfaces, mediums, 156 or even between entirely separate Reticulum networks simply by sending an 157 announce on the new medium. 158 159 * **Implicit authentication:** Because destinations are bound to public keys, 160 communication to a destination is inherently cryptographically authenticated. 161 Only the holder of the corresponding private key can decrypt and respond to 162 traffic addressed to that destination. This also makes application-level 163 authentication *much* simpler, since it can directly use the foundational 164 identity verification built into the core networking layer. 165 166 * **Identity abstraction:** A single Reticulum Identity can create multiple 167 destinations. This allows a single entity (a person, a device, a service) to 168 present multiple endpoints without needing multiple cryptographic keypairs. 169 170 171 Transport Nodes and Instances 172 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 173 174 Reticulum distinguishes between two types of nodes: **Instances** 175 and **Transport Nodes**. Every node running Reticulum is an Instance, but not 176 every Instance is a Transport Node. 177 178 A **Reticulum Instance** is any system running the Reticulum stack. It can create 179 destinations, send and receive packets, establish links, and communicate with 180 other nodes. It can also host destinations that are connectable for *anyone* else 181 in the network. This means you can easily host globally available services from 182 any location, including your home or office. Network-wide, global connectivity 183 for all destinations is guaranteed, as long as there is *some* physical way to 184 actually transport the packets. Instances are the default state and are appropriate for most end-user devices, 185 such as phones, laptops, sensors, or any device that primarily consumes network services. 186 187 A **Transport Node** is an Instance that has been explicitly configured to 188 participate in network-wide transport. Transport nodes forward packets across 189 hops, propagate announces, maintain path tables, and serve path requests on 190 behalf of other nodes. When a destination sends an announce, Transport Nodes 191 receive it, remember the path, and rebroadcast it to other interfaces. When a node 192 needs to reach a destination it doesn't have a path for, Transport Nodes help 193 resolve the path through the network. 194 195 Even devices hosting services or serving content should probably just be configured 196 as instances, and themselves connect to wider networks via a Transport Node. 197 In some situations, this may not be practical though, and as an example, it is 198 entirely viable to host a personal Transport Node on a Raspberry Pi, while it 199 is at the same time running an LXMF propagation node, and hosting your personal 200 site or files over Reticulum. 201 202 The distinction is important. **Not** every node should be a Transport Node: 203 204 * **Resource consumption:** Transport nodes maintain path tables, process 205 announces, and forward traffic. This requires memory and CPU resources that 206 may be limited on low-powered devices. 207 208 * **Stability requirements:** Transport nodes contribute to network convergence. 209 If Transport Nodes frequently go offline, path tables become stale and 210 convergence suffers. Stable, always-on nodes make better Transport Nodes. 211 212 * **Bandwidth considerations:** Transport nodes process and rebroadcast network 213 maintenance traffic. On very low-bandwidth mediums, having too many Transport 214 Nodes will consume capacity that should be used for actual data. 215 216 In practice, a network typically has a relatively small number of Transport Nodes 217 strategically placed to provide coverage and connectivity. End-user devices run 218 as Instances, connecting through nearby Transport Nodes to reach the wider network. 219 This pattern mirrors traditional networking where routers forward traffic while 220 end hosts simply consume connectivity, but with the crucial difference that any 221 node *can* become a router if needed, and the decision is yours to make based on 222 your network's requirements. 223 224 Transport nodes also function as distributed cryptographic keystores. When a 225 destination announces itself, Transport Nodes cache the public key and destination 226 information. Other nodes can request unknown public keys from the network, and 227 Transport Nodes respond with the cached information. This eliminates the need for 228 a central directory service while ensuring that public keys remain available 229 throughout the network. 230 231 Trustless Networking 232 ^^^^^^^^^^^^^^^^^^^^ 233 234 Traditional network security models assume high levels of trust at 235 specific layers. You might trust your ISP to deliver packets without inspection, 236 or trust your VPN provider to handle your traffic, or trust the network 237 administrator to configure firewalls appropriately. These trust relationships 238 create vulnerabilities and dependencies. 239 240 Reticulum is designed to function in **open, trustless environments**. This 241 means the protocol makes no assumptions about the trustworthiness of the network 242 infrastructure, the other participants, or the transport mediums. Every aspect 243 of communication is secured cryptographically: 244 245 * **Traffic encryption:** All traffic to single destinations is encrypted using 246 ephemeral keys. 247 248 * **Source anonymity:** Reticulum packets do not include source addresses. 249 An observer intercepting a packet cannot determine who sent it, only who it is 250 addressed to (unless IFAC is enabled, in which case nothing can be determined). 251 This provides initiator anonymity by default. 252 253 * **Path verification:** The announce mechanism includes cryptographic signatures that 254 prove the authenticity of destination announcements. 255 256 * **Unforgeable delivery confirmations:** When a destination proves receipt of a 257 packet, the proof is signed with the destination's identity key. This prevents 258 false acknowledgments and ensures reliable delivery verification. 259 260 * **Interface authentication:** When using Interface Access Codes (IFAC), packets 261 on authenticated interfaces carry signatures derived from a shared secret. Only 262 nodes with the correct network name and passphrase can generate valid packets, allowing creation 263 of virtual private networks on shared mediums. 264 265 The trustless design has important consequences for network design: 266 267 * **Open-access networks are viable:** You can build networks that anyone can 268 join without pre-approval. Because traffic is encrypted and authenticated end- 269 to-end, participants cannot interfere with each other's private communication, 270 even if they share the same transport infrastructure. 271 272 * **No traffic inspection or prioritization:** Because traffic contents and 273 sources are opaque to intermediate nodes, there is no mechanism for filtering, 274 prioritizing, or throttling traffic based on its type or origin. All traffic 275 is treated equally. From a neutrality perspective, this is a feature. 276 277 * **Adversarial resilience:** The network can operate even if some nodes are 278 malicious or controlled by adversaries. While a malicious Transport Node could 279 refuse to forward certain traffic or drop packets, it cannot decrypt, modify, 280 or impersonate legitimate traffic. Redundant paths and multiple Transport Nodes 281 mitigate the impact of malicious nodes. 282 283 Of course, you can also create closed networks. Interface Access 284 Codes allow you to restrict participation on specific interfaces. Network 285 Identities enable you to verify that discovered interfaces belong to trusted 286 operators. Blackhole management lets you block malicious identities. Reticulum 287 provides both the tools for open networks and the controls for closed ones. The 288 choice is yours based on your requirements. 289 290 291 Heterogeneous Connectivity 292 ^^^^^^^^^^^^^^^^^^^^^^^^^^ 293 294 In conventional networking, mixing different transport mediums typically requires 295 gateways, translation layers, and careful configuration. A WiFi network doesn't 296 natively interoperate with a packet radio network without additional infrastructure, 297 and you can't just download a car over a serial port, or send an encrypted message 298 in a QR code. 299 300 Reticulum treats **heterogeneity as a core premise**. The protocol is designed 301 to seamlessly mix mediums with vastly different characteristics: 302 303 * **Bandwidth:** LoRa links operating at a few hundred bits per second can 304 interconnect with gigabit Ethernet backbones. Reticulum automatically manages 305 the flow of information, prioritizing local traffic on slow segments while 306 allowing global convergence. 307 308 * **Latency:** Satellite links with multi-second latency can coexist with local 309 links measured in milliseconds. The transport system handles timing, asynchronous 310 delivery and retransmissions transparently. 311 312 * **Topology:** Point-to-point microwave links, broadcast radio networks, 313 switched Ethernet fabrics, and virtual tunnels over the Internet can all be 314 part of the same Reticulum network. 315 316 * **Reliability:** Intermittent connections that come and go (such as mobile 317 devices or opportunistic radio contacts) can participate alongside always-on 318 infrastructure. Reticulum gracefully handles link loss and reconnection. 319 320 This heterogeneity is achieved through several design elements: 321 322 * **Expandable, medium-agnostic interface system:** Reticulum communicates with the physical 323 world through interface modules. Adding support for a new medium is a matter 324 of implementing an interface class. The protocol itself remains unchanged. 325 326 * **Interface modes:** Different modes (``full``, ``gateway``, ``access_point``, 327 ``roaming``, ``boundary``) allow you to configure how interfaces interact with 328 the wider network based on their characteristics and role. 329 330 * **Announce propagation rules:** Announces are forwarded between interfaces 331 according to rules that account for bandwidth limitations and interface modes. 332 Slow segments are not overwhelmed by traffic from fast segments. 333 334 * **Local traffic prioritization:** When bandwidth is constrained, Reticulum 335 prioritizes announces for nearby destinations. This ensures that local 336 connectivity remains functional even when global convergence is incomplete. 337 338 For network designers, this means you are free to use whatever mediums are 339 available, affordable, or appropriate for your situation. You might use LoRa for 340 wide-area low-bandwidth coverage, WiFi for local high-capacity links, I2P for 341 anonymous Internet connectivity, and Ethernet for infrastructure backhauls, all 342 within the same network. Reticulum handles the translation and coordination 343 automatically. 344 345 The key design consideration is not whether different mediums can work together 346 (they can), but **how** they should work together based on your goals. A node 347 with multiple interfaces spanning heterogeneous mediums needs to be configured 348 with appropriate interface modes so that traffic flows efficiently. A gateway 349 connecting a slow LoRa segment to a fast Internet backbone should be configured 350 differently than a mobile device roaming between radio cells.