gettingstartedfast.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="Using Reticulum on Your System" href="using.html" /><link rel="prev" title="What is Reticulum?" href="whatis.html" /> 7 8 <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29.dev1"/> 9 <title>Getting Started Fast - 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 current current-page"><a class="current reference internal" href="#">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"><a class="reference internal" href="networks.html">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="getting-started-fast"> 225 <h1>Getting Started Fast<a class="headerlink" href="#getting-started-fast" title="Permalink to this heading">#</a></h1> 226 <p>The best way to get started with the Reticulum Network Stack depends on what 227 you want to do. This guide will outline sensible starting paths for different 228 scenarios.</p> 229 <section id="standalone-reticulum-installation"> 230 <h2>Standalone Reticulum Installation<a class="headerlink" href="#standalone-reticulum-installation" title="Permalink to this heading">#</a></h2> 231 <p>If you simply want to install Reticulum and related utilities on a system, 232 the easiest way is via the <code class="docutils literal notranslate"><span class="pre">pip</span></code> package manager:</p> 233 <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> 234 </pre></div> 235 </div> 236 <p>If you do not already have pip installed, you can install it using the package manager 237 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>, 238 <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> 239 <p>You can also dowload the Reticulum release wheels from GitHub, or other release channels, 240 and install them offline using <code class="docutils literal notranslate"><span class="pre">pip</span></code>:</p> 241 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">./</span><span class="n">rns</span><span class="o">-</span><span class="mf">0.5.1</span><span class="o">-</span><span class="n">py3</span><span class="o">-</span><span class="n">none</span><span class="o">-</span><span class="nb">any</span><span class="o">.</span><span class="n">whl</span> 242 </pre></div> 243 </div> 244 <p>For more detailed installation instructions, please see the 245 <a class="reference internal" href="#install-guides"><span class="std std-ref">Platform-Specific Install Notes</span></a> section.</p> 246 <p>After installation is complete, it might be helpful to refer to the 247 <a class="reference internal" href="using.html#using-main"><span class="std std-ref">Using Reticulum on Your System</span></a> chapter.</p> 248 <section id="resolving-dependency-installation-issues"> 249 <h3>Resolving Dependency & Installation Issues<a class="headerlink" href="#resolving-dependency-installation-issues" title="Permalink to this heading">#</a></h3> 250 <p>On some platforms, there may not be binary packages available for all dependencies, and 251 <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 252 be resolved by installing the development essentials packages for your platform:</p> 253 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Debian / Ubuntu / Derivatives</span> 254 <span class="n">sudo</span> <span class="n">apt</span> <span class="n">install</span> <span class="n">build</span><span class="o">-</span><span class="n">essential</span> 255 256 <span class="c1"># Arch / Manjaro / Derivatives</span> 257 <span class="n">sudo</span> <span class="n">pamac</span> <span class="n">install</span> <span class="n">base</span><span class="o">-</span><span class="n">devel</span> 258 259 <span class="c1"># Fedora</span> 260 <span class="n">sudo</span> <span class="n">dnf</span> <span class="n">groupinstall</span> <span class="s2">"Development Tools"</span> <span class="s2">"Development Libraries"</span> 261 </pre></div> 262 </div> 263 <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 264 dependencies from source, and complete installation even on platforms that don’t have pre- 265 compiled packages available.</p> 266 </section> 267 </section> 268 <section id="try-using-a-reticulum-based-program"> 269 <h2>Try Using a Reticulum-based Program<a class="headerlink" href="#try-using-a-reticulum-based-program" title="Permalink to this heading">#</a></h2> 270 <p>If you simply want to try using a program built with Reticulum, a few different 271 programs exist that allow basic communication and a range of other useful functions, 272 even over extremely low-bandwidth Reticulum networks.</p> 273 <p>These programs will let you get a feel for how Reticulum works. They have been designed 274 to run well over networks based on LoRa or packet radio, but can also be used over fast 275 links, such as local WiFi, wired Ethernet, the Internet, or any combination.</p> 276 <p>As such, it is easy to get started experimenting, without having to set up any radio 277 transceivers or infrastructure just to try it out. Launching the programs on separate 278 devices connected to the same WiFi network is enough to get started, and physical 279 radio interfaces can then be added later.</p> 280 <section id="remote-shell"> 281 <h3>Remote Shell<a class="headerlink" href="#remote-shell" title="Permalink to this heading">#</a></h3> 282 <p>The <a class="reference external" href="https://github.com/acehoss/rnsh">rnsh</a> program lets you establish fully interactive 283 remote shell sessions over Reticulum. It also allows you to pipe any program to or from a 284 remote system, and is similar to how <code class="docutils literal notranslate"><span class="pre">ssh</span></code> works. The <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> is very efficient, and 285 can facilitate fully interactive shell sessions, even over extremely low-bandwidth links, 286 such as LoRa or packet radio.</p> 287 </section> 288 <section id="nomad-network"> 289 <h3>Nomad Network<a class="headerlink" href="#nomad-network" title="Permalink to this heading">#</a></h3> 290 <p>The terminal-based program <a class="reference external" href="https://github.com/markqvist/nomadnet">Nomad Network</a> 291 provides a complete encrypted communications suite built with Reticulum. It features 292 encrypted messaging (both direct and delayed-delivery for offline users), file sharing, 293 and has a built-in text-browser and page server with support for dynamically rendered pages, 294 user authentication and more.</p> 295 <a class="reference external image-reference" href="_images/nomadnet_3.png"><img alt="_images/nomadnet_3.png" src="_images/nomadnet_3.png" /> 296 </a> 297 <p><a class="reference external" href="https://github.com/markqvist/nomadnet">Nomad Network</a> is a user-facing client 298 for the messaging and information-sharing protocol 299 <a class="reference external" href="https://github.com/markqvist/lxmf">LXMF</a>, another project built with Reticulum.</p> 300 <p>You can install Nomad Network via pip:</p> 301 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install ...</span> 302 <span class="n">pip</span> <span class="n">install</span> <span class="n">nomadnet</span> 303 304 <span class="c1"># ... and run</span> 305 <span class="n">nomadnet</span> 306 </pre></div> 307 </div> 308 <div class="admonition note"> 309 <p class="admonition-title">Note</p> 310 <p>If this is the very first time you use <code class="docutils literal notranslate"><span class="pre">pip</span></code> to install a program 311 on your system, you might need to reboot your system for your program to become 312 available. If you get a “command not found” error or similar when running the 313 program, reboot your system and try again. In some cases, you may even need to 314 manually add the <code class="docutils literal notranslate"><span class="pre">pip</span></code> install path to your <code class="docutils literal notranslate"><span class="pre">PATH</span></code> environment variable.</p> 315 </div> 316 </section> 317 <section id="sideband"> 318 <h3>Sideband<a class="headerlink" href="#sideband" title="Permalink to this heading">#</a></h3> 319 <p>If you would rather use a program with a graphical user interface, you can take 320 a look at <a class="reference external" href="https://unsigned.io/sideband">Sideband</a>, which is available for Android, 321 Linux, macOS and Windows.</p> 322 <a class="reference external image-reference" href="_images/sideband_devices.webp"><img alt="_images/sideband_devices.webp" class="align-center" src="_images/sideband_devices.webp" /> 323 </a> 324 <p>Sideband allows you to communicate with other people or LXMF-compatible 325 systems over Reticulum networks using LoRa, Packet Radio, WiFi, I2P, Encrypted QR 326 Paper Messages, or anything else Reticulum supports. It also interoperates with 327 the Nomad Network program.</p> 328 </section> 329 <section id="meshchat"> 330 <h3>MeshChat<a class="headerlink" href="#meshchat" title="Permalink to this heading">#</a></h3> 331 <p>The <a class="reference external" href="https://github.com/liamcottle/reticulum-meshchat">Reticulum MeshChat</a> application 332 is a user-friendly LXMF client for macOS and Windows, that also includes voice call 333 functionality, and a range of other interesting functions.</p> 334 <a class="reference external image-reference" href="_images/meshchat_1.webp"><img alt="_images/meshchat_1.webp" class="align-center" src="_images/meshchat_1.webp" /> 335 </a> 336 <p>Reticulum MeshChat is of course also compatible with Sideband and Nomad Network, or 337 any other LXMF client.</p> 338 </section> 339 </section> 340 <section id="using-the-included-utilities"> 341 <h2>Using the Included Utilities<a class="headerlink" href="#using-the-included-utilities" title="Permalink to this heading">#</a></h2> 342 <p>Reticulum comes with a range of included utilities that make it easier to 343 manage your network, check connectivity and make Reticulum available to other 344 programs on your system.</p> 345 <p>You can use <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> to run Reticulum as a background or foreground service, 346 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 347 network status and connectivity.</p> 348 <p>To learn more about these utility programs, have a look at the 349 <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> 350 </section> 351 <section id="creating-a-network-with-reticulum"> 352 <h2>Creating a Network With Reticulum<a class="headerlink" href="#creating-a-network-with-reticulum" title="Permalink to this heading">#</a></h2> 353 <p>To create a network, you will need to specify one or more <em>interfaces</em> for 354 Reticulum to use. This is done in the Reticulum configuration file, which by 355 default is located at <code class="docutils literal notranslate"><span class="pre">~/.reticulum/config</span></code>. You can get an example 356 configuration file with all options via <code class="docutils literal notranslate"><span class="pre">rnsd</span> <span class="pre">--exampleconfig</span></code>.</p> 357 <p>When Reticulum is started for the first time, it will create a default 358 configuration file, with one active interface. This default interface uses 359 your existing Ethernet and WiFi networks (if any), and only allows you to 360 communicate with other Reticulum peers within your local broadcast domains.</p> 361 <p>To communicate further, you will have to add one or more interfaces. The default 362 configuration includes a number of examples, ranging from using TCP over the 363 internet, to LoRa and Packet Radio interfaces.</p> 364 <p>With Reticulum, you only need to configure what interfaces you want to communicate 365 over. There is no need to configure address spaces, subnets, routing tables, 366 or other things you might be used to from other network types.</p> 367 <p>Once Reticulum knows which interfaces it should use, it will automatically 368 discover topography and configure transport of data to any destinations it 369 knows about.</p> 370 <p>In situations where you already have an established WiFi or Ethernet network, and 371 many devices that want to utilise the same external Reticulum network paths (for example over 372 LoRa), it will often be sufficient to let one system act as a Reticulum gateway, by 373 adding any external interfaces to the configuration of this system, and then enabling transport on it. Any 374 other device on your local WiFi will then be able to connect to this wider Reticulum 375 network just using the default (<a class="reference internal" href="interfaces.html#interfaces-auto"><span class="std std-ref">AutoInterface</span></a>) configuration.</p> 376 <p>Possibly, the examples in the config file are enough to get you started. If 377 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> 378 and <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Interfaces</span></a> chapters of this manual.</p> 379 </section> 380 <section id="connecting-reticulum-instances-over-the-internet"> 381 <h2>Connecting Reticulum Instances Over the Internet<a class="headerlink" href="#connecting-reticulum-instances-over-the-internet" title="Permalink to this heading">#</a></h2> 382 <p>Reticulum currently offers two interfaces suitable for connecting instances over the Internet: <a class="reference internal" href="interfaces.html#interfaces-tcps"><span class="std std-ref">TCP</span></a> 383 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 384 users should carefully choose the interface which best suites their needs.</p> 385 <p>The <code class="docutils literal notranslate"><span class="pre">TCPServerInterface</span></code> allows users to host an instance accessible over TCP/IP. This 386 method is generally faster, lower latency, and more energy efficient than using <code class="docutils literal notranslate"><span class="pre">I2PInterface</span></code>, 387 however it also leaks more data about the server host.</p> 388 <p>TCP connections reveal the IP address of both your instance and the server to anyone who can 389 inspect the connection. Someone could use this information to determine your location or identity. Adversaries 390 inspecting your packets may be able to record packet metadata like time of transmission and packet size. 391 Even though Reticulum encrypts traffic, TCP does not, so an adversary may be able to use 392 packet inspection to learn that a system is running Reticulum, and what other IP addresses connect to it. 393 Hosting a publicly reachable instance over TCP also requires a publicly reachable IP address, 394 which most Internet connections don’t offer anymore.</p> 395 <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 396 (I2P)</a>. To use this interface, users must also run an I2P daemon in 397 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> 398 <p>By default, I2P will encrypt and mix all traffic sent over the Internet, and 399 hide both the sender and receiver Reticulum instance IP addresses. Running an I2P node 400 will also relay other I2P user’s encrypted packets, which will use extra 401 bandwidth and compute power, but also makes timing attacks and other forms of 402 deep-packet-inspection much more difficult.</p> 403 <p>I2P also allows users to host globally available Reticulum instances from non-public IP’s and behind firewalls and NAT.</p> 404 <p>In general it is recommended to use an I2P node if you want to host a publicly accessible 405 instance, while preserving anonymity. If you care more about performance, and a slightly 406 easier setup, use TCP.</p> 407 </section> 408 <section id="connect-to-the-public-testnet"> 409 <h2>Connect to the Public Testnet<a class="headerlink" href="#connect-to-the-public-testnet" title="Permalink to this heading">#</a></h2> 410 <p>An experimental public testnet has been made accessible over both I2P and TCP. You can join it 411 by adding one of the following interfaces to your <code class="docutils literal notranslate"><span class="pre">.reticulum/config</span></code> file:</p> 412 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># TCP/IP interface to the RNS Amsterdam Hub</span> 413 <span class="p">[[</span><span class="n">RNS</span> <span class="n">Testnet</span> <span class="n">Amsterdam</span><span class="p">]]</span> 414 <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span> 415 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 416 <span class="n">target_host</span> <span class="o">=</span> <span class="n">amsterdam</span><span class="o">.</span><span class="n">connect</span><span class="o">.</span><span class="n">reticulum</span><span class="o">.</span><span class="n">network</span> 417 <span class="n">target_port</span> <span class="o">=</span> <span class="mi">4965</span> 418 419 <span class="c1"># TCP/IP interface to the BetweenTheBorders Hub (community-provided)</span> 420 <span class="p">[[</span><span class="n">RNS</span> <span class="n">Testnet</span> <span class="n">BetweenTheBorders</span><span class="p">]]</span> 421 <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span> 422 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 423 <span class="n">target_host</span> <span class="o">=</span> <span class="n">reticulum</span><span class="o">.</span><span class="n">betweentheborders</span><span class="o">.</span><span class="n">com</span> 424 <span class="n">target_port</span> <span class="o">=</span> <span class="mi">4242</span> 425 426 <span class="c1"># Interface to Testnet I2P Hub</span> 427 <span class="p">[[</span><span class="n">RNS</span> <span class="n">Testnet</span> <span class="n">I2P</span> <span class="n">Hub</span><span class="p">]]</span> 428 <span class="nb">type</span> <span class="o">=</span> <span class="n">I2PInterface</span> 429 <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> 430 <span class="n">peers</span> <span class="o">=</span> <span class="n">g3br23bvx3lq5uddcsjii74xgmn6y5q325ovrkq2zw2wbzbqgbuq</span><span class="o">.</span><span class="n">b32</span><span class="o">.</span><span class="n">i2p</span> 431 </pre></div> 432 </div> 433 <p>Many other Reticulum instances are connecting to this testnet, and you can also join it 434 via other entry points if you know them. There is absolutely no control over the network 435 topography, usage or what types of instances connect. It will also occasionally be used 436 to test various failure scenarios, and there are no availability or service guarantees. 437 Expect weird things to happen on this network, as people experiment and try out things.</p> 438 <p>It probably goes without saying, but <em>don’t use the testnet entry-points as 439 hardcoded or default interfaces in any applications you ship to users</em>. When 440 shipping applications, the best practice is to provide your own default 441 connectivity solutions, if needed and applicable, or in most cases, simply 442 leave it up to the user which networks to connect to, and how.</p> 443 </section> 444 <section id="adding-radio-interfaces"> 445 <h2>Adding Radio Interfaces<a class="headerlink" href="#adding-radio-interfaces" title="Permalink to this heading">#</a></h2> 446 <p>Once you have Reticulum installed and working, you can add radio interfaces with 447 any compatible hardware you have available. Reticulum supports a wide range of radio 448 hardware, and if you already have any available, it is very likely that it will 449 work with Reticulum. For information on how to configure this, see the 450 <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Interfaces</span></a> section of this manual.</p> 451 <p>If you do not already have transceiver hardware available, you can easily and 452 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 453 digital radio transceiver, that integrates easily with Reticulum.</p> 454 <p>To build one yourself requires installing a custom firmware on a supported LoRa 455 development board with an auto-install script. Please see the <a class="reference internal" href="hardware.html#hardware-main"><span class="std std-ref">Communications Hardware</span></a> 456 chapter for a guide. If you prefer purchasing a ready-made unit, you can refer to the 457 <span class="xref std std-ref">list of suppliers</span>. For more information on RNode, you can also 458 refer to these additional external resources:</p> 459 <ul class="simple"> 460 <li><p><a class="reference external" href="https://unsigned.io/how-to-make-your-own-rnodes/">How To Make Your Own RNodes</a></p></li> 461 <li><p><a class="reference external" href="https://unsigned.io/installing-rnode-firmware-on-supported-devices/">Installing RNode Firmware on Compatible LoRa Devices</a></p></li> 462 <li><p><a class="reference external" href="https://unsigned.io/private-messaging-over-lora/">Private, Secure and Uncensorable Messaging Over a LoRa Mesh</a></p></li> 463 <li><p><a class="reference external" href="https://github.com/markqvist/RNode_Firmware/">RNode Firmware</a></p></li> 464 </ul> 465 <p>If you have communications hardware that is not already supported by any of the 466 <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">existing interface types</span></a>, but you think would be suitable for use with Reticulum, 467 you are welcome to head over to the <a class="reference external" href="https://github.com/markqvist/Reticulum/discussions">GitHub discussion pages</a> 468 and propose adding an interface for the hardware.</p> 469 </section> 470 <section id="creating-and-using-custom-interfaces"> 471 <h2>Creating and Using Custom Interfaces<a class="headerlink" href="#creating-and-using-custom-interfaces" title="Permalink to this heading">#</a></h2> 472 <p>While Reticulum includes a flexible and broad range of built-in interfaces, these 473 will not cover every conceivable type of communications hardware that Reticulum 474 can potentially use to communicate.</p> 475 <p>It is therefore possible to easily write your own interface modules, that can be 476 loaded at run-time and used on-par with any of the built-in interface types.</p> 477 <p>For more information on this subject, and code examples to build on, please see 478 the <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Configuring Interfaces</span></a> chapter.</p> 479 </section> 480 <section id="develop-a-program-with-reticulum"> 481 <h2>Develop a Program with Reticulum<a class="headerlink" href="#develop-a-program-with-reticulum" title="Permalink to this heading">#</a></h2> 482 <p>If you want to develop programs that use Reticulum, the easiest way to get 483 started is to install the latest release of Reticulum via pip:</p> 484 <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> 485 </pre></div> 486 </div> 487 <p>The above command will install Reticulum and dependencies, and you will be 488 ready to import and use RNS in your own programs. The next step will most 489 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> 490 <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> 491 chapter of this manual.</p> 492 </section> 493 <section id="participate-in-reticulum-development"> 494 <h2>Participate in Reticulum Development<a class="headerlink" href="#participate-in-reticulum-development" title="Permalink to this heading">#</a></h2> 495 <p>If you want to participate in the development of Reticulum and associated 496 utilities, you’ll want to get the latest source from GitHub. In that case, 497 don’t use pip, but try this recipe:</p> 498 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install dependencies</span> 499 <span class="n">pip</span> <span class="n">install</span> <span class="n">cryptography</span> <span class="n">pyserial</span> 500 501 <span class="c1"># Clone repository</span> 502 <span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">markqvist</span><span class="o">/</span><span class="n">Reticulum</span><span class="o">.</span><span class="n">git</span> 503 504 <span class="c1"># Move into Reticulum folder and symlink library to examples folder</span> 505 <span class="n">cd</span> <span class="n">Reticulum</span> 506 <span class="n">ln</span> <span class="o">-</span><span class="n">s</span> <span class="o">../</span><span class="n">RNS</span> <span class="o">./</span><span class="n">Examples</span><span class="o">/</span> 507 508 <span class="c1"># Run an example</span> 509 <span class="n">python</span> <span class="n">Examples</span><span class="o">/</span><span class="n">Echo</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">s</span> 510 511 <span class="c1"># Unless you've manually created a config file, Reticulum will do so now,</span> 512 <span class="c1"># and immediately exit. Make any necessary changes to the file:</span> 513 <span class="n">nano</span> <span class="o">~/.</span><span class="n">reticulum</span><span class="o">/</span><span class="n">config</span> 514 515 <span class="c1"># ... and launch the example again.</span> 516 <span class="n">python</span> <span class="n">Examples</span><span class="o">/</span><span class="n">Echo</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">s</span> 517 518 <span class="c1"># You can now repeat the process on another computer,</span> 519 <span class="c1"># and run the same example with -h to get command line options.</span> 520 <span class="n">python</span> <span class="n">Examples</span><span class="o">/</span><span class="n">Echo</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">h</span> 521 522 <span class="c1"># Run the example in client mode to "ping" the server.</span> 523 <span class="c1"># Replace the hash below with the actual destination hash of your server.</span> 524 <span class="n">python</span> <span class="n">Examples</span><span class="o">/</span><span class="n">Echo</span><span class="o">.</span><span class="n">py</span> <span class="mi">174</span><span class="n">a64852a75682259ad8b921b8bf416</span> 525 526 <span class="c1"># Have a look at another example</span> 527 <span class="n">python</span> <span class="n">Examples</span><span class="o">/</span><span class="n">Filetransfer</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">h</span> 528 </pre></div> 529 </div> 530 <p>When you have experimented with the basic examples, it’s time to go read the 531 <a class="reference internal" href="understanding.html#understanding-main"><span class="std std-ref">Understanding Reticulum</span></a> chapter. Before submitting 532 your first pull request, it is probably a good idea to introduce yourself on 533 the <a class="reference external" href="https://github.com/markqvist/Reticulum/discussions">disucssion forum on GitHub</a>, 534 or ask one of the developers or maintainers for a good place to start.</p> 535 </section> 536 <section id="platform-specific-install-notes"> 537 <span id="install-guides"></span><h2>Platform-Specific Install Notes<a class="headerlink" href="#platform-specific-install-notes" title="Permalink to this heading">#</a></h2> 538 <p>Some platforms require a slightly different installation procedure, or have 539 various quirks that are worth being aware of. These are listed here.</p> 540 <section id="android"> 541 <h3>Android<a class="headerlink" href="#android" title="Permalink to this heading">#</a></h3> 542 <p>Reticulum can be used on Android in different ways. The easiest way to get 543 started is using an app like <a class="reference external" href="https://unsigned.io/sideband">Sideband</a>.</p> 544 <p>For more control and features, you can use Reticulum and related programs via 545 the <a class="reference external" href="https://termux.com/">Termux app</a>, at the time of writing available on 546 <a class="reference external" href="https://f-droid.org">F-droid</a>.</p> 547 <p>Termux is a terminal emulator and Linux environment for Android based devices, 548 which includes the ability to use many different programs and libraries, 549 including Reticulum.</p> 550 <p>To use Reticulum within the Termux environment, you will need to install 551 <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 552 build into Termux. After that, you can use <code class="docutils literal notranslate"><span class="pre">pip</span></code> to install Reticulum.</p> 553 <p>From within Termux, execute the following:</p> 554 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># First, make sure indexes and packages are up to date.</span> 555 <span class="n">pkg</span> <span class="n">update</span> 556 <span class="n">pkg</span> <span class="n">upgrade</span> 557 558 <span class="c1"># Then install python and the cryptography library.</span> 559 <span class="n">pkg</span> <span class="n">install</span> <span class="n">python</span> <span class="n">python</span><span class="o">-</span><span class="n">cryptography</span> 560 561 <span class="c1"># Make sure pip is up to date, and install the wheel module.</span> 562 <span class="n">pip</span> <span class="n">install</span> <span class="n">wheel</span> <span class="n">pip</span> <span class="o">--</span><span class="n">upgrade</span> 563 564 <span class="c1"># Install Reticulum</span> 565 <span class="n">pip</span> <span class="n">install</span> <span class="n">rns</span> 566 </pre></div> 567 </div> 568 <p>If for some reason the <code class="docutils literal notranslate"><span class="pre">python-cryptography</span></code> package is not available for 569 your platform via the Termux package manager, you can attempt to build it 570 locally on your device using the following command:</p> 571 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># First, make sure indexes and packages are up to date.</span> 572 <span class="n">pkg</span> <span class="n">update</span> 573 <span class="n">pkg</span> <span class="n">upgrade</span> 574 575 <span class="c1"># Then install dependencies for the cryptography library.</span> 576 <span class="n">pkg</span> <span class="n">install</span> <span class="n">python</span> <span class="n">build</span><span class="o">-</span><span class="n">essential</span> <span class="n">openssl</span> <span class="n">libffi</span> <span class="n">rust</span> 577 578 <span class="c1"># Make sure pip is up to date, and install the wheel module.</span> 579 <span class="n">pip</span> <span class="n">install</span> <span class="n">wheel</span> <span class="n">pip</span> <span class="o">--</span><span class="n">upgrade</span> 580 581 <span class="c1"># To allow the installer to build the cryptography module,</span> 582 <span class="c1"># we need to let it know what platform we are compiling for:</span> 583 <span class="n">export</span> <span class="n">CARGO_BUILD_TARGET</span><span class="o">=</span><span class="s2">"aarch64-linux-android"</span> 584 585 <span class="c1"># Start the install process for the cryptography module.</span> 586 <span class="c1"># Depending on your device, this can take several minutes,</span> 587 <span class="c1"># since the module must be compiled locally on your device.</span> 588 <span class="n">pip</span> <span class="n">install</span> <span class="n">cryptography</span> 589 590 <span class="c1"># If the above installation succeeds, you can now install</span> 591 <span class="c1"># Reticulum and any related software</span> 592 <span class="n">pip</span> <span class="n">install</span> <span class="n">rns</span> 593 </pre></div> 594 </div> 595 <p>It is also possible to include Reticulum in apps compiled and distributed as 596 Android APKs. A detailed tutorial and example source code will be included 597 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> 598 </section> 599 <section id="arm64"> 600 <h3>ARM64<a class="headerlink" href="#arm64" title="Permalink to this heading">#</a></h3> 601 <p>On some architectures, including ARM64, not all dependencies have precompiled 602 binaries. On such systems, you may need to install <code class="docutils literal notranslate"><span class="pre">python3-dev</span></code> (or similar) before 603 installing Reticulum or programs that depend on Reticulum.</p> 604 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install Python and development packages</span> 605 <span class="n">sudo</span> <span class="n">apt</span> <span class="n">update</span> 606 <span class="n">sudo</span> <span class="n">apt</span> <span class="n">install</span> <span class="n">python3</span> <span class="n">python3</span><span class="o">-</span><span class="n">pip</span> <span class="n">python3</span><span class="o">-</span><span class="n">dev</span> 607 608 <span class="c1"># Install Reticulum</span> 609 <span class="n">python3</span> <span class="o">-</span><span class="n">m</span> <span class="n">pip</span> <span class="n">install</span> <span class="n">rns</span> 610 </pre></div> 611 </div> 612 <p>With these packages installed, <code class="docutils literal notranslate"><span class="pre">pip</span></code> will be able to build any missing dependencies 613 on your system locally.</p> 614 </section> 615 <section id="debian-bookworm"> 616 <h3>Debian Bookworm<a class="headerlink" href="#debian-bookworm" title="Permalink to this heading">#</a></h3> 617 <p>On versions of Debian released after April 2023, it is no longer possible by default 618 to use <code class="docutils literal notranslate"><span class="pre">pip</span></code> to install packages onto your system. Unfortunately, you will need to 619 use the replacement <code class="docutils literal notranslate"><span class="pre">pipx</span></code> command instead, which places installed packages in an 620 isolated environment. This should not negatively affect Reticulum, but will not work 621 for including and using Reticulum in your own scripts and programs.</p> 622 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install pipx</span> 623 <span class="n">sudo</span> <span class="n">apt</span> <span class="n">install</span> <span class="n">pipx</span> 624 625 <span class="c1"># Make installed programs available on the command line</span> 626 <span class="n">pipx</span> <span class="n">ensurepath</span> 627 628 <span class="c1"># Install Reticulum</span> 629 <span class="n">pipx</span> <span class="n">install</span> <span class="n">rns</span> 630 </pre></div> 631 </div> 632 <p>Alternatively, you can restore normal behaviour to <code class="docutils literal notranslate"><span class="pre">pip</span></code> by creating or editing 633 the configuration file located at <code class="docutils literal notranslate"><span class="pre">~/.config/pip/pip.conf</span></code>, and adding the 634 following section:</p> 635 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[global] 636 break-system-packages = true 637 </pre></div> 638 </div> 639 <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> 640 option, you can use the following command:</p> 641 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>pip install rns --break-system-packages 642 </pre></div> 643 </div> 644 <div class="admonition note"> 645 <p class="admonition-title">Note</p> 646 <p>The <code class="docutils literal notranslate"><span class="pre">--break-system-packages</span></code> directive is a somewhat misleading choice 647 of words. Setting it will of course not break any system packages, but will simply 648 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 649 cases lead to version conflicts, it does not generally pose any problems, especially 650 not in the case of installing Reticulum.</p> 651 </div> 652 </section> 653 <section id="macos"> 654 <h3>MacOS<a class="headerlink" href="#macos" title="Permalink to this heading">#</a></h3> 655 <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 656 manager installed.</p> 657 <p>Systems running macOS can vary quite widely in whether or not Python is pre-installed, 658 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 659 also installed and set up. If in doubt, you can <a class="reference external" href="https://www.python.org/downloads/">download and install</a> 660 Python manually.</p> 661 <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 662 and use one of the following commands:</p> 663 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install Reticulum and utilities with pip:</span> 664 <span class="n">pip3</span> <span class="n">install</span> <span class="n">rns</span> 665 666 <span class="c1"># On some versions, you may need to use the</span> 667 <span class="c1"># flag --break-system-packages to install:</span> 668 <span class="n">pip3</span> <span class="n">install</span> <span class="n">rns</span> <span class="o">--</span><span class="k">break</span><span class="o">-</span><span class="n">system</span><span class="o">-</span><span class="n">packages</span> 669 </pre></div> 670 </div> 671 <div class="admonition note"> 672 <p class="admonition-title">Note</p> 673 <p>The <code class="docutils literal notranslate"><span class="pre">--break-system-packages</span></code> directive is a somewhat misleading choice 674 of words. Setting it will of course not break any system packages, but will simply 675 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 676 cases lead to version conflicts, it does not generally pose any problems, especially 677 not in the case of installing Reticulum.</p> 678 </div> 679 <p>Additionally, some version combinations of macOS and Python require you to 680 manually add your installed <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages directory to your <cite>PATH</cite> environment 681 variable, before you can use installed commands in your terminal. Usually, adding 682 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> 683 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>export PATH=$PATH:~/Library/Python/3.9/bin 684 </pre></div> 685 </div> 686 <p>Adjust Python version and shell init script location according to your system.</p> 687 </section> 688 <section id="openwrt"> 689 <h3>OpenWRT<a class="headerlink" href="#openwrt" title="Permalink to this heading">#</a></h3> 690 <p>On OpenWRT systems with sufficient storage and memory, you can install 691 Reticulum and related utilities using the <cite>opkg</cite> package manager and <cite>pip</cite>.</p> 692 <div class="admonition note"> 693 <p class="admonition-title">Note</p> 694 <p>At the time of releasing this manual, work is underway to create pre-built 695 Reticulum packages for OpenWRT, with full configuration, service 696 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> 697 and <a class="reference external" href="https://github.com/gretel/reticulum-openwrt">reticulum-openwrt</a> 698 repositories for more information.</p> 699 </div> 700 <p>To install Reticulum on OpenWRT, first log into a command line session, and 701 then use the following instructions:</p> 702 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install dependencies</span> 703 <span class="n">opkg</span> <span class="n">install</span> <span class="n">python3</span> <span class="n">python3</span><span class="o">-</span><span class="n">pip</span> <span class="n">python3</span><span class="o">-</span><span class="n">cryptography</span> <span class="n">python3</span><span class="o">-</span><span class="n">pyserial</span> 704 705 <span class="c1"># Install Reticulum</span> 706 <span class="n">pip</span> <span class="n">install</span> <span class="n">rns</span> 707 708 <span class="c1"># Start rnsd with debug logging enabled</span> 709 <span class="n">rnsd</span> <span class="o">-</span><span class="n">vvv</span> 710 </pre></div> 711 </div> 712 <div class="admonition note"> 713 <p class="admonition-title">Note</p> 714 <p>The above instructions have been verified and tested on OpenWRT 21.02 only. 715 It is likely that other versions may require slightly altered installation 716 commands or package names. You will also need enough free space in your 717 overlay FS, and enough free RAM to actually run Reticulum and any related 718 programs and utilities.</p> 719 </div> 720 <p>Depending on your device configuration, you may need to adjust firewall rules 721 for Reticulum connectivity to and from your device to work. Until proper 722 packaging is ready, you will also need to manually create a service or startup 723 script to automatically laucnh Reticulum at boot time.</p> 724 <p>Please also note that the <cite>AutoInterface</cite> requires link-local IPv6 addresses 725 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> 726 shows an address starting with <code class="docutils literal notranslate"><span class="pre">fe80::</span></code> for the device in question, 727 <code class="docutils literal notranslate"><span class="pre">AutoInterface</span></code> should work for that device.</p> 728 </section> 729 <section id="raspberry-pi"> 730 <h3>Raspberry Pi<a class="headerlink" href="#raspberry-pi" title="Permalink to this heading">#</a></h3> 731 <p>It is currently recommended to use a 64-bit version of the Raspberry Pi OS 732 if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions 733 don’t always have packages available for some dependencies. If Python and the 734 <cite>pip</cite> package manager is not already installed, do that first, and then 735 install Reticulum using <cite>pip</cite>.</p> 736 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install dependencies</span> 737 <span class="n">sudo</span> <span class="n">apt</span> <span class="n">install</span> <span class="n">python3</span> <span class="n">python3</span><span class="o">-</span><span class="n">pip</span> <span class="n">python3</span><span class="o">-</span><span class="n">cryptography</span> <span class="n">python3</span><span class="o">-</span><span class="n">pyserial</span> 738 739 <span class="c1"># Install Reticulum</span> 740 <span class="n">pip</span> <span class="n">install</span> <span class="n">rns</span> <span class="o">--</span><span class="k">break</span><span class="o">-</span><span class="n">system</span><span class="o">-</span><span class="n">packages</span> 741 </pre></div> 742 </div> 743 <div class="admonition note"> 744 <p class="admonition-title">Note</p> 745 <p>The <code class="docutils literal notranslate"><span class="pre">--break-system-packages</span></code> directive is a somewhat misleading choice 746 of words. Setting it will of course not break any system packages, but will simply 747 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 748 cases lead to version conflicts, it does not generally pose any problems, especially 749 not in the case of installing Reticulum.</p> 750 </div> 751 <p>While it is possible to install and run Reticulum on 32-bit Rasperry Pi OSes, 752 it will require manually configuring and installing required build dependencies, 753 and is not detailed in this manual.</p> 754 </section> 755 <section id="risc-v"> 756 <h3>RISC-V<a class="headerlink" href="#risc-v" title="Permalink to this heading">#</a></h3> 757 <p>On some architectures, including RISC-V, not all dependencies have precompiled 758 binaries. On such systems, you may need to install <code class="docutils literal notranslate"><span class="pre">python3-dev</span></code> (or similar) before 759 installing Reticulum or programs that depend on Reticulum.</p> 760 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install Python and development packages</span> 761 <span class="n">sudo</span> <span class="n">apt</span> <span class="n">update</span> 762 <span class="n">sudo</span> <span class="n">apt</span> <span class="n">install</span> <span class="n">python3</span> <span class="n">python3</span><span class="o">-</span><span class="n">pip</span> <span class="n">python3</span><span class="o">-</span><span class="n">dev</span> 763 764 <span class="c1"># Install Reticulum</span> 765 <span class="n">python3</span> <span class="o">-</span><span class="n">m</span> <span class="n">pip</span> <span class="n">install</span> <span class="n">rns</span> 766 </pre></div> 767 </div> 768 <p>With these packages installed, <code class="docutils literal notranslate"><span class="pre">pip</span></code> will be able to build any missing dependencies 769 on your system locally.</p> 770 </section> 771 <section id="ubuntu-lunar"> 772 <h3>Ubuntu Lunar<a class="headerlink" href="#ubuntu-lunar" title="Permalink to this heading">#</a></h3> 773 <p>On versions of Ubuntu released after April 2023, it is no longer possible by default 774 to use <code class="docutils literal notranslate"><span class="pre">pip</span></code> to install packages onto your system. Unfortunately, you will need to 775 use the replacement <code class="docutils literal notranslate"><span class="pre">pipx</span></code> command instead, which places installed packages in an 776 isolated environment. This should not negatively affect Reticulum, but will not work 777 for including and using Reticulum in your own scripts and programs.</p> 778 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install pipx</span> 779 <span class="n">sudo</span> <span class="n">apt</span> <span class="n">install</span> <span class="n">pipx</span> 780 781 <span class="c1"># Make installed programs available on the command line</span> 782 <span class="n">pipx</span> <span class="n">ensurepath</span> 783 784 <span class="c1"># Install Reticulum</span> 785 <span class="n">pipx</span> <span class="n">install</span> <span class="n">rns</span> 786 </pre></div> 787 </div> 788 <p>Alternatively, you can restore normal behaviour to <code class="docutils literal notranslate"><span class="pre">pip</span></code> by creating or editing 789 the configuration file located at <code class="docutils literal notranslate"><span class="pre">~/.config/pip/pip.conf</span></code>, and adding the 790 following section:</p> 791 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[global] 792 break-system-packages = true 793 </pre></div> 794 </div> 795 <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> 796 option, you can use the following command:</p> 797 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>pip install rns --break-system-packages 798 </pre></div> 799 </div> 800 <div class="admonition note"> 801 <p class="admonition-title">Note</p> 802 <p>The <code class="docutils literal notranslate"><span class="pre">--break-system-packages</span></code> directive is a somewhat misleading choice 803 of words. Setting it will of course not break any system packages, but will simply 804 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 805 cases lead to version conflicts, it does not generally pose any problems, especially 806 not in the case of installing Reticulum.</p> 807 </div> 808 </section> 809 <section id="windows"> 810 <h3>Windows<a class="headerlink" href="#windows" title="Permalink to this heading">#</a></h3> 811 <p>On Windows operating systems, the easiest way to install Reticulum is by using the 812 <code class="docutils literal notranslate"><span class="pre">pip</span></code> package manager from the command line (either the command prompt or Windows 813 Powershell).</p> 814 <p>If you don’t already have Python installed, <a class="reference external" href="https://www.python.org/downloads/">download and install Python</a>. 815 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> 816 <p><strong>Important!</strong> When asked by the installer, make sure to add the Python program to 817 your PATH environment variables. If you don’t do this, you will not be able to 818 use the <code class="docutils literal notranslate"><span class="pre">pip</span></code> installer, or run the included Reticulum utility programs (such as 819 <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> 820 <p>After installing Python, open the command prompt or Windows Powershell, and type:</p> 821 <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> 822 </pre></div> 823 </div> 824 <p>You can now use Reticulum and all included utility programs directly from your 825 preferred command line interface.</p> 826 </section> 827 </section> 828 <section id="pure-python-reticulum"> 829 <h2>Pure-Python Reticulum<a class="headerlink" href="#pure-python-reticulum" title="Permalink to this heading">#</a></h2> 830 <div class="admonition warning"> 831 <p class="admonition-title">Warning</p> 832 <p>If you use the <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> package to run Reticulum on systems that 833 do not support <a class="reference external" href="https://github.com/pyca/cryptography">PyCA/cryptography</a>, it is 834 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> 835 section of this manual.</p> 836 </div> 837 <p>In some rare cases, and on more obscure system types, it is not possible to 838 install one or more dependencies. In such situations, 839 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> 840 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> 841 package requires no external dependencies for installation. Please note that the 842 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>. 843 The only difference is that the <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> package lists no dependencies required 844 for installation.</p> 845 <p>No matter how Reticulum is installed and started, it will load external dependencies 846 only if they are <em>needed</em> and <em>available</em>. If for example you want to use Reticulum 847 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 848 the <cite>rnspure</cite> package, but Reticulum will not be able to use serial-based interfaces. 849 All other available modules will still be loaded when needed.</p> 850 </section> 851 </section> 852 853 </article> 854 </div> 855 <footer> 856 857 <div class="related-pages"> 858 <a class="next-page" href="using.html"> 859 <div class="page-info"> 860 <div class="context"> 861 <span>Next</span> 862 </div> 863 <div class="title">Using Reticulum on Your System</div> 864 </div> 865 <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> 866 </a> 867 <a class="prev-page" href="whatis.html"> 868 <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> 869 <div class="page-info"> 870 <div class="context"> 871 <span>Previous</span> 872 </div> 873 874 <div class="title">What is Reticulum?</div> 875 876 </div> 877 </a> 878 </div> 879 <div class="bottom-of-page"> 880 <div class="left-details"> 881 <div class="copyright"> 882 Copyright © 2023, Mark Qvist 883 </div> 884 Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 885 <a href="https://github.com/pradyunsg/furo">Furo</a> 886 887 </div> 888 <div class="right-details"> 889 <div class="icons"> 890 891 </div> 892 </div> 893 </div> 894 895 </footer> 896 </div> 897 <aside class="toc-drawer"> 898 899 900 <div class="toc-sticky toc-scroll"> 901 <div class="toc-title-container"> 902 <span class="toc-title"> 903 On this page 904 </span> 905 </div> 906 <div class="toc-tree-container"> 907 <div class="toc-tree"> 908 <ul> 909 <li><a class="reference internal" href="#">Getting Started Fast</a><ul> 910 <li><a class="reference internal" href="#standalone-reticulum-installation">Standalone Reticulum Installation</a><ul> 911 <li><a class="reference internal" href="#resolving-dependency-installation-issues">Resolving Dependency & Installation Issues</a></li> 912 </ul> 913 </li> 914 <li><a class="reference internal" href="#try-using-a-reticulum-based-program">Try Using a Reticulum-based Program</a><ul> 915 <li><a class="reference internal" href="#remote-shell">Remote Shell</a></li> 916 <li><a class="reference internal" href="#nomad-network">Nomad Network</a></li> 917 <li><a class="reference internal" href="#sideband">Sideband</a></li> 918 <li><a class="reference internal" href="#meshchat">MeshChat</a></li> 919 </ul> 920 </li> 921 <li><a class="reference internal" href="#using-the-included-utilities">Using the Included Utilities</a></li> 922 <li><a class="reference internal" href="#creating-a-network-with-reticulum">Creating a Network With Reticulum</a></li> 923 <li><a class="reference internal" href="#connecting-reticulum-instances-over-the-internet">Connecting Reticulum Instances Over the Internet</a></li> 924 <li><a class="reference internal" href="#connect-to-the-public-testnet">Connect to the Public Testnet</a></li> 925 <li><a class="reference internal" href="#adding-radio-interfaces">Adding Radio Interfaces</a></li> 926 <li><a class="reference internal" href="#creating-and-using-custom-interfaces">Creating and Using Custom Interfaces</a></li> 927 <li><a class="reference internal" href="#develop-a-program-with-reticulum">Develop a Program with Reticulum</a></li> 928 <li><a class="reference internal" href="#participate-in-reticulum-development">Participate in Reticulum Development</a></li> 929 <li><a class="reference internal" href="#platform-specific-install-notes">Platform-Specific Install Notes</a><ul> 930 <li><a class="reference internal" href="#android">Android</a></li> 931 <li><a class="reference internal" href="#arm64">ARM64</a></li> 932 <li><a class="reference internal" href="#debian-bookworm">Debian Bookworm</a></li> 933 <li><a class="reference internal" href="#macos">MacOS</a></li> 934 <li><a class="reference internal" href="#openwrt">OpenWRT</a></li> 935 <li><a class="reference internal" href="#raspberry-pi">Raspberry Pi</a></li> 936 <li><a class="reference internal" href="#risc-v">RISC-V</a></li> 937 <li><a class="reference internal" href="#ubuntu-lunar">Ubuntu Lunar</a></li> 938 <li><a class="reference internal" href="#windows">Windows</a></li> 939 </ul> 940 </li> 941 <li><a class="reference internal" href="#pure-python-reticulum">Pure-Python Reticulum</a></li> 942 </ul> 943 </li> 944 </ul> 945 946 </div> 947 </div> 948 </div> 949 950 951 </aside> 952 </div> 953 </div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> 954 <script src="_static/jquery.js"></script> 955 <script src="_static/underscore.js"></script> 956 <script src="_static/_sphinx_javascript_frameworks_compat.js"></script> 957 <script src="_static/doctools.js"></script> 958 <script src="_static/sphinx_highlight.js"></script> 959 <script src="_static/scripts/furo.js"></script> 960 <script src="_static/clipboard.min.js"></script> 961 <script src="_static/copybutton.js"></script> 962 </body> 963 </html>