<linkrel="index"title="Index"href="genindex.html"/><linkrel="search"title="Search"href="search.html"/><linkrel="next"title="Using Reticulum on Your System"href="using.html"/><linkrel="prev"title="What is Reticulum?"href="whatis.html"/>
of your system with a command like <codeclass="docutils literal notranslate"><spanclass="pre">sudo</span><spanclass="pre">apt</span><spanclass="pre">install</span><spanclass="pre">python3-pip</span></code>,
<codeclass="docutils literal notranslate"><spanclass="pre">sudo</span><spanclass="pre">pamac</span><spanclass="pre">install</span><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code>:</p>
<h3>Resolving Dependency & Installation Issues<aclass="headerlink"href="#resolving-dependency-installation-issues"title="Permalink to this heading">#</a></h3>
<codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> installation may fail with an error message. In these cases, the issue can usually
<p>With the base development packages installed, <codeclass="docutils literal notranslate"><spanclass="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-
remote system, and is similar to how <codeclass="docutils literal notranslate"><spanclass="pre">ssh</span></code> works. The <codeclass="docutils literal notranslate"><spanclass="pre">rnsh</span></code> is very efficient, and
program, reboot your system and try again. In some cases, you may even need to
manually add the <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> install path to your <codeclass="docutils literal notranslate"><spanclass="pre">PATH</span></code> environment variable.</p>
<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 <codeclass="docutils literal notranslate"><spanclass="pre">rnsd</span></code> to run Reticulum as a background or foreground service,
and the <codeclass="docutils literal notranslate"><spanclass="pre">rnstatus</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">rnpath</span></code> and <codeclass="docutils literal notranslate"><spanclass="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
<aclass="reference internal"href="using.html#using-main"><spanclass="std std-ref">Using Reticulum on Your System</span></a> chapter of this manual.</p>
default is located at <codeclass="docutils literal notranslate"><spanclass="pre">~/.reticulum/config</span></code>. You can get an example
configuration file with all options via <codeclass="docutils literal notranslate"><spanclass="pre">rnsd</span><spanclass="pre">--exampleconfig</span></code>.</p>
network just using the default (<aclass="reference internal"href="interfaces.html#interfaces-auto"><spanclass="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 <aclass="reference internal"href="networks.html#networks-main"><spanclass="std std-ref">Building Networks</span></a>
and <aclass="reference internal"href="interfaces.html#interfaces-main"><spanclass="std std-ref">Interfaces</span></a> chapters of this manual.</p>
<h2>Connecting Reticulum Instances Over the Internet<aclass="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: <aclass="reference internal"href="interfaces.html#interfaces-tcps"><spanclass="std std-ref">TCP</span></a>
and <aclass="reference internal"href="interfaces.html#interfaces-i2p"><spanclass="std std-ref">I2P</span></a>. Each interface offers a different set of features, and Reticulum
<p>The <codeclass="docutils literal notranslate"><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">I2PInterface</span></code>,
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">I2PInterface</span></code> routes messages through the <aclass="reference external"href="https://geti2p.net/en/">Invisible Internet Protocol
parallel to <codeclass="docutils literal notranslate"><spanclass="pre">rnsd</span></code>. For always-on I2P nodes it is recommended to use <aclass="reference external"href="https://i2pd.website/">i2pd</a>.</p>
<p>By default, I2P will encrypt and mix all traffic sent over the Internet, and
<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
<aclass="reference internal"href="interfaces.html#interfaces-main"><spanclass="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 <aclass="reference internal"href="hardware.html#rnode-main"><spanclass="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 <aclass="reference internal"href="hardware.html#hardware-main"><spanclass="std std-ref">Communications Hardware</span></a>
chapter for a guide. If you prefer purchasing a ready-made unit, you can refer to the
<li><p><aclass="reference external"href="https://unsigned.io/private-messaging-over-lora/">Private, Secure and Uncensorable Messaging Over a LoRa Mesh</a></p></li>
<p>If you have communications hardware that is not already supported by any of the
<aclass="reference internal"href="interfaces.html#interfaces-main"><spanclass="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 <aclass="reference external"href="https://github.com/markqvist/Reticulum/discussions">GitHub discussion pages</a>
and propose adding an interface for the hardware.</p>
<p>The entire Reticulum API is documented in the <aclass="reference internal"href="reference.html#api-main"><spanclass="std std-ref">API Reference</span></a>
<spanid="install-guides"></span><h2>Platform-Specific Install Notes<aclass="headerlink"href="#platform-specific-install-notes"title="Permalink to this heading">#</a></h2>
<p>To use Reticulum within the Termux environment, you will need to install
<codeclass="docutils literal notranslate"><spanclass="pre">python</span></code> and the <codeclass="docutils literal notranslate"><spanclass="pre">python-cryptography</span></code> library using <codeclass="docutils literal notranslate"><spanclass="pre">pkg</span></code>, the package-manager
build into Termux. After that, you can use <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> to install Reticulum.</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># First, make sure indexes and packages are up to date.</span>
<p>If for some reason the <codeclass="docutils literal notranslate"><spanclass="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>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># First, make sure indexes and packages are up to date.</span>
here at a later point. Until then you can use the <aclass="reference external"href="https://github.com/markqvist/sideband">Sideband source code</a> as an example and starting point.</p>
binaries. On such systems, you may need to install <codeclass="docutils literal notranslate"><spanclass="pre">python3-dev</span></code> (or similar) before
<p>With these packages installed, <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> will be able to build any missing dependencies
to use <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> to install packages onto your system. Unfortunately, you will need to
use the replacement <codeclass="docutils literal notranslate"><spanclass="pre">pipx</span></code> command instead, which places installed packages in an
<p>Alternatively, you can restore normal behaviour to <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> by creating or editing
the configuration file located at <codeclass="docutils literal notranslate"><spanclass="pre">~/.config/pip/pip.conf</span></code>, and adding the
<p>For a one-shot installation of Reticulum, without globally enabling the <codeclass="docutils literal notranslate"><spanclass="pre">break-system-packages</span></code>
of words. Setting it will of course not break any system packages, but will simply
allow installing <codeclass="docutils literal notranslate"><spanclass="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, especially
not in the case of installing Reticulum.</p>
</div>
</section>
<sectionid="macos">
<h3>MacOS<aclass="headerlink"href="#macos"title="Permalink to this heading">#</a></h3>
<p>To install Reticulum on macOS, you will need to have Python and the <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> package
manager installed.</p>
<p>Systems running macOS can vary quite widely in whether or not Python is pre-installed,
and if it is, which version is installed, and whether the <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> package manager is
also installed and set up. If in doubt, you can <aclass="reference external"href="https://www.python.org/downloads/">download and install</a>
Python manually.</p>
<p>When Python and <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> is available on your system, simply open a terminal window
and use one of the following commands:</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># Install Reticulum and utilities with pip:</span>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">--break-system-packages</span></code> directive is a somewhat misleading choice
of words. Setting it will of course not break any system packages, but will simply
allow installing <codeclass="docutils literal notranslate"><spanclass="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, especially
not in the case of installing Reticulum.</p>
</div>
<p>Additionally, some version combinations of macOS and Python require you to
manually add your installed <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> packages directory to your <cite>PATH</cite> environment
variable, before you can use installed commands in your terminal. Usually, adding
the following line to your shell init script (for example <codeclass="docutils literal notranslate"><spanclass="pre">~/.zshrc</span></code>) will be enough:</p>
<p>At the time of releasing this manual, work is underway to create pre-built
Reticulum packages for OpenWRT, with full configuration, service
and <codeclass="docutils literal notranslate"><spanclass="pre">uci</span></code> integration. Please see the <aclass="reference external"href="https://github.com/gretel/feed-reticulum">feed-reticulum</a>
and <aclass="reference external"href="https://github.com/gretel/reticulum-openwrt">reticulum-openwrt</a>
repositories for more information.</p>
</div>
<p>To install Reticulum on OpenWRT, first log into a command line session, and
for Reticulum connectivity to and from your device to work. Until proper
packaging is ready, you will also need to manually create a service or startup
script to automatically laucnh Reticulum at boot time.</p>
<p>Please also note that the <cite>AutoInterface</cite> requires link-local IPv6 addresses
to be enabled for any Ethernet and WiFi devices you intend to use. If <codeclass="docutils literal notranslate"><spanclass="pre">ip</span><spanclass="pre">a</span></code>
shows an address starting with <codeclass="docutils literal notranslate"><spanclass="pre">fe80::</span></code> for the device in question,
<codeclass="docutils literal notranslate"><spanclass="pre">AutoInterface</span></code> should work for that device.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">--break-system-packages</span></code> directive is a somewhat misleading choice
of words. Setting it will of course not break any system packages, but will simply
allow installing <codeclass="docutils literal notranslate"><spanclass="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, especially
<h3>RISC-V<aclass="headerlink"href="#risc-v"title="Permalink to this heading">#</a></h3>
<p>On some architectures, including RISC-V, not all dependencies have precompiled
binaries. On such systems, you may need to install <codeclass="docutils literal notranslate"><spanclass="pre">python3-dev</span></code> (or similar) before
installing Reticulum or programs that depend on Reticulum.</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># Install Python and development packages</span>
<p>With these packages installed, <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> will be able to build any missing dependencies
to use <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> to install packages onto your system. Unfortunately, you will need to
use the replacement <codeclass="docutils literal notranslate"><spanclass="pre">pipx</span></code> command instead, which places installed packages in an
<p>Alternatively, you can restore normal behaviour to <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> by creating or editing
the configuration file located at <codeclass="docutils literal notranslate"><spanclass="pre">~/.config/pip/pip.conf</span></code>, and adding the
<p>For a one-shot installation of Reticulum, without globally enabling the <codeclass="docutils literal notranslate"><spanclass="pre">break-system-packages</span></code>
allow installing <codeclass="docutils literal notranslate"><spanclass="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, especially
<h3>Windows<aclass="headerlink"href="#windows"title="Permalink to this heading">#</a></h3>
<p>On Windows operating systems, the easiest way to install Reticulum is by using the
<codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> package manager from the command line (either the command prompt or Windows
Powershell).</p>
<p>If you don’t already have Python installed, <aclass="reference external"href="https://www.python.org/downloads/">download and install Python</a>.
At the time of publication of this manual, the recommended version is <aclass="reference external"href="https://www.python.org/downloads/release/python-3127">Python 3.12.7</a>.</p>
<p><strong>Important!</strong> When asked by the installer, make sure to add the Python program to
your PATH environment variables. If you don’t do this, you will not be able to
use the <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code> installer, or run the included Reticulum utility programs (such as
<codeclass="docutils literal notranslate"><spanclass="pre">rnsd</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">rnstatus</span></code>) from the command line.</p>
<p>After installing Python, open the command prompt or Windows Powershell, and type:</p>
<p>If you use the <codeclass="docutils literal notranslate"><spanclass="pre">rnspure</span></code> package to run Reticulum on systems that
do not support <aclass="reference external"href="https://github.com/pyca/cryptography">PyCA/cryptography</a>, it is
important that you read and understand the <aclass="reference internal"href="understanding.html#understanding-primitives"><spanclass="std std-ref">Cryptographic Primitives</span></a>
you can use the <codeclass="docutils literal notranslate"><spanclass="pre">rnspure</span></code> package instead of the <codeclass="docutils literal notranslate"><spanclass="pre">rns</span></code> package, or use <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code>
with the <codeclass="docutils literal notranslate"><spanclass="pre">--no-dependencies</span></code> command-line option. The <codeclass="docutils literal notranslate"><spanclass="pre">rnspure</span></code>
package requires no external dependencies for installation. Please note that the
actual contents of the <codeclass="docutils literal notranslate"><spanclass="pre">rns</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">rnspure</span></code> packages are <em>completely identical</em>.
The only difference is that the <codeclass="docutils literal notranslate"><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="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>
