networks.html
1 <!doctype html> 2 <html class="no-js" lang="en"> 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="Code Examples" href="examples.html" /><link rel="prev" title="Configuring Interfaces" href="interfaces.html" /> 7 8 <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29.dev1"/> 9 <title>Building Networks - Reticulum Network Stack 1.0.0 documentation</title> 10 <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> 11 <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" /> 12 <link rel="stylesheet" type="text/css" href="_static/copybutton.css" /> 13 <link rel="stylesheet" type="text/css" href="_static/styles/furo-extensions.css?digest=30d1aed668e5c3a91c3e3bf6a60b675221979f0e" /> 14 <link rel="stylesheet" type="text/css" href="_static/custom.css" /> 15 16 17 18 19 <style> 20 body { 21 --color-code-background: #f8f8f8; 22 --color-code-foreground: black; 23 24 } 25 @media not print { 26 body[data-theme="dark"] { 27 --color-code-background: #202020; 28 --color-code-foreground: #d0d0d0; 29 --color-background-primary: #202b38; 30 --color-background-secondary: #161f27; 31 --color-foreground-primary: #dbdbdb; 32 --color-foreground-secondary: #a9b1ba; 33 --color-brand-primary: #41adff; 34 --color-background-hover: #161f27; 35 --color-api-name: #ffbe85; 36 --color-api-pre-name: #efae75; 37 38 } 39 @media (prefers-color-scheme: dark) { 40 body:not([data-theme="light"]) { 41 --color-code-background: #202020; 42 --color-code-foreground: #d0d0d0; 43 --color-background-primary: #202b38; 44 --color-background-secondary: #161f27; 45 --color-foreground-primary: #dbdbdb; 46 --color-foreground-secondary: #a9b1ba; 47 --color-brand-primary: #41adff; 48 --color-background-hover: #161f27; 49 --color-api-name: #ffbe85; 50 --color-api-pre-name: #efae75; 51 52 } 53 } 54 } 55 </style></head> 56 <body> 57 58 <script> 59 document.body.dataset.theme = localStorage.getItem("theme") || "auto"; 60 </script> 61 62 63 <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> 64 <symbol id="svg-toc" viewBox="0 0 24 24"> 65 <title>Contents</title> 66 <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024"> 67 <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"/> 68 </svg> 69 </symbol> 70 <symbol id="svg-menu" viewBox="0 0 24 24"> 71 <title>Menu</title> 72 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 73 stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu"> 74 <line x1="3" y1="12" x2="21" y2="12"></line> 75 <line x1="3" y1="6" x2="21" y2="6"></line> 76 <line x1="3" y1="18" x2="21" y2="18"></line> 77 </svg> 78 </symbol> 79 <symbol id="svg-arrow-right" viewBox="0 0 24 24"> 80 <title>Expand</title> 81 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 82 stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right"> 83 <polyline points="9 18 15 12 9 6"></polyline> 84 </svg> 85 </symbol> 86 <symbol id="svg-sun" viewBox="0 0 24 24"> 87 <title>Light mode</title> 88 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 89 stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="feather-sun"> 90 <circle cx="12" cy="12" r="5"></circle> 91 <line x1="12" y1="1" x2="12" y2="3"></line> 92 <line x1="12" y1="21" x2="12" y2="23"></line> 93 <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> 94 <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> 95 <line x1="1" y1="12" x2="3" y2="12"></line> 96 <line x1="21" y1="12" x2="23" y2="12"></line> 97 <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> 98 <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> 99 </svg> 100 </symbol> 101 <symbol id="svg-moon" viewBox="0 0 24 24"> 102 <title>Dark mode</title> 103 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 104 stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon"> 105 <path stroke="none" d="M0 0h24v24H0z" fill="none" /> 106 <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" /> 107 </svg> 108 </symbol> 109 <symbol id="svg-sun-half" viewBox="0 0 24 24"> 110 <title>Auto light/dark mode</title> 111 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 112 stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-shadow"> 113 <path stroke="none" d="M0 0h24v24H0z" fill="none"/> 114 <circle cx="12" cy="12" r="9" /> 115 <path d="M13 12h5" /> 116 <path d="M13 15h4" /> 117 <path d="M13 18h1" /> 118 <path d="M13 9h4" /> 119 <path d="M13 6h1" /> 120 </svg> 121 </symbol> 122 </svg> 123 124 <input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation"> 125 <input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc"> 126 <label class="overlay sidebar-overlay" for="__navigation"> 127 <div class="visually-hidden">Hide navigation sidebar</div> 128 </label> 129 <label class="overlay toc-overlay" for="__toc"> 130 <div class="visually-hidden">Hide table of contents sidebar</div> 131 </label> 132 133 134 135 <div class="page"> 136 <header class="mobile-header"> 137 <div class="header-left"> 138 <label class="nav-overlay-icon" for="__navigation"> 139 <div class="visually-hidden">Toggle site navigation sidebar</div> 140 <i class="icon"><svg><use href="#svg-menu"></use></svg></i> 141 </label> 142 </div> 143 <div class="header-center"> 144 <a href="index.html"><div class="brand">Reticulum Network Stack 1.0.0 documentation</div></a> 145 </div> 146 <div class="header-right"> 147 <div class="theme-toggle-container theme-toggle-header"> 148 <button class="theme-toggle"> 149 <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div> 150 <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg> 151 <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg> 152 <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg> 153 </button> 154 </div> 155 <label class="toc-overlay-icon toc-header-icon" for="__toc"> 156 <div class="visually-hidden">Toggle table of contents sidebar</div> 157 <i class="icon"><svg><use href="#svg-toc"></use></svg></i> 158 </label> 159 </div> 160 </header> 161 <aside class="sidebar-drawer"> 162 <div class="sidebar-container"> 163 164 <div class="sidebar-sticky"><a class="sidebar-brand centered" href="index.html"> 165 166 <div class="sidebar-logo-container"> 167 <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/> 168 </div> 169 170 <span class="sidebar-brand-text">Reticulum Network Stack 1.0.0 documentation</span> 171 172 </a><form class="sidebar-search-container" method="get" action="search.html" role="search"> 173 <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search"> 174 <input type="hidden" name="check_keywords" value="yes"> 175 <input type="hidden" name="area" value="default"> 176 </form> 177 <div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree"> 178 <ul class="current"> 179 <li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li> 180 <li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li> 181 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li> 182 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li> 183 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li> 184 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li> 185 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Building Networks</a></li> 186 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li> 187 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li> 188 </ul> 189 <ul> 190 <li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li> 191 </ul> 192 193 </div> 194 </div> 195 196 </div> 197 198 </div> 199 </aside> 200 <div class="main"> 201 <div class="content"> 202 <div class="article-container"> 203 <a href="#" class="back-to-top muted-link"> 204 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"> 205 <path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path> 206 </svg> 207 <span>Back to top</span> 208 </a> 209 <div class="content-icon-container"> 210 <div class="theme-toggle-container theme-toggle-content"> 211 <button class="theme-toggle"> 212 <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div> 213 <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg> 214 <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg> 215 <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg> 216 </button> 217 </div> 218 <label class="toc-overlay-icon toc-content-icon" for="__toc"> 219 <div class="visually-hidden">Toggle table of contents sidebar</div> 220 <i class="icon"><svg><use href="#svg-toc"></use></svg></i> 221 </label> 222 </div> 223 <article role="main"> 224 <section id="building-networks"> 225 <span id="networks-main"></span><h1>Building Networks<a class="headerlink" href="#building-networks" title="Permalink to this heading">#</a></h1> 226 <p>This chapter will provide you with the knowledge needed to build networks with 227 Reticulum, which can often be easier than using traditional stacks, since you 228 don’t have to worry about coordinating addresses, subnets and routing for an 229 entire network that you might not know how will evolve in the future. With 230 Reticulum, you can simply add more segments to your network when it becomes 231 necessary, and Reticulum will handle the convergence of the entire network 232 automatically.</p> 233 <section id="concepts-overview"> 234 <h2>Concepts & Overview<a class="headerlink" href="#concepts-overview" title="Permalink to this heading">#</a></h2> 235 <p>There are important points that need to be kept in mind when building networks 236 with Reticulum:</p> 237 <blockquote> 238 <div><ul> 239 <li><div class="line-block"> 240 <div class="line">In a Reticulum network, any node can autonomously generate as many addresses 241 (called <em>destinations</em> in Reticulum terminology) as it needs, which become 242 globally reachable to the rest of the network. There is no central point of 243 control over the address space.</div> 244 </div> 245 </li> 246 <li><div class="line-block"> 247 <div class="line">Reticulum was designed to handle both very small, and very large networks. 248 While the address space can support billions of endpoints, Reticulum is 249 also very useful when just a few devices needs to communicate.</div> 250 </div> 251 </li> 252 <li><div class="line-block"> 253 <div class="line">Low-bandwidth networks, like LoRa and packet radio, can interoperate and 254 interconnect with much larger and higher bandwidth networks without issue. 255 Reticulum automatically manages the flow of information to and from various 256 network segments, and when bandwidth is limited, local traffic is prioritised.</div> 257 </div> 258 </li> 259 <li><div class="line-block"> 260 <div class="line">Reticulum provides sender/initiator anonymity by default. There is no way 261 to filter traffic or discriminate it based on the source of the traffic.</div> 262 </div> 263 </li> 264 <li><div class="line-block"> 265 <div class="line">All traffic is encrypted using ephemeral keys generated by an Elliptic Curve 266 Diffie-Hellman key exchange on Curve25519. There is no way to inspect traffic 267 contents, and no way to prioritise or throttle certain kinds of traffic. 268 All transport and routing layers are thus completely agnostic to traffic type, 269 and will pass all traffic equally.</div> 270 </div> 271 </li> 272 <li><div class="line-block"> 273 <div class="line">Reticulum can function both with and without infrastructure. When <em>transport 274 nodes</em> are available, they can route traffic over multiple hops for other 275 nodes, and will function as a distributed cryptographic keystore. When there 276 is no transport nodes available, all nodes that are within communication range 277 can still communicate.</div> 278 </div> 279 </li> 280 <li><div class="line-block"> 281 <div class="line">Every node can become a transport node, simply by enabling it in it’s 282 configuration, but there is no need for every node on the network to be a 283 transport node. Letting every node be a transport node will in most cases 284 degrade the performance and reliability of the network.</div> 285 </div> 286 <blockquote> 287 <div><p><em>In general terms, if a node is stationary, well-connected and kept running 288 most of the time, it is a good candidate to be a transport node. For optimal 289 performance, a network should contain the amount of transport nodes that 290 provides connectivity to the intended area / topography, and not many more 291 than that.</em></p> 292 </div></blockquote> 293 </li> 294 <li><div class="line-block"> 295 <div class="line">Reticulum is designed to work reliably in open, trustless environments. This 296 means you can use it to create open-access networks, where participants can 297 join and leave in a free and unorganised manner. This property allows an 298 entirely new, and so far, mostly unexplored class of networked applications, 299 where networks, and the information flow within them can form and dissolve 300 organically.</div> 301 </div> 302 </li> 303 <li><div class="line-block"> 304 <div class="line">You can just as easily create closed networks, since Reticulum allows you to 305 add authentication to any interface. This means you can restrict access on 306 any interface type, even when using legacy devices, such as modems. You can 307 also mix authenticated and open interfaces on the same system. See the 308 <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> 309 chapter of this manual for information on how to set up interface authentication.</div> 310 </div> 311 </li> 312 </ul> 313 </div></blockquote> 314 <p>Reticulum allows you to mix very different kinds of networking mediums into a 315 unified mesh, or to keep everything within one medium. You could build a “virtual 316 network” running entirely over the Internet, where all nodes communicate over TCP 317 and UDP “channels”. You could also build such a network using other already-established 318 communications channels as the underlying carrier for Reticulum.</p> 319 <p>However, most real-world networks will probably involve either some form of 320 wireless or direct hardline communications. To allow Reticulum to communicate 321 over any type of medium, you must specify it in the configuration file, by default 322 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> 323 chapter of this manual for interface configuration examples.</p> 324 <p>Any number of interfaces can be configured, and Reticulum will automatically 325 decide which are suitable to use in any given situation, depending on where 326 traffic needs to flow.</p> 327 </section> 328 <section id="example-scenarios"> 329 <h2>Example Scenarios<a class="headerlink" href="#example-scenarios" title="Permalink to this heading">#</a></h2> 330 <p>This section illustrates a few example scenarios, and how they would, in general 331 terms, be planned, implemented and configured.</p> 332 <section id="interconnected-lora-sites"> 333 <h3>Interconnected LoRa Sites<a class="headerlink" href="#interconnected-lora-sites" title="Permalink to this heading">#</a></h3> 334 <p>An organisation wants to provide communication and information services to it’s 335 members, which are located mainly in three separate areas. Three suitable hill-top 336 locations are found, where the organisation can install equipment: Site A, B and C.</p> 337 <p>Since the amount of data that needs to be exchanged between users is mainly text- 338 based, the bandwidth requirements are low, and LoRa radios are chosen to connect 339 users to the network.</p> 340 <p>Due to the hill-top locations found, there is radio line-of-sight between site A 341 and B, and also between site B and C. Because of this, the organisation does not 342 need to use the Internet to interconnect the sites, but purchases four Point-to-Point 343 WiFi based radios for interconnecting the sites.</p> 344 <p>At each site, a Raspberry Pi is installed to function as a gateway. A LoRa radio 345 is connected to the Pi with a USB cable, and the WiFi radio is connected to the 346 Ethernet port of the Pi. At site B, two WiFi radios are needed to be able to reach 347 both site A and site C, so an extra Ethernet adapter is connected to the Pi in 348 this location.</p> 349 <p>Once the hardware has been installed, Reticulum is installed on all the Pis, and at 350 site A and C, one interface is added for the LoRa radio, as well as one for the WiFi 351 radio. At site B, an interface for the LoRa radio, and one interface for each WiFi 352 radio is added to the Reticulum configuration file. The transport node option is 353 enabled in the configuration of all three gateways.</p> 354 <p>The network is now operational, and ready to serve users across all three areas. 355 The organisation prepares a LoRa radio that is supplied to the end users, along 356 with a Reticulum configuration file, that contains the right parameters for 357 communicating with the LoRa radios installed at the gateway sites.</p> 358 <p>Once users connect to the network, anyone will be able to communicate with anyone 359 else across all three sites.</p> 360 </section> 361 <section id="bridging-over-the-internet"> 362 <h3>Bridging Over the Internet<a class="headerlink" href="#bridging-over-the-internet" title="Permalink to this heading">#</a></h3> 363 <p>As the organisation grows, several new communities form in places too far away 364 from the core network to be reachable over WiFi links. New gateways similar to those 365 previously installed are set up for the new communities at the new sites D and E, but 366 they are islanded from the core network, and only serve the local users.</p> 367 <p>After investigating the options, it is found that it is possible to install an 368 Internet connection at site A, and an interface on the Internet connection is 369 configured for Reticulum on the Raspberry Pi at site A.</p> 370 <p>A member of the organisation at site D, named Dori, is willing to help by sharing 371 the Internet connection she already has in her home, and is able to leave a Raspberry 372 Pi running. A new Reticulum interface is configured on her Pi, connecting to the newly 373 enabled Internet interface on the gateway at site A. Dori is now connected to both 374 the nodes at her own local site (through the hill-top LoRa gateway), and all the 375 combined users of sites A, B and C. She then enables transport on her node, and 376 traffic from site D can now reach everyone at site A, B and C, and vice versa.</p> 377 </section> 378 <section id="growth-and-convergence"> 379 <h3>Growth and Convergence<a class="headerlink" href="#growth-and-convergence" title="Permalink to this heading">#</a></h3> 380 <p>As the organisation grows, more gateways are added to keep up with the growing user 381 base. Some local gateways even add VHF radios and packet modems to reach outlying users 382 and communities that are out of reach for the LoRa radios and WiFi backhauls.</p> 383 <p>As more sites, gateways and users are connected, the amount of coordination required 384 is kept to a minimum. If one community wants to add connectivity to the next one 385 over, it can simply be done without having to involve everyone or coordinate address 386 space or routing tables.</p> 387 <p>With the added geographical coverage, the operators at site A one day find that 388 the original internet bridged interfaces are no longer utilised. The network has 389 converged to be completely self-connected, and the sites that were once poorly 390 connected outliers are now an integral part of the network.</p> 391 </section> 392 </section> 393 </section> 394 395 </article> 396 </div> 397 <footer> 398 399 <div class="related-pages"> 400 <a class="next-page" href="examples.html"> 401 <div class="page-info"> 402 <div class="context"> 403 <span>Next</span> 404 </div> 405 <div class="title">Code Examples</div> 406 </div> 407 <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> 408 </a> 409 <a class="prev-page" href="interfaces.html"> 410 <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> 411 <div class="page-info"> 412 <div class="context"> 413 <span>Previous</span> 414 </div> 415 416 <div class="title">Configuring Interfaces</div> 417 418 </div> 419 </a> 420 </div> 421 <div class="bottom-of-page"> 422 <div class="left-details"> 423 <div class="copyright"> 424 Copyright © 2023, Mark Qvist 425 </div> 426 Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 427 <a href="https://github.com/pradyunsg/furo">Furo</a> 428 429 </div> 430 <div class="right-details"> 431 <div class="icons"> 432 433 </div> 434 </div> 435 </div> 436 437 </footer> 438 </div> 439 <aside class="toc-drawer"> 440 441 442 <div class="toc-sticky toc-scroll"> 443 <div class="toc-title-container"> 444 <span class="toc-title"> 445 On this page 446 </span> 447 </div> 448 <div class="toc-tree-container"> 449 <div class="toc-tree"> 450 <ul> 451 <li><a class="reference internal" href="#">Building Networks</a><ul> 452 <li><a class="reference internal" href="#concepts-overview">Concepts & Overview</a></li> 453 <li><a class="reference internal" href="#example-scenarios">Example Scenarios</a><ul> 454 <li><a class="reference internal" href="#interconnected-lora-sites">Interconnected LoRa Sites</a></li> 455 <li><a class="reference internal" href="#bridging-over-the-internet">Bridging Over the Internet</a></li> 456 <li><a class="reference internal" href="#growth-and-convergence">Growth and Convergence</a></li> 457 </ul> 458 </li> 459 </ul> 460 </li> 461 </ul> 462 463 </div> 464 </div> 465 </div> 466 467 468 </aside> 469 </div> 470 </div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> 471 <script src="_static/jquery.js"></script> 472 <script src="_static/underscore.js"></script> 473 <script src="_static/_sphinx_javascript_frameworks_compat.js"></script> 474 <script src="_static/doctools.js"></script> 475 <script src="_static/sphinx_highlight.js"></script> 476 <script src="_static/scripts/furo.js"></script> 477 <script src="_static/clipboard.min.js"></script> 478 <script src="_static/copybutton.js"></script> 479 </body> 480 </html>