gettingstartedfast.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="Zen of Reticulum" href="zen.html"><link rel="prev" title="What is Reticulum?" href="whatis.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>Getting Started Fast - 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 current current-page"><a class="current reference internal" href="#">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"><a class="reference internal" href="networks.html">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="getting-started-fast"> 264 <h1>Getting Started Fast<a class="headerlink" href="#getting-started-fast" title="Link to this heading">¶</a></h1> 265 <p>The best way to get started with the Reticulum Network Stack depends on what 266 you want to do. This guide will outline sensible starting paths for different 267 scenarios.</p> 268 <section id="standalone-reticulum-installation"> 269 <h2>Standalone Reticulum Installation<a class="headerlink" href="#standalone-reticulum-installation" title="Link to this heading">¶</a></h2> 270 <p>If you simply want to install Reticulum and related utilities on a system, 271 the easiest way is via the <code class="docutils literal notranslate"><span class="pre">pip</span></code> package manager:</p> 272 <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>rns 273 </pre></div> 274 </div> 275 <p>If you do not already have pip installed, you can install it using the package manager 276 of your system with a command like <code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">apt</span> <span class="pre">install</span> <span class="pre">python3-pip</span></code>, 277 <code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">pamac</span> <span class="pre">install</span> <span class="pre">python-pip</span></code> or similar.</p> 278 <p>You can also dowload the Reticulum release wheels from GitHub, or other release channels, 279 and install them offline using <code class="docutils literal notranslate"><span class="pre">pip</span></code>:</p> 280 <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>./rns-1.1.2-py3-none-any.whl 281 </pre></div> 282 </div> 283 <p>On platforms that limit user package installation via <code class="docutils literal notranslate"><span class="pre">pip</span></code>, you may need to manually 284 allow this using the <code class="docutils literal notranslate"><span class="pre">--break-system-packages</span></code> command line flag when installing. This 285 will not actually break any packages, unless you have installed Reticulum directly via 286 your operating system’s package manager.</p> 287 <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>rns<span class="w"> </span>--break-system-packages 288 </pre></div> 289 </div> 290 <p>For more detailed installation instructions, please see the 291 <a class="reference internal" href="#install-guides"><span class="std std-ref">Platform-Specific Install Notes</span></a> section.</p> 292 <p>After installation is complete, it might be helpful to refer to the 293 <a class="reference internal" href="using.html#using-main"><span class="std std-ref">Using Reticulum on Your System</span></a> chapter.</p> 294 <section id="resolving-dependency-installation-issues"> 295 <h3>Resolving Dependency & Installation Issues<a class="headerlink" href="#resolving-dependency-installation-issues" title="Link to this heading">¶</a></h3> 296 <p>On some platforms, there may not be binary packages available for all dependencies, and 297 <code class="docutils literal notranslate"><span class="pre">pip</span></code> installation may fail with an error message. In these cases, the issue can usually 298 be resolved by installing the development essentials packages for your platform:</p> 299 <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># Debian / Ubuntu / Derivatives</span> 300 sudo<span class="w"> </span>apt<span class="w"> </span>install<span class="w"> </span>build-essential 301 302 <span class="c1"># Arch / Manjaro / Derivatives</span> 303 sudo<span class="w"> </span>pamac<span class="w"> </span>install<span class="w"> </span>base-devel 304 305 <span class="c1"># Fedora</span> 306 sudo<span class="w"> </span>dnf<span class="w"> </span>groupinstall<span class="w"> </span><span class="s2">"Development Tools"</span><span class="w"> </span><span class="s2">"Development Libraries"</span> 307 </pre></div> 308 </div> 309 <p>With the base development packages installed, <code class="docutils literal notranslate"><span class="pre">pip</span></code> should be able to compile any missing 310 dependencies from source, and complete installation even on platforms that don’t have pre- 311 compiled packages available.</p> 312 </section> 313 </section> 314 <section id="try-using-a-reticulum-based-program"> 315 <h2>Try Using a Reticulum-based Program<a class="headerlink" href="#try-using-a-reticulum-based-program" title="Link to this heading">¶</a></h2> 316 <p>If you simply want to try using a program built with Reticulum, a <a class="reference internal" href="software.html#software-main"><span class="std std-ref">range of different 317 programs</span></a> exist that allow basic communication and a various other useful functions, 318 even over extremely low-bandwidth Reticulum networks.</p> 319 </section> 320 <section id="using-the-included-utilities"> 321 <h2>Using the Included Utilities<a class="headerlink" href="#using-the-included-utilities" title="Link to this heading">¶</a></h2> 322 <p>Reticulum comes with a range of included utilities that make it easier to 323 manage your network, check connectivity and make Reticulum available to other 324 programs on your system.</p> 325 <p>You can use <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> to run Reticulum as a background or foreground service, 326 and the <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code>, <code class="docutils literal notranslate"><span class="pre">rnpath</span></code> and <code class="docutils literal notranslate"><span class="pre">rnprobe</span></code> utilities to view and query 327 network status and connectivity.</p> 328 <p>To learn more about these utility programs, have a look at the 329 <a class="reference internal" href="using.html#using-main"><span class="std std-ref">Using Reticulum on Your System</span></a> chapter of this manual.</p> 330 </section> 331 <section id="creating-a-network-with-reticulum"> 332 <h2>Creating a Network With Reticulum<a class="headerlink" href="#creating-a-network-with-reticulum" title="Link to this heading">¶</a></h2> 333 <p>To create a network, you will need to specify one or more <em>interfaces</em> for 334 Reticulum to use. This is done in the Reticulum configuration file, which by 335 default is located at <code class="docutils literal notranslate"><span class="pre">~/.reticulum/config</span></code>. You can get an example 336 configuration file with all options via <code class="docutils literal notranslate"><span class="pre">rnsd</span> <span class="pre">--exampleconfig</span></code>.</p> 337 <p>When Reticulum is started for the first time, it will create a default 338 configuration file, with one active interface. This default interface uses 339 your existing Ethernet and WiFi networks (if any), and only allows you to 340 communicate with other Reticulum peers within your local broadcast domains.</p> 341 <p>To communicate further, you will have to add one or more interfaces. The default 342 configuration includes a number of examples, ranging from using TCP over the 343 internet, to LoRa and Packet Radio interfaces.</p> 344 <p>With Reticulum, you only need to configure what interfaces you want to communicate 345 over. There is no need to configure address spaces, subnets, routing tables, 346 or other things you might be used to from other network types.</p> 347 <p>Once Reticulum knows which interfaces it should use, it will automatically 348 discover topography and configure transport of data to any destinations it 349 knows about.</p> 350 <p>In situations where you already have an established WiFi or Ethernet network, and 351 many devices that want to utilise the same external Reticulum network paths (for example over 352 LoRa), it will often be sufficient to let one system act as a Reticulum gateway, by 353 adding any external interfaces to the configuration of this system, and then enabling transport on it. Any 354 other device on your local WiFi will then be able to connect to this wider Reticulum 355 network just using the default (<a class="reference internal" href="interfaces.html#interfaces-auto"><span class="std std-ref">AutoInterface</span></a>) configuration.</p> 356 <p>Possibly, the examples in the config file are enough to get you started. If 357 you want more information, you can read the <a class="reference internal" href="networks.html#networks-main"><span class="std std-ref">Building Networks</span></a> 358 and <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Interfaces</span></a> chapters of this manual, but most importantly, 359 start with reading the next section, <a class="reference internal" href="#bootstrapping-connectivity"><span class="std std-ref">Bootstrapping Connectivity</span></a>, 360 as this provides the most essential understanding of how to ensure reliable 361 connectivity with a minimum of maintenance.</p> 362 </section> 363 <section id="bootstrapping-connectivity"> 364 <span id="id1"></span><h2>Bootstrapping Connectivity<a class="headerlink" href="#bootstrapping-connectivity" title="Link to this heading">¶</a></h2> 365 <p>Reticulum is not a service you subscribe to, nor is it a single global network you “join”. It is a <em>networking stack</em>; a toolkit for building communications systems that align with your specific values, requirements, and operational environment. The way you choose to connect to other Reticulum peers is entirely your own choice.</p> 366 <p>One of the most powerful aspects of Reticulum is that it provides a multitude of tools to establish, maintain, and optimize connectivity. You can use these tools in isolation or combine them in complex configurations to achieve a vast array of goals.</p> 367 <p>Whether your aim is to create a completely private, air-gapped network for your family; to build a resilient community mesh that survives infrastructure collapse; to connect far and wide to as many nodes as possible; or simply to maintain a reliable, encrypted link to a specific organization you care about, Reticulum provides the mechanisms to make it happen.</p> 368 <p>There is no “right” or “wrong” way to build a Reticulum network, and you don’t need to be a network engineer just to get started. If the information flows in the way you intend, and your privacy and security requirements are met, your configuration is a success. Reticulum is designed to make the most challenging and difficult scenarios attainable, even when other networking technologies fail.</p> 369 <section id="finding-your-way"> 370 <h3>Finding Your Way<a class="headerlink" href="#finding-your-way" title="Link to this heading">¶</a></h3> 371 <p>When you first start using Reticulum, you need a way to obtain connectivity with the peers you want to communicate with - the process of <em>bootstrapping connectivity</em>.</p> 372 <div class="admonition important"> 373 <p class="admonition-title">Important</p> 374 <p>A common mistake in modern networking is the reliance on a few centralized, hard-coded entrypoints. If every user simply connects to the same list of public IP addresses found on a website, the network becomes brittle, centralized, and ultimately fails to deliver on the promise of decentralization and resilience. You have a responsibility here.</p> 375 </div> 376 <p>Reticulum encourages the approach of <em>organic growth</em>. Instead of relying on permanent static connections to distant servers, you can use temporary bootstrap connections to continously <em>discover</em> more relevant or local infrastructure. Once discovered, your system can automatically form stronger, more direct links to these peers, and discard the temporary bootstrap links. This results in a web of connections that are geographically relevant, resilient and efficient.</p> 377 <p>It <em>is</em> possible to simply add a few public entrypoints to the <code class="docutils literal notranslate"><span class="pre">[interfaces]</span></code> section of your Reticulum configuration and be connected, but a better option is to enable <a class="reference internal" href="using.html#using-interface-discovery"><span class="std std-ref">interface discovery</span></a> and either manually select relevant, local interfaces, or enable discovered interface auto-connection.</p> 378 <p>A relevant option in this context is the <a class="reference internal" href="interfaces.html#interfaces-options"><span class="std std-ref">bootstrap only</span></a> interface option. This is an automated tool for better distributing connectivity. By enabling interface discovery and auto-connection, and marking an interface as <code class="docutils literal notranslate"><span class="pre">bootstrap_only</span></code>, you tell Reticulum to use that interface primarliy to find connectivity options, and then disconnect it once sufficient entrypoints have been discovered. This helps create a network topology that favors locality and resilience over the simple centralization caused by using only a few static entrypoints.</p> 379 <p>Good places to find interface definitions for bootstrapping connectivity are websites like 380 <a class="reference external" href="https://directory.rns.recipes/">directory.rns.recipes</a> and <a class="reference external" href="https://rmap.world/">rmap.world</a>.</p> 381 </section> 382 <section id="build-personal-infrastructure"> 383 <h3>Build Personal Infrastructure<a class="headerlink" href="#build-personal-infrastructure" title="Link to this heading">¶</a></h3> 384 <p>You do not need a datacenter to be a meaningful part of the Reticulum ecosystem. In fact, the most important nodes in the network are often the smallest ones.</p> 385 <p>We strongly encourage everyone, even home users, to think in terms of building <strong>personal infrastructure</strong>. Don’t connect every phone, tablet, and computer in your house directly to a public internet gateway. Instead, repurpose an old computer, a Raspberry Pi, or a supported router to act as your own, personal <strong>Transport Node</strong>:</p> 386 <ul class="simple"> 387 <li><p>Your local Transport Node sits in your home, connected to your WiFi and perhaps a radio interface (like an RNode).</p></li> 388 <li><p>You configure this node with a <code class="docutils literal notranslate"><span class="pre">bootstrap_only</span></code> interface (perhaps a TCP tunnel to a wider network) and enable interface discovery.</p></li> 389 <li><p>While you sleep, work, or cook, your node listens to the network. It discovers other local community members, validates their Network Identities, and automatically establishes direct links.</p></li> 390 <li><p>Your personal devices now connect to your <em>local</em> node, which is integrated into a living, breathing local mesh. Your traffic flows through local paths provided by other real people in the community rather than bouncing off a distant server.</p></li> 391 </ul> 392 <p><strong>Don’t wait for others to build the networks you want to see</strong>. Every network is important, perhaps even most so those that support individual families and persons. Once enough of this personal, local infrastructure exist, connecting them directly to each other, without traversing the public Internet, becomes inevitable.</p> 393 </section> 394 <section id="mixing-strategies"> 395 <h3>Mixing Strategies<a class="headerlink" href="#mixing-strategies" title="Link to this heading">¶</a></h3> 396 <p>There is no requirement to commit to a single strategy. The most robust setups often mix static, dynamic, and discovered interfaces.</p> 397 <ul class="simple"> 398 <li><p><strong>Static Interfaces:</strong> You maintain a permanent interface to a trusted friend or organization using a static configuration.</p></li> 399 <li><p><strong>Bootstrap Links:</strong> You connect a <code class="docutils literal notranslate"><span class="pre">bootstrap_only</span></code> interface to a public gateway on the Internet to scan for new connectable peers or to regain connectivity if your other interfaces fail.</p></li> 400 <li><p><strong>Local Wide-Area Connectivity:</strong> You run a <code class="docutils literal notranslate"><span class="pre">RNodeInterface</span></code> on a shared frequency, giving you completely self-sovereign and private wide-area access to both your own network and other Reticulum peers globally, without any “service providers” being able to control or monitor how you interact with people.</p></li> 401 </ul> 402 <p>By combining these methods, you create a system that is secure against single points of failure, adaptable to changing network conditions, and better integrated into your physical and social reality.</p> 403 </section> 404 <section id="network-health-responsibility"> 405 <h3>Network Health & Responsibility<a class="headerlink" href="#network-health-responsibility" title="Link to this heading">¶</a></h3> 406 <p>As you participate in the wider networks you discover and build, you will inevitably encounter peers that are misconfigured, malicious, or simply broken. To protect your resources and those of your local peers, you can utilize the <a class="reference internal" href="using.html#using-blackhole-management"><span class="std std-ref">Blackhole Management</span></a> system.</p> 407 <p>Whether you manually block a spamming identity or subscribe to a blackhole list maintained by a trusted Network Identity, these tools help ensure that <em>your</em> transport capacity is used for what <em>you</em> consider legitimate communication. This keeps your local segment efficient and contributes to the health of the wider network.</p> 408 </section> 409 <section id="contributing-to-the-global-ret"> 410 <h3>Contributing to the Global Ret<a class="headerlink" href="#contributing-to-the-global-ret" title="Link to this heading">¶</a></h3> 411 <p>If you have the means to host a stable node with a public IP address, consider becoming a <a class="reference internal" href="#hosting-entrypoints"><span class="std std-ref">Public Entrypoint</span></a>. By <a class="reference internal" href="interfaces.html#interfaces-discoverable"><span class="std std-ref">publishing your interface as discoverable</span></a>, you provide a potential connection point for others, helping the network grow and reach new areas.</p> 412 <p>For guidelines on how to properly configure a public entrypoint, refer to the <a class="reference internal" href="#hosting-entrypoints"><span class="std std-ref">Hosting Public Entrypoints</span></a> section.</p> 413 </section> 414 </section> 415 <section id="connect-to-the-distributed-backbone"> 416 <h2>Connect to the Distributed Backbone<a class="headerlink" href="#connect-to-the-distributed-backbone" title="Link to this heading">¶</a></h2> 417 <p>A global, distributed backbone of Reticulum Transport Nodes is being run by volunteers from around the world. This network constitutes a heterogenous collection of both public and private nodes that form an uncoordinated, voluntary inter-networking backbone that currently provides global transport and internetworking capabilities for Reticulum.</p> 418 <p>As a good starting point, you can find interface definitions for connecting your own networks to this backbone on websites such as <a class="reference external" href="https://directory.rns.recipes/">directory.rns.recipes</a> and <a class="reference external" href="https://rmap.world/">rmap.world</a>.</p> 419 <div class="admonition tip"> 420 <p class="admonition-title">Tip</p> 421 <p>Don’t rely on just a single connection to the distributed backbone for everyday use. It is much better to have several redundant connections configured, and enable the interface discovery options, so your nodes can continously discover peering opportunities as the network evolves. Refer to the <a class="reference internal" href="#bootstrapping-connectivity"><span class="std std-ref">Bootstrapping Connectivity</span></a> section to understand the options.</p> 422 </div> 423 </section> 424 <section id="hosting-public-entrypoints"> 425 <span id="hosting-entrypoints"></span><h2>Hosting Public Entrypoints<a class="headerlink" href="#hosting-public-entrypoints" title="Link to this heading">¶</a></h2> 426 <p>If you want to help build a strong global interconnection backbone, you can host a public (or private) entry-point to a Reticulum network over the 427 Internet. This section offers some helpful pointers. Once you have set up your public entrypoint, it is a great idea to <a class="reference internal" href="interfaces.html#interfaces-discoverable"><span class="std std-ref">make it discoverable over Reticulum</span></a>.</p> 428 <p>You will need a machine, physical or virtual with a public IP address, that can be reached by other devices on the Internet.</p> 429 <p>The most efficient and performant way to host a connectable entry-point supporting many 430 users is to use the <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code>. This interface type is fully compatible with 431 the <code class="docutils literal notranslate"><span class="pre">TCPClientInterface</span></code> and <code class="docutils literal notranslate"><span class="pre">TCPServerInterface</span></code> types, but much faster and uses 432 less system resources, allowing your device to handle thousands of connections even on 433 small systems.</p> 434 <p>It is also important to set your connectable interface to <code class="docutils literal notranslate"><span class="pre">gateway</span></code> mode, since this 435 will greatly improve network convergence time and path resolution for anyone connecting 436 to your entry-point.</p> 437 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a backbone interface</span> 438 <span class="c1"># configured for acting as a gateway for users to</span> 439 <span class="c1"># connect to either a public or private network</span> 440 441 <span class="k">[[Public Gateway]]</span> 442 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">BackboneInterface</span> 443 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 444 <span class="w"> </span><span class="na">mode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">gateway</span> 445 <span class="w"> </span><span class="na">listen_on</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">0.0.0.0</span> 446 <span class="w"> </span><span class="na">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4242</span> 447 448 <span class="w"> </span><span class="c1"># On publicly available interfaces, it can be</span> 449 <span class="w"> </span><span class="c1"># a good idea to configure sensible announce</span> 450 <span class="w"> </span><span class="c1"># rate targets.</span> 451 <span class="w"> </span><span class="na">announce_rate_target</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">3600</span> 452 <span class="w"> </span><span class="na">announce_rate_penalty</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">3600</span> 453 <span class="w"> </span><span class="na">announce_rate_grace</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">12</span> 454 </pre></div> 455 </div> 456 <p>If instead you want to make a private entry-point from the Internet, you can use the 457 <a class="reference internal" href="interfaces.html#interfaces-options"><span class="std std-ref">IFAC name and passphrase options</span></a> to secure your interface with a network name and passphrase.</p> 458 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="c1"># A private entry-point requiring a pre-shared</span> 459 <span class="c1"># network name and passphrase to connect to.</span> 460 461 <span class="k">[[Private Gateway]]</span> 462 <span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">BackboneInterface</span> 463 <span class="w"> </span><span class="na">enabled</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span> 464 <span class="w"> </span><span class="na">mode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">gateway</span> 465 <span class="w"> </span><span class="na">listen_on</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">0.0.0.0</span> 466 <span class="w"> </span><span class="na">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4242</span> 467 <span class="w"> </span><span class="na">network_name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">private_ret</span> 468 <span class="w"> </span><span class="na">passphrase</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">2owjajquafIanPecAc</span> 469 </pre></div> 470 </div> 471 <p>If you are hosting an entry-point on an operating system that does not support 472 <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code>, you can use <code class="docutils literal notranslate"><span class="pre">TCPServerInterface</span></code> instead, although it will 473 not be as performant.</p> 474 </section> 475 <section id="connecting-reticulum-instances-over-the-internet"> 476 <h2>Connecting Reticulum Instances Over the Internet<a class="headerlink" href="#connecting-reticulum-instances-over-the-internet" title="Link to this heading">¶</a></h2> 477 <p>Reticulum currently offers three interfaces suitable for connecting instances over the Internet: <a class="reference internal" href="interfaces.html#interfaces-backbone"><span class="std std-ref">Backbone</span></a>, <a class="reference internal" href="interfaces.html#interfaces-tcps"><span class="std std-ref">TCP</span></a> 478 and <a class="reference internal" href="interfaces.html#interfaces-i2p"><span class="std std-ref">I2P</span></a>. Each interface offers a different set of features, and Reticulum 479 users should carefully choose the interface which best suites their needs.</p> 480 <p>The <code class="docutils literal notranslate"><span class="pre">TCPServerInterface</span></code> allows users to host an instance accessible over TCP/IP. This 481 method is generally faster, lower latency, and more energy efficient than using <code class="docutils literal notranslate"><span class="pre">I2PInterface</span></code>, 482 however it also leaks more data about the server host.</p> 483 <p>The <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code> is a very fast and efficient interface type available on POSIX operating 484 systems, designed to handle thousands of connections simultaneously with low memory, processing 485 and I/O overhead. It is fully compatible with the TCP-based interface types.</p> 486 <p>TCP connections reveal the IP address of both your instance and the server to anyone who can 487 inspect the connection. Someone could use this information to determine your location or identity. Adversaries 488 inspecting your packets may be able to record packet metadata like time of transmission and packet size. 489 Even though Reticulum encrypts traffic, TCP does not, so an adversary may be able to use 490 packet inspection to learn that a system is running Reticulum, and what other IP addresses connect to it. 491 Hosting a publicly reachable instance over TCP also requires a publicly reachable IP address, 492 which most Internet connections don’t offer anymore.</p> 493 <p>The <code class="docutils literal notranslate"><span class="pre">I2PInterface</span></code> routes messages through the <a class="reference external" href="https://geti2p.net/en/">Invisible Internet Protocol 494 (I2P)</a>. To use this interface, users must also run an I2P daemon in 495 parallel to <code class="docutils literal notranslate"><span class="pre">rnsd</span></code>. For always-on I2P nodes it is recommended to use <a class="reference external" href="https://i2pd.website/">i2pd</a>.</p> 496 <p>By default, I2P will encrypt and mix all traffic sent over the Internet, and 497 hide both the sender and receiver Reticulum instance IP addresses. Running an I2P node 498 will also relay other I2P user’s encrypted packets, which will use extra 499 bandwidth and compute power, but also makes timing attacks and other forms of 500 deep-packet-inspection much more difficult.</p> 501 <p>I2P also allows users to host globally available Reticulum instances from non-public IP’s and behind firewalls and NAT.</p> 502 <p>In general it is recommended to use an I2P node if you want to host a publicly accessible 503 instance, while preserving anonymity. If you care more about performance, and a slightly 504 easier setup, use TCP.</p> 505 </section> 506 <section id="adding-radio-interfaces"> 507 <h2>Adding Radio Interfaces<a class="headerlink" href="#adding-radio-interfaces" title="Link to this heading">¶</a></h2> 508 <p>Once you have Reticulum installed and working, you can add radio interfaces with 509 any compatible hardware you have available. Reticulum supports a wide range of radio 510 hardware, and if you already have any available, it is very likely that it will 511 work with Reticulum. For information on how to configure this, see the 512 <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Interfaces</span></a> section of this manual.</p> 513 <p>If you do not already have transceiver hardware available, you can easily and 514 cheaply build an <a class="reference internal" href="hardware.html#rnode-main"><span class="std std-ref">RNode</span></a>, which is a general-purpose long-range 515 digital radio transceiver, that integrates easily with Reticulum.</p> 516 <p>To build one yourself requires installing a custom firmware on a supported LoRa 517 development board with an auto-install script or web-based flasher. 518 Please see the <a class="reference internal" href="hardware.html#hardware-main"><span class="std std-ref">Communications Hardware</span></a> chapter for a guide. 519 If you prefer purchasing a ready-made unit, you can refer to the 520 <span class="xref std std-ref">list of suppliers</span>.</p> 521 <p>Other radio-based hardware interfaces are being developed and made available by 522 the broader Reticulum community. You can find more information on such topics 523 over Reticulum-based information sharing systems.</p> 524 <p>If you have communications hardware that is not already supported by any of the 525 <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">existing interface types</span></a>, it is easy to write (and potentially 526 publish) a <a class="reference internal" href="interfaces.html#interfaces-custom"><span class="std std-ref">custom interface module</span></a> that makes it compatible with Reticulum.</p> 527 </section> 528 <section id="creating-and-using-custom-interfaces"> 529 <h2>Creating and Using Custom Interfaces<a class="headerlink" href="#creating-and-using-custom-interfaces" title="Link to this heading">¶</a></h2> 530 <p>While Reticulum includes a flexible and broad range of built-in interfaces, these 531 will not cover every conceivable type of communications hardware that Reticulum 532 can potentially use to communicate.</p> 533 <p>It is therefore possible to easily write your own interface modules, that can be 534 loaded at run-time and used on-par with any of the built-in interface types.</p> 535 <p>For more information on this subject, and code examples to build on, please see 536 the <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Configuring Interfaces</span></a> chapter.</p> 537 </section> 538 <section id="develop-a-program-with-reticulum"> 539 <h2>Develop a Program with Reticulum<a class="headerlink" href="#develop-a-program-with-reticulum" title="Link to this heading">¶</a></h2> 540 <p>If you want to develop programs that use Reticulum, the easiest way to get 541 started is to install the latest release of Reticulum via pip:</p> 542 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">rns</span> 543 </pre></div> 544 </div> 545 <p>The above command will install Reticulum and dependencies, and you will be 546 ready to import and use RNS in your own programs. The next step will most 547 likely be to look at some <a class="reference internal" href="examples.html#examples-main"><span class="std std-ref">Example Programs</span></a>.</p> 548 <p>The entire Reticulum API is documented in the <a class="reference internal" href="reference.html#api-main"><span class="std std-ref">API Reference</span></a> 549 chapter of this manual. Before diving in, it’s probably a good idea to read 550 this manual in full, but at least start with the <a class="reference internal" href="understanding.html#understanding-main"><span class="std std-ref">Understanding Reticulum</span></a> chapter.</p> 551 </section> 552 <section id="platform-specific-install-notes"> 553 <span id="install-guides"></span><h2>Platform-Specific Install Notes<a class="headerlink" href="#platform-specific-install-notes" title="Link to this heading">¶</a></h2> 554 <p>Some platforms require a slightly different installation procedure, or have 555 various quirks that are worth being aware of. These are listed here.</p> 556 <section id="android"> 557 <h3>Android<a class="headerlink" href="#android" title="Link to this heading">¶</a></h3> 558 <p>Reticulum can be used on Android in different ways. The easiest way to get 559 started is using an app like <a class="reference external" href="https://unsigned.io/sideband">Sideband</a>.</p> 560 <p>For more control and features, you can use Reticulum and related programs via 561 the <a class="reference external" href="https://termux.com/">Termux app</a>, at the time of writing available on 562 <a class="reference external" href="https://f-droid.org">F-droid</a>.</p> 563 <p>Termux is a terminal emulator and Linux environment for Android based devices, 564 which includes the ability to use many different programs and libraries, 565 including Reticulum.</p> 566 <p>To use Reticulum within the Termux environment, you will need to install 567 <code class="docutils literal notranslate"><span class="pre">python</span></code> and the <code class="docutils literal notranslate"><span class="pre">python-cryptography</span></code> library using <code class="docutils literal notranslate"><span class="pre">pkg</span></code>, the package-manager 568 build into Termux. After that, you can use <code class="docutils literal notranslate"><span class="pre">pip</span></code> to install Reticulum.</p> 569 <p>From within Termux, execute the following:</p> 570 <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># First, make sure indexes and packages are up to date.</span> 571 pkg<span class="w"> </span>update 572 pkg<span class="w"> </span>upgrade 573 574 <span class="c1"># Then install python and the cryptography library.</span> 575 pkg<span class="w"> </span>install<span class="w"> </span>python<span class="w"> </span>python-cryptography 576 577 <span class="c1"># Make sure pip is up to date, and install the wheel module.</span> 578 pip<span class="w"> </span>install<span class="w"> </span>wheel<span class="w"> </span>pip<span class="w"> </span>--upgrade 579 580 <span class="c1"># Install Reticulum</span> 581 pip<span class="w"> </span>install<span class="w"> </span>rns 582 </pre></div> 583 </div> 584 <p>If for some reason the <code class="docutils literal notranslate"><span class="pre">python-cryptography</span></code> package is not available for 585 your platform via the Termux package manager, you can attempt to build it 586 locally on your device using the following command:</p> 587 <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># First, make sure indexes and packages are up to date.</span> 588 pkg<span class="w"> </span>update 589 pkg<span class="w"> </span>upgrade 590 591 <span class="c1"># Then install dependencies for the cryptography library.</span> 592 pkg<span class="w"> </span>install<span class="w"> </span>python<span class="w"> </span>build-essential<span class="w"> </span>openssl<span class="w"> </span>libffi<span class="w"> </span>rust 593 594 <span class="c1"># Make sure pip is up to date, and install the wheel module.</span> 595 pip<span class="w"> </span>install<span class="w"> </span>wheel<span class="w"> </span>pip<span class="w"> </span>--upgrade 596 597 <span class="c1"># To allow the installer to build the cryptography module,</span> 598 <span class="c1"># we need to let it know what platform we are compiling for:</span> 599 <span class="nb">export</span><span class="w"> </span><span class="nv">CARGO_BUILD_TARGET</span><span class="o">=</span><span class="s2">"aarch64-linux-android"</span> 600 601 <span class="c1"># Start the install process for the cryptography module.</span> 602 <span class="c1"># Depending on your device, this can take several minutes,</span> 603 <span class="c1"># since the module must be compiled locally on your device.</span> 604 pip<span class="w"> </span>install<span class="w"> </span>cryptography 605 606 <span class="c1"># If the above installation succeeds, you can now install</span> 607 <span class="c1"># Reticulum and any related software</span> 608 pip<span class="w"> </span>install<span class="w"> </span>rns 609 </pre></div> 610 </div> 611 <p>It is also possible to include Reticulum in apps compiled and distributed as 612 Android APKs. A detailed tutorial and example source code will be included 613 here at a later point. Until then you can use the <a class="reference external" href="https://github.com/markqvist/sideband">Sideband source code</a> as an example and starting point.</p> 614 </section> 615 <section id="arm64"> 616 <h3>ARM64<a class="headerlink" href="#arm64" title="Link to this heading">¶</a></h3> 617 <p>On some architectures, including ARM64, not all dependencies have precompiled 618 binaries. On such systems, you may need to install <code class="docutils literal notranslate"><span class="pre">python3-dev</span></code> (or similar) before 619 installing Reticulum or programs that depend on Reticulum.</p> 620 <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install Python and development packages</span> 621 sudo<span class="w"> </span>apt<span class="w"> </span>update 622 sudo<span class="w"> </span>apt<span class="w"> </span>install<span class="w"> </span>python3<span class="w"> </span>python3-pip<span class="w"> </span>python3-dev 623 624 <span class="c1"># Install Reticulum</span> 625 python3<span class="w"> </span>-m<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>rns 626 </pre></div> 627 </div> 628 <p>With these packages installed, <code class="docutils literal notranslate"><span class="pre">pip</span></code> will be able to build any missing dependencies 629 on your system locally.</p> 630 </section> 631 <section id="debian-bookworm"> 632 <h3>Debian Bookworm<a class="headerlink" href="#debian-bookworm" title="Link to this heading">¶</a></h3> 633 <p>On versions of Debian released after April 2023, it is no longer possible by default 634 to use <code class="docutils literal notranslate"><span class="pre">pip</span></code> to install packages onto your system. Unfortunately, you will need to 635 use the replacement <code class="docutils literal notranslate"><span class="pre">pipx</span></code> command instead, which places installed packages in an 636 isolated environment. This should not negatively affect Reticulum, but will not work 637 for including and using Reticulum in your own scripts and programs.</p> 638 <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install pipx</span> 639 sudo<span class="w"> </span>apt<span class="w"> </span>install<span class="w"> </span>pipx 640 641 <span class="c1"># Make installed programs available on the command line</span> 642 pipx<span class="w"> </span>ensurepath 643 644 <span class="c1"># Install Reticulum</span> 645 pipx<span class="w"> </span>install<span class="w"> </span>rns 646 </pre></div> 647 </div> 648 <p>Alternatively, you can restore normal behaviour to <code class="docutils literal notranslate"><span class="pre">pip</span></code> by creating or editing 649 the configuration file located at <code class="docutils literal notranslate"><span class="pre">~/.config/pip/pip.conf</span></code>, and adding the 650 following section:</p> 651 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[global]</span> 652 <span class="na">break-system-packages</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">true</span> 653 </pre></div> 654 </div> 655 <p>For a one-shot installation of Reticulum, without globally enabling the <code class="docutils literal notranslate"><span class="pre">break-system-packages</span></code> 656 option, you can use the following command:</p> 657 <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>rns<span class="w"> </span>--break-system-packages 658 </pre></div> 659 </div> 660 <div class="admonition note"> 661 <p class="admonition-title">Note</p> 662 <p>The <code class="docutils literal notranslate"><span class="pre">--break-system-packages</span></code> directive is a somewhat misleading choice 663 of words. Setting it will of course not break any system packages, but will simply 664 allow installing <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages user- and system-wide. While this <em>could</em> in rare 665 cases lead to version conflicts, it does not generally pose any problems, especially 666 not in the case of installing Reticulum.</p> 667 </div> 668 </section> 669 <section id="macos"> 670 <h3>MacOS<a class="headerlink" href="#macos" title="Link to this heading">¶</a></h3> 671 <p>To install Reticulum on macOS, you will need to have Python and the <code class="docutils literal notranslate"><span class="pre">pip</span></code> package 672 manager installed.</p> 673 <p>Systems running macOS can vary quite widely in whether or not Python is pre-installed, 674 and if it is, which version is installed, and whether the <code class="docutils literal notranslate"><span class="pre">pip</span></code> package manager is 675 also installed and set up. If in doubt, you can <a class="reference external" href="https://www.python.org/downloads/">download and install</a> 676 Python manually.</p> 677 <p>When Python and <code class="docutils literal notranslate"><span class="pre">pip</span></code> is available on your system, simply open a terminal window 678 and use one of the following commands:</p> 679 <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install Reticulum and utilities with pip:</span> 680 pip3<span class="w"> </span>install<span class="w"> </span>rns 681 682 <span class="c1"># On some versions, you may need to use the</span> 683 <span class="c1"># flag --break-system-packages to install:</span> 684 pip3<span class="w"> </span>install<span class="w"> </span>rns<span class="w"> </span>--break-system-packages 685 </pre></div> 686 </div> 687 <div class="admonition note"> 688 <p class="admonition-title">Note</p> 689 <p>The <code class="docutils literal notranslate"><span class="pre">--break-system-packages</span></code> directive is a somewhat misleading choice 690 of words. Setting it will of course not break any system packages, but will simply 691 allow installing <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages user- and system-wide. While this <em>could</em> in rare 692 cases lead to version conflicts, it does not generally pose any problems, especially 693 not in the case of installing Reticulum.</p> 694 </div> 695 <p>Additionally, some version combinations of macOS and Python require you to 696 manually add your installed <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages directory to your <cite>PATH</cite> environment 697 variable, before you can use installed commands in your terminal. Usually, adding 698 the following line to your shell init script (for example <code class="docutils literal notranslate"><span class="pre">~/.zshrc</span></code>) will be enough:</p> 699 <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="nb">export</span><span class="w"> </span><span class="nv">PATH</span><span class="o">=</span><span class="nv">$PATH</span>:~/Library/Python/3.9/bin 700 </pre></div> 701 </div> 702 <p>Adjust Python version and shell init script location according to your system.</p> 703 </section> 704 <section id="openwrt"> 705 <h3>OpenWRT<a class="headerlink" href="#openwrt" title="Link to this heading">¶</a></h3> 706 <p>On OpenWRT systems with sufficient storage and memory, you can install 707 Reticulum and related utilities using the <cite>opkg</cite> package manager and <cite>pip</cite>.</p> 708 <div class="admonition note"> 709 <p class="admonition-title">Note</p> 710 <p>At the time of releasing this manual, work is underway to create pre-built 711 Reticulum packages for OpenWRT, with full configuration, service 712 and <code class="docutils literal notranslate"><span class="pre">uci</span></code> integration. Please see the <a class="reference external" href="https://github.com/gretel/feed-reticulum">feed-reticulum</a> 713 and <a class="reference external" href="https://github.com/gretel/reticulum-openwrt">reticulum-openwrt</a> 714 repositories for more information.</p> 715 </div> 716 <p>To install Reticulum on OpenWRT, first log into a command line session, and 717 then use the following instructions:</p> 718 <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install dependencies</span> 719 opkg<span class="w"> </span>install<span class="w"> </span>python3<span class="w"> </span>python3-pip<span class="w"> </span>python3-cryptography<span class="w"> </span>python3-pyserial 720 721 <span class="c1"># Install Reticulum</span> 722 pip<span class="w"> </span>install<span class="w"> </span>rns 723 724 <span class="c1"># Start rnsd with debug logging enabled</span> 725 rnsd<span class="w"> </span>-vvv 726 </pre></div> 727 </div> 728 <div class="admonition note"> 729 <p class="admonition-title">Note</p> 730 <p>The above instructions have been verified and tested on OpenWRT 21.02 only. 731 It is likely that other versions may require slightly altered installation 732 commands or package names. You will also need enough free space in your 733 overlay FS, and enough free RAM to actually run Reticulum and any related 734 programs and utilities.</p> 735 </div> 736 <p>Depending on your device configuration, you may need to adjust firewall rules 737 for Reticulum connectivity to and from your device to work. Until proper 738 packaging is ready, you will also need to manually create a service or startup 739 script to automatically laucnh Reticulum at boot time.</p> 740 <p>Please also note that the <cite>AutoInterface</cite> requires link-local IPv6 addresses 741 to be enabled for any Ethernet and WiFi devices you intend to use. If <code class="docutils literal notranslate"><span class="pre">ip</span> <span class="pre">a</span></code> 742 shows an address starting with <code class="docutils literal notranslate"><span class="pre">fe80::</span></code> for the device in question, 743 <code class="docutils literal notranslate"><span class="pre">AutoInterface</span></code> should work for that device.</p> 744 </section> 745 <section id="raspberry-pi"> 746 <h3>Raspberry Pi<a class="headerlink" href="#raspberry-pi" title="Link to this heading">¶</a></h3> 747 <p>It is currently recommended to use a 64-bit version of the Raspberry Pi OS 748 if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions 749 don’t always have packages available for some dependencies. If Python and the 750 <cite>pip</cite> package manager is not already installed, do that first, and then 751 install Reticulum using <cite>pip</cite>.</p> 752 <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install dependencies</span> 753 sudo<span class="w"> </span>apt<span class="w"> </span>install<span class="w"> </span>python3<span class="w"> </span>python3-pip<span class="w"> </span>python3-cryptography<span class="w"> </span>python3-pyserial 754 755 <span class="c1"># Install Reticulum</span> 756 pip<span class="w"> </span>install<span class="w"> </span>rns<span class="w"> </span>--break-system-packages 757 </pre></div> 758 </div> 759 <div class="admonition note"> 760 <p class="admonition-title">Note</p> 761 <p>The <code class="docutils literal notranslate"><span class="pre">--break-system-packages</span></code> directive is a somewhat misleading choice 762 of words. Setting it will of course not break any system packages, but will simply 763 allow installing <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages user- and system-wide. While this <em>could</em> in rare 764 cases lead to version conflicts, it does not generally pose any problems, especially 765 not in the case of installing Reticulum.</p> 766 </div> 767 <p>While it is possible to install and run Reticulum on 32-bit Rasperry Pi OSes, 768 it will require manually configuring and installing required build dependencies, 769 and is not detailed in this manual.</p> 770 </section> 771 <section id="risc-v"> 772 <h3>RISC-V<a class="headerlink" href="#risc-v" title="Link to this heading">¶</a></h3> 773 <p>On some architectures, including RISC-V, not all dependencies have precompiled 774 binaries. On such systems, you may need to install <code class="docutils literal notranslate"><span class="pre">python3-dev</span></code> (or similar) before 775 installing Reticulum or programs that depend on Reticulum.</p> 776 <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install Python and development packages</span> 777 sudo<span class="w"> </span>apt<span class="w"> </span>update 778 sudo<span class="w"> </span>apt<span class="w"> </span>install<span class="w"> </span>python3<span class="w"> </span>python3-pip<span class="w"> </span>python3-dev 779 780 <span class="c1"># Install Reticulum</span> 781 python3<span class="w"> </span>-m<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>rns 782 </pre></div> 783 </div> 784 <p>With these packages installed, <code class="docutils literal notranslate"><span class="pre">pip</span></code> will be able to build any missing dependencies 785 on your system locally.</p> 786 </section> 787 <section id="ubuntu-lunar"> 788 <h3>Ubuntu Lunar<a class="headerlink" href="#ubuntu-lunar" title="Link to this heading">¶</a></h3> 789 <p>On versions of Ubuntu released after April 2023, it is no longer possible by default 790 to use <code class="docutils literal notranslate"><span class="pre">pip</span></code> to install packages onto your system. Unfortunately, you will need to 791 use the replacement <code class="docutils literal notranslate"><span class="pre">pipx</span></code> command instead, which places installed packages in an 792 isolated environment. This should not negatively affect Reticulum, but will not work 793 for including and using Reticulum in your own scripts and programs.</p> 794 <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install pipx</span> 795 sudo<span class="w"> </span>apt<span class="w"> </span>install<span class="w"> </span>pipx 796 797 <span class="c1"># Make installed programs available on the command line</span> 798 pipx<span class="w"> </span>ensurepath 799 800 <span class="c1"># Install Reticulum</span> 801 pipx<span class="w"> </span>install<span class="w"> </span>rns 802 </pre></div> 803 </div> 804 <p>Alternatively, you can restore normal behaviour to <code class="docutils literal notranslate"><span class="pre">pip</span></code> by creating or editing 805 the configuration file located at <code class="docutils literal notranslate"><span class="pre">~/.config/pip/pip.conf</span></code>, and adding the 806 following section:</p> 807 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[global] 808 break-system-packages = true 809 </pre></div> 810 </div> 811 <p>For a one-shot installation of Reticulum, without globally enabling the <code class="docutils literal notranslate"><span class="pre">break-system-packages</span></code> 812 option, you can use the following command:</p> 813 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>pip install rns --break-system-packages 814 </pre></div> 815 </div> 816 <div class="admonition note"> 817 <p class="admonition-title">Note</p> 818 <p>The <code class="docutils literal notranslate"><span class="pre">--break-system-packages</span></code> directive is a somewhat misleading choice 819 of words. Setting it will of course not break any system packages, but will simply 820 allow installing <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages user- and system-wide. While this <em>could</em> in rare 821 cases lead to version conflicts, it does not generally pose any problems, especially 822 not in the case of installing Reticulum.</p> 823 </div> 824 </section> 825 <section id="windows"> 826 <h3>Windows<a class="headerlink" href="#windows" title="Link to this heading">¶</a></h3> 827 <p>On Windows operating systems, the easiest way to install Reticulum is by using the 828 <code class="docutils literal notranslate"><span class="pre">pip</span></code> package manager from the command line (either the command prompt or Windows 829 Powershell).</p> 830 <p>If you don’t already have Python installed, <a class="reference external" href="https://www.python.org/downloads/">download and install Python</a>. 831 At the time of publication of this manual, the recommended version is <a class="reference external" href="https://www.python.org/downloads/release/python-3127">Python 3.12.7</a>.</p> 832 <p><strong>Important!</strong> When asked by the installer, make sure to add the Python program to 833 your PATH environment variables. If you don’t do this, you will not be able to 834 use the <code class="docutils literal notranslate"><span class="pre">pip</span></code> installer, or run the included Reticulum utility programs (such as 835 <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> and <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code>) from the command line.</p> 836 <p>After installing Python, open the command prompt or Windows Powershell, and type:</p> 837 <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>rns 838 </pre></div> 839 </div> 840 <p>You can now use Reticulum and all included utility programs directly from your 841 preferred command line interface.</p> 842 </section> 843 </section> 844 <section id="pure-python-reticulum"> 845 <h2>Pure-Python Reticulum<a class="headerlink" href="#pure-python-reticulum" title="Link to this heading">¶</a></h2> 846 <div class="admonition warning"> 847 <p class="admonition-title">Warning</p> 848 <p>If you use the <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> package to run Reticulum on systems that 849 do not support <a class="reference external" href="https://github.com/pyca/cryptography">PyCA/cryptography</a>, it is 850 important that you read and understand the <a class="reference internal" href="understanding.html#understanding-primitives"><span class="std std-ref">Cryptographic Primitives</span></a> 851 section of this manual.</p> 852 </div> 853 <p>In some rare cases, and on more obscure system types, it is not possible to 854 install one or more dependencies. In such situations, 855 you can use the <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> package instead of the <code class="docutils literal notranslate"><span class="pre">rns</span></code> package, or use <code class="docutils literal notranslate"><span class="pre">pip</span></code> 856 with the <code class="docutils literal notranslate"><span class="pre">--no-dependencies</span></code> command-line option. The <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> 857 package requires no external dependencies for installation. Please note that the 858 actual contents of the <code class="docutils literal notranslate"><span class="pre">rns</span></code> and <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> packages are <em>completely identical</em>. 859 The only difference is that the <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> package lists no dependencies required 860 for installation.</p> 861 <p>No matter how Reticulum is installed and started, it will load external dependencies 862 only if they are <em>needed</em> and <em>available</em>. If for example you want to use Reticulum 863 on a system that cannot support <code class="docutils literal notranslate"><span class="pre">pyserial</span></code>, it is perfectly possible to do so using 864 the <cite>rnspure</cite> package, but Reticulum will not be able to use serial-based interfaces. 865 All other available modules will still be loaded when needed.</p> 866 </section> 867 </section> 868 869 </article> 870 </div> 871 <footer> 872 873 <div class="related-pages"> 874 <a class="next-page" href="zen.html"> 875 <div class="page-info"> 876 <div class="context"> 877 <span>Next</span> 878 </div> 879 <div class="title">Zen of Reticulum</div> 880 </div> 881 <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> 882 </a> 883 <a class="prev-page" href="whatis.html"> 884 <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> 885 <div class="page-info"> 886 <div class="context"> 887 <span>Previous</span> 888 </div> 889 890 <div class="title">What is Reticulum?</div> 891 892 </div> 893 </a> 894 </div> 895 <div class="bottom-of-page"> 896 <div class="left-details"> 897 <div class="copyright"> 898 Copyright © 2025, Mark Qvist 899 </div> 900 Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 901 <a href="https://github.com/pradyunsg/furo">Furo</a> 902 903 </div> 904 <div class="right-details"> 905 906 </div> 907 </div> 908 909 </footer> 910 </div> 911 <aside class="toc-drawer"> 912 913 914 <div class="toc-sticky toc-scroll"> 915 <div class="toc-title-container"> 916 <span class="toc-title"> 917 On this page 918 </span> 919 </div> 920 <div class="toc-tree-container"> 921 <div class="toc-tree"> 922 <ul> 923 <li><a class="reference internal" href="#">Getting Started Fast</a><ul> 924 <li><a class="reference internal" href="#standalone-reticulum-installation">Standalone Reticulum Installation</a><ul> 925 <li><a class="reference internal" href="#resolving-dependency-installation-issues">Resolving Dependency & Installation Issues</a></li> 926 </ul> 927 </li> 928 <li><a class="reference internal" href="#try-using-a-reticulum-based-program">Try Using a Reticulum-based Program</a></li> 929 <li><a class="reference internal" href="#using-the-included-utilities">Using the Included Utilities</a></li> 930 <li><a class="reference internal" href="#creating-a-network-with-reticulum">Creating a Network With Reticulum</a></li> 931 <li><a class="reference internal" href="#bootstrapping-connectivity">Bootstrapping Connectivity</a><ul> 932 <li><a class="reference internal" href="#finding-your-way">Finding Your Way</a></li> 933 <li><a class="reference internal" href="#build-personal-infrastructure">Build Personal Infrastructure</a></li> 934 <li><a class="reference internal" href="#mixing-strategies">Mixing Strategies</a></li> 935 <li><a class="reference internal" href="#network-health-responsibility">Network Health & Responsibility</a></li> 936 <li><a class="reference internal" href="#contributing-to-the-global-ret">Contributing to the Global Ret</a></li> 937 </ul> 938 </li> 939 <li><a class="reference internal" href="#connect-to-the-distributed-backbone">Connect to the Distributed Backbone</a></li> 940 <li><a class="reference internal" href="#hosting-public-entrypoints">Hosting Public Entrypoints</a></li> 941 <li><a class="reference internal" href="#connecting-reticulum-instances-over-the-internet">Connecting Reticulum Instances Over the Internet</a></li> 942 <li><a class="reference internal" href="#adding-radio-interfaces">Adding Radio Interfaces</a></li> 943 <li><a class="reference internal" href="#creating-and-using-custom-interfaces">Creating and Using Custom Interfaces</a></li> 944 <li><a class="reference internal" href="#develop-a-program-with-reticulum">Develop a Program with Reticulum</a></li> 945 <li><a class="reference internal" href="#platform-specific-install-notes">Platform-Specific Install Notes</a><ul> 946 <li><a class="reference internal" href="#android">Android</a></li> 947 <li><a class="reference internal" href="#arm64">ARM64</a></li> 948 <li><a class="reference internal" href="#debian-bookworm">Debian Bookworm</a></li> 949 <li><a class="reference internal" href="#macos">MacOS</a></li> 950 <li><a class="reference internal" href="#openwrt">OpenWRT</a></li> 951 <li><a class="reference internal" href="#raspberry-pi">Raspberry Pi</a></li> 952 <li><a class="reference internal" href="#risc-v">RISC-V</a></li> 953 <li><a class="reference internal" href="#ubuntu-lunar">Ubuntu Lunar</a></li> 954 <li><a class="reference internal" href="#windows">Windows</a></li> 955 </ul> 956 </li> 957 <li><a class="reference internal" href="#pure-python-reticulum">Pure-Python Reticulum</a></li> 958 </ul> 959 </li> 960 </ul> 961 962 </div> 963 </div> 964 </div> 965 966 967 </aside> 968 </div> 969 </div><script src="_static/documentation_options.js?v=cb7bf70b"></script> 970 <script src="_static/doctools.js?v=9bcbadda"></script> 971 <script src="_static/sphinx_highlight.js?v=dc90522c"></script> 972 <script src="_static/scripts/furo.js?v=46bd48cc"></script> 973 <script src="_static/clipboard.min.js?v=a7894cd8"></script> 974 <script src="_static/copybutton.js?v=f281be69"></script> 975 </body> 976 </html>