<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"/>
<p>If you do not already have pip installed, you can install it using the package manager
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>
<h2>Resolving Dependency & Installation Issues<aclass="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
<codeclass="docutils literal notranslate"><spanclass="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>
<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-
compiled packages available.</p>
</section>
<sectionid="try-using-a-reticulum-based-program">
<h2>Try Using a Reticulum-based Program<aclass="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>
<sectionid="remote-shell">
<h3>Remote Shell<aclass="headerlink"href="#remote-shell"title="Permalink to this heading">#</a></h3>
<p>The <aclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">ssh</span></code> works. The <codeclass="docutils literal notranslate"><spanclass="pre">rnsh</span></code> is very efficient, and
can facilitate fully interactive shell sessions, even over extremely low-bandwidth links.</p>
<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>
<sectionid="using-the-included-utilities">
<h2>Using the Included Utilities<aclass="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 <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>
</section>
<sectionid="creating-a-network-with-reticulum">
<h2>Creating a Network With Reticulum<aclass="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 <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>
<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 (<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
users should carefully choose the interface which best suites their needs.</p>
<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>,
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 <codeclass="docutils literal notranslate"><spanclass="pre">I2PInterface</span></code> routes messages through the <aclass="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 <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
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>
<sectionid="connect-to-the-public-testnet">
<h2>Connect to the Public Testnet<aclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">.reticulum/config</span></code> file:</p>
<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.</p>
</section>
<sectionid="adding-radio-interfaces">
<h2>Adding Radio Interfaces<aclass="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
<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/how-to-make-your-own-rnodes/">How To Make Your Own RNodes</a></p></li>
<li><p><aclass="reference external"href="https://unsigned.io/installing-rnode-firmware-on-supported-devices/">Installing RNode Firmware on Compatible LoRa Devices</a></p></li>
<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>
</section>
<sectionid="develop-a-program-with-reticulum">
<h2>Develop a Program with Reticulum<aclass="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>
<p>Further information can be found in the <aclass="reference internal"href="reference.html#api-main"><spanclass="std std-ref">API Reference</span></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
<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>
<p>From within Termux, execute the following:</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>
<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 <aclass="reference external"href="https://github.com/markqvist/sideband">Sideband source code</a> as an example and startig point.</p>
</section>
<sectionid="arm64">
<h3>ARM64<aclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">python3-dev</span></code> 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>
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>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 <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.</p>
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>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 <codeclass="docutils literal notranslate"><spanclass="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>
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>
<p><strong>Please Note!</strong> If you use the <cite>rnspure</cite> 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>
section of this manual.</p>
</section>
</section>
</article>
</div>
<footer>
<divclass="related-pages">
<aclass="next-page"href="using.html">
<divclass="page-info">
<divclass="context">
<span>Next</span>
</div>
<divclass="title">Using Reticulum on Your System</div>
