networks.html
1 <!doctype html> 2 <html class="no-js" lang="en" data-content_root="./"> 3 <head><meta charset="utf-8"> 4 <meta name="viewport" content="width=device-width,initial-scale=1"> 5 <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" /> 6 <link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="next" title="Support Reticulum" href="support.html"><link rel="prev" title="Configuring Interfaces" href="interfaces.html"> 7 <link rel="prefetch" href="_static/rns_logo_512.png" as="image"> 8 9 <!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 --> 10 <title>Building Networks - Reticulum Network Stack 1.1.3 documentation</title> 11 <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" /> 12 <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" /> 13 <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" /> 14 <link rel="stylesheet" type="text/css" href="_static/styles/furo-extensions.css?v=8dab3a3b" /> 15 <link rel="stylesheet" type="text/css" href="_static/custom.css?v=bb3cebc5" /> 16 17 18 19 20 <style> 21 body { 22 --color-code-background: #f2f2f2; 23 --color-code-foreground: #1e1e1e; 24 25 } 26 @media not print { 27 body[data-theme="dark"] { 28 --color-code-background: #202020; 29 --color-code-foreground: #d0d0d0; 30 --color-background-primary: #202b38; 31 --color-background-secondary: #161f27; 32 --color-foreground-primary: #dbdbdb; 33 --color-foreground-secondary: #a9b1ba; 34 --color-brand-primary: #41adff; 35 --color-background-hover: #161f27; 36 --color-api-name: #ffbe85; 37 --color-api-pre-name: #efae75; 38 39 } 40 @media (prefers-color-scheme: dark) { 41 body:not([data-theme="light"]) { 42 --color-code-background: #202020; 43 --color-code-foreground: #d0d0d0; 44 --color-background-primary: #202b38; 45 --color-background-secondary: #161f27; 46 --color-foreground-primary: #dbdbdb; 47 --color-foreground-secondary: #a9b1ba; 48 --color-brand-primary: #41adff; 49 --color-background-hover: #161f27; 50 --color-api-name: #ffbe85; 51 --color-api-pre-name: #efae75; 52 53 } 54 } 55 } 56 </style></head> 57 <body> 58 59 <script> 60 document.body.dataset.theme = localStorage.getItem("theme") || "auto"; 61 </script> 62 63 64 <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> 65 <symbol id="svg-toc" viewBox="0 0 24 24"> 66 <title>Contents</title> 67 <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024"> 68 <path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/> 69 </svg> 70 </symbol> 71 <symbol id="svg-menu" viewBox="0 0 24 24"> 72 <title>Menu</title> 73 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 74 stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu"> 75 <line x1="3" y1="12" x2="21" y2="12"></line> 76 <line x1="3" y1="6" x2="21" y2="6"></line> 77 <line x1="3" y1="18" x2="21" y2="18"></line> 78 </svg> 79 </symbol> 80 <symbol id="svg-arrow-right" viewBox="0 0 24 24"> 81 <title>Expand</title> 82 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 83 stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right"> 84 <polyline points="9 18 15 12 9 6"></polyline> 85 </svg> 86 </symbol> 87 <symbol id="svg-sun" viewBox="0 0 24 24"> 88 <title>Light mode</title> 89 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 90 stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="feather-sun"> 91 <circle cx="12" cy="12" r="5"></circle> 92 <line x1="12" y1="1" x2="12" y2="3"></line> 93 <line x1="12" y1="21" x2="12" y2="23"></line> 94 <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> 95 <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> 96 <line x1="1" y1="12" x2="3" y2="12"></line> 97 <line x1="21" y1="12" x2="23" y2="12"></line> 98 <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> 99 <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> 100 </svg> 101 </symbol> 102 <symbol id="svg-moon" viewBox="0 0 24 24"> 103 <title>Dark mode</title> 104 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 105 stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon"> 106 <path stroke="none" d="M0 0h24v24H0z" fill="none" /> 107 <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" /> 108 </svg> 109 </symbol> 110 <symbol id="svg-sun-with-moon" viewBox="0 0 24 24"> 111 <title>Auto light/dark, in light mode</title> 112 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 113 stroke-width="1" stroke-linecap="round" stroke-linejoin="round" 114 class="icon-custom-derived-from-feather-sun-and-tabler-moon"> 115 <path style="opacity: 50%" d="M 5.411 14.504 C 5.471 14.504 5.532 14.504 5.591 14.504 C 3.639 16.319 4.383 19.569 6.931 20.352 C 7.693 20.586 8.512 20.551 9.25 20.252 C 8.023 23.207 4.056 23.725 2.11 21.184 C 0.166 18.642 1.702 14.949 4.874 14.536 C 5.051 14.512 5.231 14.5 5.411 14.5 L 5.411 14.504 Z"/> 116 <line x1="14.5" y1="3.25" x2="14.5" y2="1.25"/> 117 <line x1="14.5" y1="15.85" x2="14.5" y2="17.85"/> 118 <line x1="10.044" y1="5.094" x2="8.63" y2="3.68"/> 119 <line x1="19" y1="14.05" x2="20.414" y2="15.464"/> 120 <line x1="8.2" y1="9.55" x2="6.2" y2="9.55"/> 121 <line x1="20.8" y1="9.55" x2="22.8" y2="9.55"/> 122 <line x1="10.044" y1="14.006" x2="8.63" y2="15.42"/> 123 <line x1="19" y1="5.05" x2="20.414" y2="3.636"/> 124 <circle cx="14.5" cy="9.55" r="3.6"/> 125 </svg> 126 </symbol> 127 <symbol id="svg-moon-with-sun" viewBox="0 0 24 24"> 128 <title>Auto light/dark, in dark mode</title> 129 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 130 stroke-width="1" stroke-linecap="round" stroke-linejoin="round" 131 class="icon-custom-derived-from-feather-sun-and-tabler-moon"> 132 <path d="M 8.282 7.007 C 8.385 7.007 8.494 7.007 8.595 7.007 C 5.18 10.184 6.481 15.869 10.942 17.24 C 12.275 17.648 13.706 17.589 15 17.066 C 12.851 22.236 5.91 23.143 2.505 18.696 C -0.897 14.249 1.791 7.786 7.342 7.063 C 7.652 7.021 7.965 7 8.282 7 L 8.282 7.007 Z"/> 133 <line style="opacity: 50%" x1="18" y1="3.705" x2="18" y2="2.5"/> 134 <line style="opacity: 50%" x1="18" y1="11.295" x2="18" y2="12.5"/> 135 <line style="opacity: 50%" x1="15.316" y1="4.816" x2="14.464" y2="3.964"/> 136 <line style="opacity: 50%" x1="20.711" y1="10.212" x2="21.563" y2="11.063"/> 137 <line style="opacity: 50%" x1="14.205" y1="7.5" x2="13.001" y2="7.5"/> 138 <line style="opacity: 50%" x1="21.795" y1="7.5" x2="23" y2="7.5"/> 139 <line style="opacity: 50%" x1="15.316" y1="10.184" x2="14.464" y2="11.036"/> 140 <line style="opacity: 50%" x1="20.711" y1="4.789" x2="21.563" y2="3.937"/> 141 <circle style="opacity: 50%" cx="18" cy="7.5" r="2.169"/> 142 </svg> 143 </symbol> 144 <symbol id="svg-pencil" viewBox="0 0 24 24"> 145 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 146 stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-pencil-code"> 147 <path d="M4 20h4l10.5 -10.5a2.828 2.828 0 1 0 -4 -4l-10.5 10.5v4" /> 148 <path d="M13.5 6.5l4 4" /> 149 <path d="M20 21l2 -2l-2 -2" /> 150 <path d="M17 17l-2 2l2 2" /> 151 </svg> 152 </symbol> 153 <symbol id="svg-eye" viewBox="0 0 24 24"> 154 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 155 stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-eye-code"> 156 <path stroke="none" d="M0 0h24v24H0z" fill="none" /> 157 <path d="M10 12a2 2 0 1 0 4 0a2 2 0 0 0 -4 0" /> 158 <path 159 d="M11.11 17.958c-3.209 -.307 -5.91 -2.293 -8.11 -5.958c2.4 -4 5.4 -6 9 -6c3.6 0 6.6 2 9 6c-.21 .352 -.427 .688 -.647 1.008" /> 160 <path d="M20 21l2 -2l-2 -2" /> 161 <path d="M17 17l-2 2l2 2" /> 162 </svg> 163 </symbol> 164 </svg> 165 166 <input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation" aria-label="Toggle site navigation sidebar"> 167 <input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc" aria-label="Toggle table of contents sidebar"> 168 <label class="overlay sidebar-overlay" for="__navigation"></label> 169 <label class="overlay toc-overlay" for="__toc"></label> 170 171 <a class="skip-to-content muted-link" href="#furo-main-content">Skip to content</a> 172 173 174 175 <div class="page"> 176 <header class="mobile-header"> 177 <div class="header-left"> 178 <label class="nav-overlay-icon" for="__navigation"> 179 <span class="icon"><svg><use href="#svg-menu"></use></svg></span> 180 </label> 181 </div> 182 <div class="header-center"> 183 <a href="index.html"><div class="brand">Reticulum Network Stack 1.1.3 documentation</div></a> 184 </div> 185 <div class="header-right"> 186 <div class="theme-toggle-container theme-toggle-header"> 187 <button class="theme-toggle" aria-label="Toggle Light / Dark / Auto color theme"> 188 <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg> 189 <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg> 190 <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg> 191 <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg> 192 </button> 193 </div> 194 <label class="toc-overlay-icon toc-header-icon" for="__toc"> 195 <span class="icon"><svg><use href="#svg-toc"></use></svg></span> 196 </label> 197 </div> 198 </header> 199 <aside class="sidebar-drawer"> 200 <div class="sidebar-container"> 201 202 <div class="sidebar-sticky"><a class="sidebar-brand" href="index.html"> 203 <div class="sidebar-logo-container"> 204 <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/> 205 </div> 206 207 <span class="sidebar-brand-text">Reticulum Network Stack 1.1.3 documentation</span> 208 209 </a><form class="sidebar-search-container" method="get" action="search.html" role="search"> 210 <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search"> 211 <input type="hidden" name="check_keywords" value="yes"> 212 <input type="hidden" name="area" value="default"> 213 </form> 214 <div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree"> 215 <ul class="current"> 216 <li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li> 217 <li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li> 218 <li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li> 219 <li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li> 220 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li> 221 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li> 222 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li> 223 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li> 224 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Building Networks</a></li> 225 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li> 226 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li> 227 <li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li> 228 </ul> 229 <ul> 230 <li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li> 231 </ul> 232 233 </div> 234 </div> 235 236 </div> 237 238 </div> 239 </aside> 240 <div class="main"> 241 <div class="content"> 242 <div class="article-container"> 243 <a href="#" class="back-to-top muted-link"> 244 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"> 245 <path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path> 246 </svg> 247 <span>Back to top</span> 248 </a> 249 <div class="content-icon-container"> 250 <div class="theme-toggle-container theme-toggle-content"> 251 <button class="theme-toggle" aria-label="Toggle Light / Dark / Auto color theme"> 252 <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg> 253 <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg> 254 <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg> 255 <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg> 256 </button> 257 </div> 258 <label class="toc-overlay-icon toc-content-icon" for="__toc"> 259 <span class="icon"><svg><use href="#svg-toc"></use></svg></span> 260 </label> 261 </div> 262 <article role="main" id="furo-main-content"> 263 <section id="building-networks"> 264 <span id="networks-main"></span><h1>Building Networks<a class="headerlink" href="#building-networks" title="Link to this heading">¶</a></h1> 265 <p>This chapter will provide you with the high-level knowledge needed to build networks with 266 Reticulum. It will not, however tell you all you need to know to succesfully 267 design and configure every kind of network you can imagine. For this, you will 268 most likely need to read this manual in its entirity, invest significant time 269 into experimenting with the stack, and learning functionality intuitively.</p> 270 <p>Still, after reading this chapter, you should be well equipped to <em>start</em> that 271 journey. While Reticulum is <strong>fundamentally different</strong> compared to other 272 networking technologies, it can often be easier than using traditional stacks. 273 If you’ve built networks before, you will probably have to forget, or at least 274 temporarily ignore, a lot of things at this point. It will all makes sense in 275 the end though. Hopefully.</p> 276 <p>If you’re used to protocols like IP, let’s at least start with some relief: 277 You don’t have to worry about coordinating addresses, subnets and routing for an 278 entire network that you might not know how will evolve in the future. With 279 Reticulum, you can simply add more segments to your network when it becomes 280 necessary, and Reticulum will handle the convergence of the entire network 281 automatically. There’s plenty more neat aspects like that to Reticulum, but 282 we’re getting ahead of ourselves. Let’s cover the basics first.</p> 283 <section id="concepts-overview"> 284 <h2>Concepts & Overview<a class="headerlink" href="#concepts-overview" title="Link to this heading">¶</a></h2> 285 <p>Before you start building your own networks, it’s important to understand the 286 fundamental principles that distinguish Reticulum networks from traditional 287 networking approaches. These principles shape how you design your network, 288 what trade-offs you encounter, and what capabilities you can rely on.</p> 289 <p>Reticulum is not a single network you “join”, it is a toolkit for <em>creating</em> networks. 290 You decide what mediums to use, how nodes connect, what trust boundaries exist, 291 and what the network’s purpose is. Reticulum provides the cryptographic foundation, 292 the transport mechanisms, and the convergence algorithms that make your design 293 workable. You provide the intent and the structure.</p> 294 <p>This approach offers tremendous flexibility, but it requires thinking in terms of 295 different abstractions than those used in conventional networking.</p> 296 <section id="introductory-considerations"> 297 <h3>Introductory Considerations<a class="headerlink" href="#introductory-considerations" title="Link to this heading">¶</a></h3> 298 <p>There are important points that need to be kept in mind when building networks 299 with Reticulum:</p> 300 <blockquote> 301 <div><ul> 302 <li><div class="line-block"> 303 <div class="line">In a Reticulum network, any node can autonomously generate as many addresses 304 (called <em>destinations</em> in Reticulum terminology) as it needs, which become 305 globally reachable to the rest of the network. There is no central point of 306 control over the address space.</div> 307 </div> 308 </li> 309 <li><div class="line-block"> 310 <div class="line">Reticulum was designed to handle both very small, and very large networks. 311 While the address space can support billions of endpoints, Reticulum is 312 also very useful when just a few devices needs to communicate.</div> 313 </div> 314 </li> 315 <li><div class="line-block"> 316 <div class="line">Low-bandwidth networks, like LoRa and packet radio, can interoperate and 317 interconnect with much larger and higher bandwidth networks without issue. 318 Reticulum automatically manages the flow of information to and from various 319 network segments, and when bandwidth is limited, local traffic is prioritised. 320 You will, however, need to configure your interfaces correctly. If you tell 321 Reticulum to pass all announce traffic from a gigabit link to a LoRa interfaces, 322 it will try as best as possible to comply with this, while still respecting 323 bandwidth limits, but you <em>will</em> waste a lot of precious bandwidth and airtime, 324 and your LoRa network will not work very well.</div> 325 </div> 326 </li> 327 <li><div class="line-block"> 328 <div class="line">Reticulum provides sender/initiator anonymity by default. There is no way 329 to filter traffic or discriminate it based on the source of the traffic.</div> 330 </div> 331 </li> 332 <li><div class="line-block"> 333 <div class="line">All traffic is encrypted using ephemeral keys generated by an Elliptic Curve 334 Diffie-Hellman key exchange on Curve25519. There is no way to inspect traffic 335 contents, and no way to prioritise or throttle certain kinds of traffic. 336 All transport and routing layers are thus completely agnostic to traffic type, 337 and will pass all traffic equally.</div> 338 </div> 339 </li> 340 <li><div class="line-block"> 341 <div class="line">Reticulum can function both with and without infrastructure. When <em>transport 342 nodes</em> are available, they can route traffic over multiple hops for other 343 nodes, and will function as a distributed cryptographic keystore. When there 344 is no transport nodes available, all nodes that are within communication range 345 can still communicate.</div> 346 </div> 347 </li> 348 <li><div class="line-block"> 349 <div class="line">Every node can become a transport node, simply by enabling it in it’s 350 configuration, but there is no need for every node on the network to be a 351 transport node. Letting every node be a transport node will in most cases 352 degrade the performance and reliability of the network.</div> 353 </div> 354 <blockquote> 355 <div><p><em>In general terms, if a node is stationary, well-connected and kept running 356 most of the time, it is a good candidate to be a transport node. For optimal 357 performance, a network should contain the amount of transport nodes that 358 provides connectivity to the intended area / topography, and not many more 359 than that.</em></p> 360 </div></blockquote> 361 </li> 362 <li><div class="line-block"> 363 <div class="line">Reticulum is designed to work reliably in open, trustless environments. This 364 means you can use it to create open-access networks, where participants can 365 join and leave in a free and unorganised manner. This property allows an 366 entirely new, and so far, mostly unexplored class of networked applications, 367 where networks, and the information flow within them can form and dissolve 368 organically.</div> 369 </div> 370 </li> 371 <li><div class="line-block"> 372 <div class="line">You can just as easily create closed networks, since Reticulum allows you to 373 add authentication to any interface. This means you can restrict access on 374 any interface type, even when using legacy devices, such as modems. You can 375 also mix authenticated and open interfaces on the same system. See the 376 <a class="reference internal" href="interfaces.html#interfaces-options"><span class="std std-ref">Common Interface Options</span></a> section of the <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Interfaces</span></a> 377 chapter of this manual for information on how to set up interface authentication.</div> 378 </div> 379 </li> 380 </ul> 381 </div></blockquote> 382 <p>Reticulum allows you to mix very different kinds of networking mediums into a 383 unified mesh, or to keep everything within one medium. You could build a “virtual 384 network” running entirely over the Internet, where all nodes communicate over TCP 385 and UDP “channels”. You could also build such a network using other already-established 386 communications channels as the underlying carrier for Reticulum.</p> 387 <p>However, most real-world networks will probably involve either some form of 388 wireless or direct hardline communications. To allow Reticulum to communicate 389 over any type of medium, you must specify it in the configuration file, by default 390 located at <code class="docutils literal notranslate"><span class="pre">~/.reticulum/config</span></code>. See the <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Supported Interfaces</span></a> 391 chapter of this manual for interface configuration examples.</p> 392 <p>Any number of interfaces can be configured, and Reticulum will automatically 393 decide which are suitable to use in any given situation, depending on where 394 traffic needs to flow.</p> 395 </section> 396 <section id="destinations-not-addresses"> 397 <h3>Destinations, Not Addresses<a class="headerlink" href="#destinations-not-addresses" title="Link to this heading">¶</a></h3> 398 <p>In traditional networking, addresses are allocated from a managed space. If you want to 399 communicate with another node, you need to know its address, and that address 400 must be unique within the network segment. This requires coordination, either 401 through manual assignment, DHCP servers, or other allocation mechanisms.</p> 402 <p>Reticulum replaces addresses with <strong>destinations</strong>. A destination is identified by a 16-byte 403 hash (128 bits) derived from a SHA-256 hash of the destination’s identifying 404 characteristics. This hash serves as the address on the network. On the network, it 405 is represented in binary, but when displayed to human users, it will usually look something like 406 this <code class="docutils literal notranslate"><span class="pre"><13425ec15b621c1d928589718000d814></span></code>.</p> 407 <p>The critical difference is that <em>any node can generate as many destinations as it 408 needs, without coordination</em>. A destination’s uniqueness is guaranteed by the 409 collision resistance of SHA-256 and the inclusion of the node’s public key in the 410 hash calculation. Two nodes can both use the destination name 411 <code class="docutils literal notranslate"><span class="pre">messenger.user.inbox</span></code>, but they will have different destination hashes because 412 their public keys differ. Both can coexist on the same network without conflict.</p> 413 <p>This has profound implications for network design:</p> 414 <ul class="simple"> 415 <li><p><strong>No address allocation planning:</strong> You never need to reserve address ranges, 416 plan subnets, or coordinate with other network operators. Nodes simply generate 417 destinations and announce them.</p></li> 418 <li><p><strong>Global portability:</strong> A destination is not tied to a physical location or 419 network segment. A node can move its destinations across interfaces, mediums, 420 or even between entirely separate Reticulum networks simply by sending an 421 announce on the new medium.</p></li> 422 <li><p><strong>Implicit authentication:</strong> Because destinations are bound to public keys, 423 communication to a destination is inherently cryptographically authenticated. 424 Only the holder of the corresponding private key can decrypt and respond to 425 traffic addressed to that destination. This also makes application-level 426 authentication <em>much</em> simpler, since it can directly use the foundational 427 identity verification built into the core networking layer.</p></li> 428 <li><p><strong>Identity abstraction:</strong> A single Reticulum Identity can create multiple 429 destinations. This allows a single entity (a person, a device, a service) to 430 present multiple endpoints without needing multiple cryptographic keypairs.</p></li> 431 </ul> 432 </section> 433 <section id="transport-nodes-and-instances"> 434 <h3>Transport Nodes and Instances<a class="headerlink" href="#transport-nodes-and-instances" title="Link to this heading">¶</a></h3> 435 <p>Reticulum distinguishes between two types of nodes: <strong>Instances</strong> 436 and <strong>Transport Nodes</strong>. Every node running Reticulum is an Instance, but not 437 every Instance is a Transport Node.</p> 438 <p>A <strong>Reticulum Instance</strong> is any system running the Reticulum stack. It can create 439 destinations, send and receive packets, establish links, and communicate with 440 other nodes. It can also host destinations that are connectable for <em>anyone</em> else 441 in the network. This means you can easily host globally available services from 442 any location, including your home or office. Network-wide, global connectivity 443 for all destinations is guaranteed, as long as there is <em>some</em> physical way to 444 actually transport the packets. Instances are the default state and are appropriate for most end-user devices, 445 such as phones, laptops, sensors, or any device that primarily consumes network services.</p> 446 <p>A <strong>Transport Node</strong> is an Instance that has been explicitly configured to 447 participate in network-wide transport. Transport nodes forward packets across 448 hops, propagate announces, maintain path tables, and serve path requests on 449 behalf of other nodes. When a destination sends an announce, Transport Nodes 450 receive it, remember the path, and rebroadcast it to other interfaces. When a node 451 needs to reach a destination it doesn’t have a path for, Transport Nodes help 452 resolve the path through the network.</p> 453 <p>Even devices hosting services or serving content should probably just be configured 454 as instances, and themselves connect to wider networks via a Transport Node. 455 In some situations, this may not be practical though, and as an example, it is 456 entirely viable to host a personal Transport Node on a Raspberry Pi, while it 457 is at the same time running an LXMF propagation node, and hosting your personal 458 site or files over Reticulum.</p> 459 <p>The distinction is important. <strong>Not</strong> every node should be a Transport Node:</p> 460 <ul class="simple"> 461 <li><p><strong>Resource consumption:</strong> Transport nodes maintain path tables, process 462 announces, and forward traffic. This requires memory and CPU resources that 463 may be limited on low-powered devices.</p></li> 464 <li><p><strong>Stability requirements:</strong> Transport nodes contribute to network convergence. 465 If Transport Nodes frequently go offline, path tables become stale and 466 convergence suffers. Stable, always-on nodes make better Transport Nodes.</p></li> 467 <li><p><strong>Bandwidth considerations:</strong> Transport nodes process and rebroadcast network 468 maintenance traffic. On very low-bandwidth mediums, having too many Transport 469 Nodes will consume capacity that should be used for actual data.</p></li> 470 </ul> 471 <p>In practice, a network typically has a relatively small number of Transport Nodes 472 strategically placed to provide coverage and connectivity. End-user devices run 473 as Instances, connecting through nearby Transport Nodes to reach the wider network. 474 This pattern mirrors traditional networking where routers forward traffic while 475 end hosts simply consume connectivity, but with the crucial difference that any 476 node <em>can</em> become a router if needed, and the decision is yours to make based on 477 your network’s requirements.</p> 478 <p>Transport nodes also function as distributed cryptographic keystores. When a 479 destination announces itself, Transport Nodes cache the public key and destination 480 information. Other nodes can request unknown public keys from the network, and 481 Transport Nodes respond with the cached information. This eliminates the need for 482 a central directory service while ensuring that public keys remain available 483 throughout the network.</p> 484 </section> 485 <section id="trustless-networking"> 486 <h3>Trustless Networking<a class="headerlink" href="#trustless-networking" title="Link to this heading">¶</a></h3> 487 <p>Traditional network security models assume high levels of trust at 488 specific layers. You might trust your ISP to deliver packets without inspection, 489 or trust your VPN provider to handle your traffic, or trust the network 490 administrator to configure firewalls appropriately. These trust relationships 491 create vulnerabilities and dependencies.</p> 492 <p>Reticulum is designed to function in <strong>open, trustless environments</strong>. This 493 means the protocol makes no assumptions about the trustworthiness of the network 494 infrastructure, the other participants, or the transport mediums. Every aspect 495 of communication is secured cryptographically:</p> 496 <ul class="simple"> 497 <li><p><strong>Traffic encryption:</strong> All traffic to single destinations is encrypted using 498 ephemeral keys.</p></li> 499 <li><p><strong>Source anonymity:</strong> Reticulum packets do not include source addresses. 500 An observer intercepting a packet cannot determine who sent it, only who it is 501 addressed to (unless IFAC is enabled, in which case nothing can be determined). 502 This provides initiator anonymity by default.</p></li> 503 <li><p><strong>Path verification:</strong> The announce mechanism includes cryptographic signatures that 504 prove the authenticity of destination announcements.</p></li> 505 <li><p><strong>Unforgeable delivery confirmations:</strong> When a destination proves receipt of a 506 packet, the proof is signed with the destination’s identity key. This prevents 507 false acknowledgments and ensures reliable delivery verification.</p></li> 508 <li><p><strong>Interface authentication:</strong> When using Interface Access Codes (IFAC), packets 509 on authenticated interfaces carry signatures derived from a shared secret. Only 510 nodes with the correct network name and passphrase can generate valid packets, allowing creation 511 of virtual private networks on shared mediums.</p></li> 512 </ul> 513 <p>The trustless design has important consequences for network design:</p> 514 <ul class="simple"> 515 <li><p><strong>Open-access networks are viable:</strong> You can build networks that anyone can 516 join without pre-approval. Because traffic is encrypted and authenticated end- 517 to-end, participants cannot interfere with each other’s private communication, 518 even if they share the same transport infrastructure.</p></li> 519 <li><p><strong>No traffic inspection or prioritization:</strong> Because traffic contents and 520 sources are opaque to intermediate nodes, there is no mechanism for filtering, 521 prioritizing, or throttling traffic based on its type or origin. All traffic 522 is treated equally. From a neutrality perspective, this is a feature.</p></li> 523 <li><p><strong>Adversarial resilience:</strong> The network can operate even if some nodes are 524 malicious or controlled by adversaries. While a malicious Transport Node could 525 refuse to forward certain traffic or drop packets, it cannot decrypt, modify, 526 or impersonate legitimate traffic. Redundant paths and multiple Transport Nodes 527 mitigate the impact of malicious nodes.</p></li> 528 </ul> 529 <p>Of course, you can also create closed networks. Interface Access 530 Codes allow you to restrict participation on specific interfaces. Network 531 Identities enable you to verify that discovered interfaces belong to trusted 532 operators. Blackhole management lets you block malicious identities. Reticulum 533 provides both the tools for open networks and the controls for closed ones. The 534 choice is yours based on your requirements.</p> 535 </section> 536 <section id="heterogeneous-connectivity"> 537 <h3>Heterogeneous Connectivity<a class="headerlink" href="#heterogeneous-connectivity" title="Link to this heading">¶</a></h3> 538 <p>In conventional networking, mixing different transport mediums typically requires 539 gateways, translation layers, and careful configuration. A WiFi network doesn’t 540 natively interoperate with a packet radio network without additional infrastructure, 541 and you can’t just download a car over a serial port, or send an encrypted message 542 in a QR code.</p> 543 <p>Reticulum treats <strong>heterogeneity as a core premise</strong>. The protocol is designed 544 to seamlessly mix mediums with vastly different characteristics:</p> 545 <ul class="simple"> 546 <li><p><strong>Bandwidth:</strong> LoRa links operating at a few hundred bits per second can 547 interconnect with gigabit Ethernet backbones. Reticulum automatically manages 548 the flow of information, prioritizing local traffic on slow segments while 549 allowing global convergence.</p></li> 550 <li><p><strong>Latency:</strong> Satellite links with multi-second latency can coexist with local 551 links measured in milliseconds. The transport system handles timing, asynchronous 552 delivery and retransmissions transparently.</p></li> 553 <li><p><strong>Topology:</strong> Point-to-point microwave links, broadcast radio networks, 554 switched Ethernet fabrics, and virtual tunnels over the Internet can all be 555 part of the same Reticulum network.</p></li> 556 <li><p><strong>Reliability:</strong> Intermittent connections that come and go (such as mobile 557 devices or opportunistic radio contacts) can participate alongside always-on 558 infrastructure. Reticulum gracefully handles link loss and reconnection.</p></li> 559 </ul> 560 <p>This heterogeneity is achieved through several design elements:</p> 561 <ul class="simple"> 562 <li><p><strong>Expandable, medium-agnostic interface system:</strong> Reticulum communicates with the physical 563 world through interface modules. Adding support for a new medium is a matter 564 of implementing an interface class. The protocol itself remains unchanged.</p></li> 565 <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>, 566 <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 567 the wider network based on their characteristics and role.</p></li> 568 <li><p><strong>Announce propagation rules:</strong> Announces are forwarded between interfaces 569 according to rules that account for bandwidth limitations and interface modes. 570 Slow segments are not overwhelmed by traffic from fast segments.</p></li> 571 <li><p><strong>Local traffic prioritization:</strong> When bandwidth is constrained, Reticulum 572 prioritizes announces for nearby destinations. This ensures that local 573 connectivity remains functional even when global convergence is incomplete.</p></li> 574 </ul> 575 <p>For network designers, this means you are free to use whatever mediums are 576 available, affordable, or appropriate for your situation. You might use LoRa for 577 wide-area low-bandwidth coverage, WiFi for local high-capacity links, I2P for 578 anonymous Internet connectivity, and Ethernet for infrastructure backhauls, all 579 within the same network. Reticulum handles the translation and coordination 580 automatically.</p> 581 <p>The key design consideration is not whether different mediums can work together 582 (they can), but <strong>how</strong> they should work together based on your goals. A node 583 with multiple interfaces spanning heterogeneous mediums needs to be configured 584 with appropriate interface modes so that traffic flows efficiently. A gateway 585 connecting a slow LoRa segment to a fast Internet backbone should be configured 586 differently than a mobile device roaming between radio cells.</p> 587 </section> 588 </section> 589 </section> 590 591 </article> 592 </div> 593 <footer> 594 595 <div class="related-pages"> 596 <a class="next-page" href="support.html"> 597 <div class="page-info"> 598 <div class="context"> 599 <span>Next</span> 600 </div> 601 <div class="title">Support Reticulum</div> 602 </div> 603 <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> 604 </a> 605 <a class="prev-page" href="interfaces.html"> 606 <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> 607 <div class="page-info"> 608 <div class="context"> 609 <span>Previous</span> 610 </div> 611 612 <div class="title">Configuring Interfaces</div> 613 614 </div> 615 </a> 616 </div> 617 <div class="bottom-of-page"> 618 <div class="left-details"> 619 <div class="copyright"> 620 Copyright © 2025, Mark Qvist 621 </div> 622 Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 623 <a href="https://github.com/pradyunsg/furo">Furo</a> 624 625 </div> 626 <div class="right-details"> 627 628 </div> 629 </div> 630 631 </footer> 632 </div> 633 <aside class="toc-drawer"> 634 635 636 <div class="toc-sticky toc-scroll"> 637 <div class="toc-title-container"> 638 <span class="toc-title"> 639 On this page 640 </span> 641 </div> 642 <div class="toc-tree-container"> 643 <div class="toc-tree"> 644 <ul> 645 <li><a class="reference internal" href="#">Building Networks</a><ul> 646 <li><a class="reference internal" href="#concepts-overview">Concepts & Overview</a><ul> 647 <li><a class="reference internal" href="#introductory-considerations">Introductory Considerations</a></li> 648 <li><a class="reference internal" href="#destinations-not-addresses">Destinations, Not Addresses</a></li> 649 <li><a class="reference internal" href="#transport-nodes-and-instances">Transport Nodes and Instances</a></li> 650 <li><a class="reference internal" href="#trustless-networking">Trustless Networking</a></li> 651 <li><a class="reference internal" href="#heterogeneous-connectivity">Heterogeneous Connectivity</a></li> 652 </ul> 653 </li> 654 </ul> 655 </li> 656 </ul> 657 658 </div> 659 </div> 660 </div> 661 662 663 </aside> 664 </div> 665 </div><script src="_static/documentation_options.js?v=cb7bf70b"></script> 666 <script src="_static/doctools.js?v=9bcbadda"></script> 667 <script src="_static/sphinx_highlight.js?v=dc90522c"></script> 668 <script src="_static/scripts/furo.js?v=46bd48cc"></script> 669 <script src="_static/clipboard.min.js?v=a7894cd8"></script> 670 <script src="_static/copybutton.js?v=f281be69"></script> 671 </body> 672 </html>