<!doctype html> <html class="no-js" lang="en"> <head><meta charset="utf-8"/> <meta name="viewport" content="width=device-width,initial-scale=1"/> <meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" /> <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" /> <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29.dev1"/> <title>Getting Started Fast - Reticulum Network Stack 0.8.6 beta documentation</title> <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" /> <link rel="stylesheet" type="text/css" href="_static/copybutton.css" /> <link rel="stylesheet" type="text/css" href="_static/styles/furo-extensions.css?digest=30d1aed668e5c3a91c3e3bf6a60b675221979f0e" /> <link rel="stylesheet" type="text/css" href="_static/custom.css" /> <style> body { --color-code-background: #f8f8f8; --color-code-foreground: black; } @media not print { body[data-theme="dark"] { --color-code-background: #202020; --color-code-foreground: #d0d0d0; --color-background-primary: #202b38; --color-background-secondary: #161f27; --color-foreground-primary: #dbdbdb; --color-foreground-secondary: #a9b1ba; --color-brand-primary: #41adff; --color-background-hover: #161f27; --color-api-name: #ffbe85; --color-api-pre-name: #efae75; } @media (prefers-color-scheme: dark) { body:not([data-theme="light"]) { --color-code-background: #202020; --color-code-foreground: #d0d0d0; --color-background-primary: #202b38; --color-background-secondary: #161f27; --color-foreground-primary: #dbdbdb; --color-foreground-secondary: #a9b1ba; --color-brand-primary: #41adff; --color-background-hover: #161f27; --color-api-name: #ffbe85; --color-api-pre-name: #efae75; } } } </style></head> <body> <script> document.body.dataset.theme = localStorage.getItem("theme") || "auto"; </script> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-toc" viewBox="0 0 24 24"> <title>Contents</title> <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024"> <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"/> </svg> </symbol> <symbol id="svg-menu" viewBox="0 0 24 24"> <title>Menu</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu"> <line x1="3" y1="12" x2="21" y2="12"></line> <line x1="3" y1="6" x2="21" y2="6"></line> <line x1="3" y1="18" x2="21" y2="18"></line> </svg> </symbol> <symbol id="svg-arrow-right" viewBox="0 0 24 24"> <title>Expand</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right"> <polyline points="9 18 15 12 9 6"></polyline> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24"> <title>Light mode</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="feather-sun"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24"> <title>Dark mode</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon"> <path stroke="none" d="M0 0h24v24H0z" fill="none" /> <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" /> </svg> </symbol> <symbol id="svg-sun-half" viewBox="0 0 24 24"> <title>Auto light/dark mode</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-shadow"> <path stroke="none" d="M0 0h24v24H0z" fill="none"/> <circle cx="12" cy="12" r="9" /> <path d="M13 12h5" /> <path d="M13 15h4" /> <path d="M13 18h1" /> <path d="M13 9h4" /> <path d="M13 6h1" /> </svg> </symbol> </svg> <input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation"> <input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc"> <label class="overlay sidebar-overlay" for="__navigation"> <div class="visually-hidden">Hide navigation sidebar</div> </label> <label class="overlay toc-overlay" for="__toc"> <div class="visually-hidden">Hide table of contents sidebar</div> </label> <div class="page"> <header class="mobile-header"> <div class="header-left"> <label class="nav-overlay-icon" for="__navigation"> <div class="visually-hidden">Toggle site navigation sidebar</div> <i class="icon"><svg><use href="#svg-menu"></use></svg></i> </label> </div> <div class="header-center"> <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.6 beta documentation</div></a> </div> <div class="header-right"> <div class="theme-toggle-container theme-toggle-header"> <button class="theme-toggle"> <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div> <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg> </button> </div> <label class="toc-overlay-icon toc-header-icon" for="__toc"> <div class="visually-hidden">Toggle table of contents sidebar</div> <i class="icon"><svg><use href="#svg-toc"></use></svg></i> </label> </div> </header> <aside class="sidebar-drawer"> <div class="sidebar-container"> <div class="sidebar-sticky"><a class="sidebar-brand centered" href="index.html"> <div class="sidebar-logo-container"> <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/> </div> <span class="sidebar-brand-text">Reticulum Network Stack 0.8.6 beta documentation</span> </a><form class="sidebar-search-container" method="get" action="search.html" role="search"> <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search"> <input type="hidden" name="check_keywords" value="yes"> <input type="hidden" name="area" value="default"> </form> <div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree"> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li> <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Getting Started Fast</a></li> <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li> <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li> <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li> <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li> <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li> <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li> <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li> </ul> <ul> <li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li> </ul> </div> </div> </div> </div> </aside> <div class="main"> <div class="content"> <div class="article-container"> <a href="#" class="back-to-top muted-link"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"> <path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path> </svg> <span>Back to top</span> </a> <div class="content-icon-container"> <div class="theme-toggle-container theme-toggle-content"> <button class="theme-toggle"> <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div> <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg> </button> </div> <label class="toc-overlay-icon toc-content-icon" for="__toc"> <div class="visually-hidden">Toggle table of contents sidebar</div> <i class="icon"><svg><use href="#svg-toc"></use></svg></i> </label> </div> <article role="main"> <section id="getting-started-fast"> <h1>Getting Started Fast<a class="headerlink" href="#getting-started-fast" title="Permalink to this heading">#</a></h1> <p>The best way to get started with the Reticulum Network Stack depends on what you want to do. This guide will outline sensible starting paths for different scenarios.</p> <section id="standalone-reticulum-installation"> <h2>Standalone Reticulum Installation<a class="headerlink" href="#standalone-reticulum-installation" title="Permalink to this heading">#</a></h2> <p>If you simply want to install Reticulum and related utilities on a system, the easiest way is via the <code class="docutils literal notranslate"><span class="pre">pip</span></code> package manager:</p> <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> </pre></div> </div> <p>If you do not already have pip installed, you can install it using the package manager 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>, <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> <p>You can also dowload the Reticulum release wheels from GitHub, or other release channels, and install them offline using <code class="docutils literal notranslate"><span class="pre">pip</span></code>:</p> <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> </pre></div> </div> </section> <section id="resolving-dependency-installation-issues"> <h2>Resolving Dependency & Installation Issues<a class="headerlink" href="#resolving-dependency-installation-issues" title="Permalink to this heading">#</a></h2> <p>On some platforms, there may not be binary packages available for all dependencies, and <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 be resolved by installing the development essentials packages for your platform:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Debian / Ubuntu / Derivatives</span> <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> <span class="c1"># Arch / Manjaro / Derivatives</span> <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> <span class="c1"># Fedora</span> <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> </pre></div> </div> <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 dependencies from source, and complete installation even on platforms that don’t have pre- compiled packages available.</p> </section> <section id="try-using-a-reticulum-based-program"> <h2>Try Using a Reticulum-based Program<a class="headerlink" href="#try-using-a-reticulum-based-program" title="Permalink to this heading">#</a></h2> <p>If you simply want to try using a program built with Reticulum, a few different programs exist that allow basic communication and a range of other useful functions, even over extremely low-bandwidth Reticulum networks.</p> <p>These programs will let you get a feel for how Reticulum works. They have been designed to run well over networks based on LoRa or packet radio, but can also be used over fast links, such as local WiFi, wired Ethernet, the Internet, or any combination.</p> <p>As such, it is easy to get started experimenting, without having to set up any radio transceivers or infrastructure just to try it out. Launching the programs on separate devices connected to the same WiFi network is enough to get started, and physical radio interfaces can then be added later.</p> <section id="remote-shell"> <h3>Remote Shell<a class="headerlink" href="#remote-shell" title="Permalink to this heading">#</a></h3> <p>The <a class="reference external" href="https://github.com/acehoss/rnsh">rnsh</a> program lets you establish fully interactive remote shell sessions over Reticulum. It also allows you to pipe any program to or from a 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 can facilitate fully interactive shell sessions, even over extremely low-bandwidth links, such as LoRa or packet radio.</p> </section> <section id="nomad-network"> <h3>Nomad Network<a class="headerlink" href="#nomad-network" title="Permalink to this heading">#</a></h3> <p>The terminal-based program <a class="reference external" href="https://github.com/markqvist/nomadnet">Nomad Network</a> provides a complete encrypted communications suite built with Reticulum. It features encrypted messaging (both direct and delayed-delivery for offline users), file sharing, and has a built-in text-browser and page server with support for dynamically rendered pages, user authentication and more.</p> <a class="reference external image-reference" href="_images/nomadnet_3.png"><img alt="_images/nomadnet_3.png" src="_images/nomadnet_3.png" /></a> <p><a class="reference external" href="https://github.com/markqvist/nomadnet">Nomad Network</a> is a user-facing client for the messaging and information-sharing protocol <a class="reference external" href="https://github.com/markqvist/lxmf">LXMF</a>, another project built with Reticulum.</p> <p>You can install Nomad Network via pip:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install ...</span> <span class="n">pip</span> <span class="n">install</span> <span class="n">nomadnet</span> <span class="c1"># ... and run</span> <span class="n">nomadnet</span> </pre></div> </div> <p><strong>Please Note</strong>: If this is the very first time you use pip to install a program on your system, you might need to reboot your system for your program to become available. If you get a “command not found” error or similar when running the program, reboot your system and try again.</p> </section> <section id="sideband"> <h3>Sideband<a class="headerlink" href="#sideband" title="Permalink to this heading">#</a></h3> <p>If you would rather use a program with a graphical user interface, you can take a look at <a class="reference external" href="https://unsigned.io/sideband">Sideband</a>, which is available for Android, Linux, macOS and Windows.</p> <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" /></a> <p>Sideband allows you to communicate with other people or LXMF-compatible systems over Reticulum networks using LoRa, Packet Radio, WiFi, I2P, Encrypted QR Paper Messages, or anything else Reticulum supports. It also interoperates with the Nomad Network program.</p> </section> <section id="meshchat"> <h3>MeshChat<a class="headerlink" href="#meshchat" title="Permalink to this heading">#</a></h3> <p>The <a class="reference external" href="https://github.com/liamcottle/reticulum-meshchat">Reticulum MeshChat</a> application is a user-friendly LXMF client for macOS and Windows, that also includes voice call functionality, and a range of other interesting functions.</p> <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" /></a> <p>Reticulum MeshChat is of course also compatible with Sideband and Nomad Network, or any other LXMF client.</p> </section> </section> <section id="using-the-included-utilities"> <h2>Using the Included Utilities<a class="headerlink" href="#using-the-included-utilities" title="Permalink to this heading">#</a></h2> <p>Reticulum comes with a range of included utilities that make it easier to manage your network, check connectivity and make Reticulum available to other programs on your system.</p> <p>You can use <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> to run Reticulum as a background or foreground service, 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 network status and connectivity.</p> <p>To learn more about these utility programs, have a look at the <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> </section> <section id="creating-a-network-with-reticulum"> <h2>Creating a Network With Reticulum<a class="headerlink" href="#creating-a-network-with-reticulum" title="Permalink to this heading">#</a></h2> <p>To create a network, you will need to specify one or more <em>interfaces</em> for Reticulum to use. This is done in the Reticulum configuration file, which by default is located at <code class="docutils literal notranslate"><span class="pre">~/.reticulum/config</span></code>. You can get an example configuration file with all options via <code class="docutils literal notranslate"><span class="pre">rnsd</span> <span class="pre">--exampleconfig</span></code>.</p> <p>When Reticulum is started for the first time, it will create a default configuration file, with one active interface. This default interface uses your existing Ethernet and WiFi networks (if any), and only allows you to communicate with other Reticulum peers within your local broadcast domains.</p> <p>To communicate further, you will have to add one or more interfaces. The default configuration includes a number of examples, ranging from using TCP over the internet, to LoRa and Packet Radio interfaces.</p> <p>With Reticulum, you only need to configure what interfaces you want to communicate over. There is no need to configure address spaces, subnets, routing tables, or other things you might be used to from other network types.</p> <p>Once Reticulum knows which interfaces it should use, it will automatically discover topography and configure transport of data to any destinations it knows about.</p> <p>In situations where you already have an established WiFi or Ethernet network, and many devices that want to utilise the same external Reticulum network paths (for example over LoRa), it will often be sufficient to let one system act as a Reticulum gateway, by adding any external interfaces to the configuration of this system, and then enabling transport on it. Any other device on your local WiFi will then be able to connect to this wider Reticulum network just using the default (<a class="reference internal" href="interfaces.html#interfaces-auto"><span class="std std-ref">AutoInterface</span></a>) configuration.</p> <p>Possibly, the examples in the config file are enough to get you started. If 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> and <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Interfaces</span></a> chapters of this manual.</p> </section> <section id="connecting-reticulum-instances-over-the-internet"> <h2>Connecting Reticulum Instances Over the Internet<a class="headerlink" href="#connecting-reticulum-instances-over-the-internet" title="Permalink to this heading">#</a></h2> <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> 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 users should carefully choose the interface which best suites their needs.</p> <p>The <code class="docutils literal notranslate"><span class="pre">TCPServerInterface</span></code> allows users to host an instance accessible over TCP/IP. This method is generally faster, lower latency, and more energy efficient than using <code class="docutils literal notranslate"><span class="pre">I2PInterface</span></code>, however it also leaks more data about the server host.</p> <p>TCP connections reveal the IP address of both your instance and the server to anyone who can inspect the connection. Someone could use this information to determine your location or identity. Adversaries inspecting your packets may be able to record packet metadata like time of transmission and packet size. Even though Reticulum encrypts traffic, TCP does not, so an adversary may be able to use packet inspection to learn that a system is running Reticulum, and what other IP addresses connect to it. Hosting a publicly reachable instance over TCP also requires a publicly reachable IP address, which most Internet connections don’t offer anymore.</p> <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 (I2P)</a>. To use this interface, users must also run an I2P daemon in 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> <p>By default, I2P will encrypt and mix all traffic sent over the Internet, and hide both the sender and receiver Reticulum instance IP addresses. Running an I2P node will also relay other I2P user’s encrypted packets, which will use extra bandwidth and compute power, but also makes timing attacks and other forms of deep-packet-inspection much more difficult.</p> <p>I2P also allows users to host globally available Reticulum instances from non-public IP’s and behind firewalls and NAT.</p> <p>In general it is recommended to use an I2P node if you want to host a publicly accessible instance, while preserving anonymity. If you care more about performance, and a slightly easier setup, use TCP.</p> </section> <section id="connect-to-the-public-testnet"> <h2>Connect to the Public Testnet<a class="headerlink" href="#connect-to-the-public-testnet" title="Permalink to this heading">#</a></h2> <p>An experimental public testnet has been made accessible over both I2P and TCP. You can join it by adding one of the following interfaces to your <code class="docutils literal notranslate"><span class="pre">.reticulum/config</span></code> file:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># TCP/IP interface to the RNS Amsterdam Hub</span> <span class="p">[[</span><span class="n">RNS</span> <span class="n">Testnet</span> <span class="n">Amsterdam</span><span class="p">]]</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span> <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> <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> <span class="n">target_port</span> <span class="o">=</span> <span class="mi">4965</span> <span class="c1"># TCP/IP interface to the BetweenTheBorders Hub (community-provided)</span> <span class="p">[[</span><span class="n">RNS</span> <span class="n">Testnet</span> <span class="n">BetweenTheBorders</span><span class="p">]]</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span> <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> <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> <span class="n">target_port</span> <span class="o">=</span> <span class="mi">4242</span> <span class="c1"># Interface to Testnet I2P Hub</span> <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> <span class="nb">type</span> <span class="o">=</span> <span class="n">I2PInterface</span> <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span> <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> </pre></div> </div> <p>Many other Reticulum instances are connecting to this testnet, and you can also join it via other entry points if you know them. There is absolutely no control over the network topography, usage or what types of instances connect. It will also occasionally be used to test various failure scenarios, and there are no availability or service guarantees. Expect weird things to happen on this network, as people experiment and try out things.</p> <p>It probably goes without saying, but <em>don’t use the testnet entry-points as hardcoded or default interfaces in any applications you ship to users</em>. When shipping applications, the best practice is to provide your own default connectivity solutions, if needed and applicable, or in most cases, simply leave it up to the user which networks to connect to, and how.</p> </section> <section id="adding-radio-interfaces"> <h2>Adding Radio Interfaces<a class="headerlink" href="#adding-radio-interfaces" title="Permalink to this heading">#</a></h2> <p>Once you have Reticulum installed and working, you can add radio interfaces with any compatible hardware you have available. Reticulum supports a wide range of radio hardware, and if you already have any available, it is very likely that it will work with Reticulum. For information on how to configure this, see the <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Interfaces</span></a> section of this manual.</p> <p>If you do not already have transceiver hardware available, you can easily and 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 digital radio transceiver, that integrates easily with Reticulum.</p> <p>To build one yourself requires installing a custom firmware on a supported LoRa 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> chapter for a guide. If you prefer purchasing a ready-made unit, you can refer to the <span class="xref std std-ref">list of suppliers</span>. For more information on RNode, you can also refer to these additional external resources:</p> <ul class="simple"> <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> <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> <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> <li><p><a class="reference external" href="https://github.com/markqvist/RNode_Firmware/">RNode Firmware</a></p></li> </ul> <p>If you have communications hardware that is not already supported by any of the <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, you are welcome to head over to the <a class="reference external" href="https://github.com/markqvist/Reticulum/discussions">GitHub discussion pages</a> and propose adding an interface for the hardware.</p> </section> <section id="develop-a-program-with-reticulum"> <h2>Develop a Program with Reticulum<a class="headerlink" href="#develop-a-program-with-reticulum" title="Permalink to this heading">#</a></h2> <p>If you want to develop programs that use Reticulum, the easiest way to get started is to install the latest release of Reticulum via pip:</p> <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> </pre></div> </div> <p>The above command will install Reticulum and dependencies, and you will be ready to import and use RNS in your own programs. The next step will most 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> <p>For extended functionality, you can install optional dependencies:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">pyserial</span> </pre></div> </div> <p>Further information can be found in the <a class="reference internal" href="reference.html#api-main"><span class="std std-ref">API Reference</span></a>.</p> </section> <section id="participate-in-reticulum-development"> <h2>Participate in Reticulum Development<a class="headerlink" href="#participate-in-reticulum-development" title="Permalink to this heading">#</a></h2> <p>If you want to participate in the development of Reticulum and associated utilities, you’ll want to get the latest source from GitHub. In that case, don’t use pip, but try this recipe:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install dependencies</span> <span class="n">pip</span> <span class="n">install</span> <span class="n">cryptography</span> <span class="n">pyserial</span> <span class="c1"># Clone repository</span> <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> <span class="c1"># Move into Reticulum folder and symlink library to examples folder</span> <span class="n">cd</span> <span class="n">Reticulum</span> <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> <span class="c1"># Run an example</span> <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> <span class="c1"># Unless you've manually created a config file, Reticulum will do so now,</span> <span class="c1"># and immediately exit. Make any necessary changes to the file:</span> <span class="n">nano</span> <span class="o">~/.</span><span class="n">reticulum</span><span class="o">/</span><span class="n">config</span> <span class="c1"># ... and launch the example again.</span> <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> <span class="c1"># You can now repeat the process on another computer,</span> <span class="c1"># and run the same example with -h to get command line options.</span> <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> <span class="c1"># Run the example in client mode to "ping" the server.</span> <span class="c1"># Replace the hash below with the actual destination hash of your server.</span> <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> <span class="c1"># Have a look at another example</span> <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> </pre></div> </div> <p>When you have experimented with the basic examples, it’s time to go read the <a class="reference internal" href="understanding.html#understanding-main"><span class="std std-ref">Understanding Reticulum</span></a> chapter. Before submitting your first pull request, it is probably a good idea to introduce yourself on the <a class="reference external" href="https://github.com/markqvist/Reticulum/discussions">disucssion forum on GitHub</a>, or ask one of the developers or maintainers for a good place to start.</p> </section> <section id="platform-specific-install-notes"> <h2>Platform-Specific Install Notes<a class="headerlink" href="#platform-specific-install-notes" title="Permalink to this heading">#</a></h2> <p>Some platforms require a slightly different installation procedure, or have various quirks that are worth being aware of. These are listed here.</p> <section id="android"> <h3>Android<a class="headerlink" href="#android" title="Permalink to this heading">#</a></h3> <p>Reticulum can be used on Android in different ways. The easiest way to get started is using an app like <a class="reference external" href="https://unsigned.io/sideband">Sideband</a>.</p> <p>For more control and features, you can use Reticulum and related programs via the <a class="reference external" href="https://termux.com/">Termux app</a>, at the time of writing available on <a class="reference external" href="https://f-droid.org">F-droid</a>.</p> <p>Termux is a terminal emulator and Linux environment for Android based devices, which includes the ability to use many different programs and libraries, including Reticulum.</p> <p>To use Reticulum within the Termux environment, you will need to install <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 build into Termux. After that, you can use <code class="docutils literal notranslate"><span class="pre">pip</span></code> to install Reticulum.</p> <p>From within Termux, execute the following:</p> <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> <span class="n">pkg</span> <span class="n">update</span> <span class="n">pkg</span> <span class="n">upgrade</span> <span class="c1"># Then install python and the cryptography library.</span> <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> <span class="c1"># Make sure pip is up to date, and install the wheel module.</span> <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> <span class="c1"># Install Reticulum</span> <span class="n">pip</span> <span class="n">install</span> <span class="n">rns</span> </pre></div> </div> <p>If for some reason the <code class="docutils literal notranslate"><span class="pre">python-cryptography</span></code> package is not available for your platform via the Termux package manager, you can attempt to build it locally on your device using the following command:</p> <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> <span class="n">pkg</span> <span class="n">update</span> <span class="n">pkg</span> <span class="n">upgrade</span> <span class="c1"># Then install dependencies for the cryptography library.</span> <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> <span class="c1"># Make sure pip is up to date, and install the wheel module.</span> <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> <span class="c1"># To allow the installer to build the cryptography module,</span> <span class="c1"># we need to let it know what platform we are compiling for:</span> <span class="n">export</span> <span class="n">CARGO_BUILD_TARGET</span><span class="o">=</span><span class="s2">"aarch64-linux-android"</span> <span class="c1"># Start the install process for the cryptography module.</span> <span class="c1"># Depending on your device, this can take several minutes,</span> <span class="c1"># since the module must be compiled locally on your device.</span> <span class="n">pip</span> <span class="n">install</span> <span class="n">cryptography</span> <span class="c1"># If the above installation succeeds, you can now install</span> <span class="c1"># Reticulum and any related software</span> <span class="n">pip</span> <span class="n">install</span> <span class="n">rns</span> </pre></div> </div> <p>It is also possible to include Reticulum in apps compiled and distributed as Android APKs. A detailed tutorial and example source code will be included 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> </section> <section id="arm64"> <h3>ARM64<a class="headerlink" href="#arm64" title="Permalink to this heading">#</a></h3> <p>On some architectures, including ARM64, not all dependencies have precompiled binaries. On such systems, you may need to install <code class="docutils literal notranslate"><span class="pre">python3-dev</span></code> before installing Reticulum or programs that depend on Reticulum.</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install Python and development packages</span> <span class="n">sudo</span> <span class="n">apt</span> <span class="n">update</span> <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> <span class="c1"># Install Reticulum</span> <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> </pre></div> </div> </section> <section id="raspberry-pi"> <h3>Raspberry Pi<a class="headerlink" href="#raspberry-pi" title="Permalink to this heading">#</a></h3> <p>It is currently recommended to use a 64-bit version of the Raspberry Pi OS if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions don’t always have packages available for some dependencies.</p> <p>While it is possible to install and run Reticulum on 32-bit Rasperry Pi OSes, it will require manually configuring and installing some packages, and is not detailed in this manual.</p> </section> <section id="debian-bookworm"> <h3>Debian Bookworm<a class="headerlink" href="#debian-bookworm" title="Permalink to this heading">#</a></h3> <p>On versions of Debian released after April 2023, it is no longer possible by default to use <code class="docutils literal notranslate"><span class="pre">pip</span></code> to install packages onto your system. Unfortunately, you will need to use the replacement <code class="docutils literal notranslate"><span class="pre">pipx</span></code> command instead, which places installed packages in an isolated environment. This should not negatively affect Reticulum, but will not work for including and using Reticulum in your own scripts and programs.</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install pipx</span> <span class="n">sudo</span> <span class="n">apt</span> <span class="n">install</span> <span class="n">pipx</span> <span class="c1"># Make installed programs available on the command line</span> <span class="n">pipx</span> <span class="n">ensurepath</span> <span class="c1"># Install Reticulum</span> <span class="n">pipx</span> <span class="n">install</span> <span class="n">rns</span> </pre></div> </div> <p>Alternatively, you can restore normal behaviour to <code class="docutils literal notranslate"><span class="pre">pip</span></code> by creating or editing the configuration file located at <code class="docutils literal notranslate"><span class="pre">~/.config/pip/pip.conf</span></code>, and adding the following section:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[global] break-system-packages = true </pre></div> </div> <p>Please note that the “break-system-packages” directive is a somewhat misleading choice of words. Setting it will of course not break any system packages, but will simply 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 cases lead to version conflicts, it does not generally pose any problems.</p> </section> <section id="ubuntu-lunar"> <h3>Ubuntu Lunar<a class="headerlink" href="#ubuntu-lunar" title="Permalink to this heading">#</a></h3> <p>On versions of Ubuntu released after April 2023, it is no longer possible by default to use <code class="docutils literal notranslate"><span class="pre">pip</span></code> to install packages onto your system. Unfortunately, you will need to use the replacement <code class="docutils literal notranslate"><span class="pre">pipx</span></code> command instead, which places installed packages in an isolated environment. This should not negatively affect Reticulum, but will not work for including and using Reticulum in your own scripts and programs.</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install pipx</span> <span class="n">sudo</span> <span class="n">apt</span> <span class="n">install</span> <span class="n">pipx</span> <span class="c1"># Make installed programs available on the command line</span> <span class="n">pipx</span> <span class="n">ensurepath</span> <span class="c1"># Install Reticulum</span> <span class="n">pipx</span> <span class="n">install</span> <span class="n">rns</span> </pre></div> </div> <p>Alternatively, you can restore normal behaviour to <code class="docutils literal notranslate"><span class="pre">pip</span></code> by creating or editing the configuration file located at <code class="docutils literal notranslate"><span class="pre">~/.config/pip/pip.conf</span></code>, and adding the following section:</p> <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[global] break-system-packages = true </pre></div> </div> <p>Please note that the “break-system-packages” directive is a somewhat misleading choice of words. Setting it will of course not break any system packages, but will simply allow installing <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages user- and system-wide. While this _could_ in rare cases lead to version conflicts, it does not generally pose any problems.</p> </section> </section> <section id="pure-python-reticulum"> <h2>Pure-Python Reticulum<a class="headerlink" href="#pure-python-reticulum" title="Permalink to this heading">#</a></h2> <p>In some rare cases, and on more obscure system types, it is not possible to install one or more dependencies. In such situations, 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> 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> package requires no external dependencies for installation. Please note that the 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>. The only difference is that the <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> package lists no dependencies required for installation.</p> <p>No matter how Reticulum is installed and started, it will load external dependencies only if they are <em>needed</em> and <em>available</em>. If for example you want to use Reticulum 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 the <cite>rnspure</cite> package, but Reticulum will not be able to use serial-based interfaces. All other available modules will still be loaded when needed.</p> <p><strong>Please Note!</strong> If you use the <cite>rnspure</cite> package to run Reticulum on systems that do not support <a class="reference external" href="https://github.com/pyca/cryptography">PyCA/cryptography</a>, it is 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> section of this manual.</p> </section> </section> </article> </div> <footer> <div class="related-pages"> <a class="next-page" href="using.html"> <div class="page-info"> <div class="context"> <span>Next</span> </div> <div class="title">Using Reticulum on Your System</div> </div> <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> </a> <a class="prev-page" href="whatis.html"> <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> <div class="page-info"> <div class="context"> <span>Previous</span> </div> <div class="title">What is Reticulum?</div> </div> </a> </div> <div class="bottom-of-page"> <div class="left-details"> <div class="copyright"> Copyright © 2023, Mark Qvist </div> Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and <a href="https://github.com/pradyunsg/furo">Furo</a> </div> <div class="right-details"> <div class="icons"> </div> </div> </div> </footer> </div> <aside class="toc-drawer"> <div class="toc-sticky toc-scroll"> <div class="toc-title-container"> <span class="toc-title"> On this page </span> </div> <div class="toc-tree-container"> <div class="toc-tree"> <ul> <li><a class="reference internal" href="#">Getting Started Fast</a><ul> <li><a class="reference internal" href="#standalone-reticulum-installation">Standalone Reticulum Installation</a></li> <li><a class="reference internal" href="#resolving-dependency-installation-issues">Resolving Dependency & Installation Issues</a></li> <li><a class="reference internal" href="#try-using-a-reticulum-based-program">Try Using a Reticulum-based Program</a><ul> <li><a class="reference internal" href="#remote-shell">Remote Shell</a></li> <li><a class="reference internal" href="#nomad-network">Nomad Network</a></li> <li><a class="reference internal" href="#sideband">Sideband</a></li> <li><a class="reference internal" href="#meshchat">MeshChat</a></li> </ul> </li> <li><a class="reference internal" href="#using-the-included-utilities">Using the Included Utilities</a></li> <li><a class="reference internal" href="#creating-a-network-with-reticulum">Creating a Network With Reticulum</a></li> <li><a class="reference internal" href="#connecting-reticulum-instances-over-the-internet">Connecting Reticulum Instances Over the Internet</a></li> <li><a class="reference internal" href="#connect-to-the-public-testnet">Connect to the Public Testnet</a></li> <li><a class="reference internal" href="#adding-radio-interfaces">Adding Radio Interfaces</a></li> <li><a class="reference internal" href="#develop-a-program-with-reticulum">Develop a Program with Reticulum</a></li> <li><a class="reference internal" href="#participate-in-reticulum-development">Participate in Reticulum Development</a></li> <li><a class="reference internal" href="#platform-specific-install-notes">Platform-Specific Install Notes</a><ul> <li><a class="reference internal" href="#android">Android</a></li> <li><a class="reference internal" href="#arm64">ARM64</a></li> <li><a class="reference internal" href="#raspberry-pi">Raspberry Pi</a></li> <li><a class="reference internal" href="#debian-bookworm">Debian Bookworm</a></li> <li><a class="reference internal" href="#ubuntu-lunar">Ubuntu Lunar</a></li> </ul> </li> <li><a class="reference internal" href="#pure-python-reticulum">Pure-Python Reticulum</a></li> </ul> </li> </ul> </div> </div> </div> </aside> </div> </div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> <script src="_static/jquery.js"></script> <script src="_static/underscore.js"></script> <script src="_static/_sphinx_javascript_frameworks_compat.js"></script> <script src="_static/doctools.js"></script> <script src="_static/sphinx_highlight.js"></script> <script src="_static/scripts/furo.js"></script> <script src="_static/clipboard.min.js"></script> <script src="_static/copybutton.js"></script> </body> </html>