jacob.eva/Reticulum
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updated documentation

Browse Source
This commit is contained in:
Mark Qvist 2022-04-07 18:59:42 +02:00
parent d4aeb85191
commit 3684fe502f
22 changed files with 274 additions and 152 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/manual/.buildinfo
View File

@ -1,4 +1,4 @@
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
config: 8cd01657672a2b3a4d1c8ecc92b32a11
config: 8680566a0b6de7e728db125ddf2d6a25
tags: 645f666f9bcd5a90fca523b33c5a78b7

BIN
docs/manual/_images/sideband_1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 79 KiB

65
docs/manual/_sources/gettingstartedfast.rst.txt
View File

@ -35,6 +35,15 @@ 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.
If you would rather use a program with a graphical user interface, you can take
a look at `Sideband <https://unsigned.io/sideband>`_, which is available for Android,
Linux and macOS.
.. image:: screenshots/sideband_1.png
:width: 400px
:align: center
:target: _images/sideband_1.png
Using the Included Utilities
=============================================
@ -59,27 +68,34 @@ or use the interactive ``rnsconfig`` utility.
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 network (if there is one), and only allows you to
communicate with other Reticulum peers within your local broadcast domain.
your existing ethernet and WiFi networks (if any), and only allows you to
communicate with other Reticulum peers within your local broadcast domains.
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.
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.
Once Reticulums knows which interfaces it should use, it will automatically
discover topography and configure transport of data to any destinations it
knows about.
Possibly, the examples in the config file are enough to get you started. If
you want more information, you can read the :ref:`Building Networks<networks-main>`
and :ref:`Interfaces<interfaces-main>` chapters of this manual.
Bridging Over the Internet
=============================================
Reticulum currently offers two interfaces for connecting nodes over the internet:
`TCP <https://markqvist.github.io/Reticulum/manual/interfaces.html#tcp-server-interface>`_ and `I2P <https://markqvist.github.io/Reticulum/manual/interfaces.html#i2p-interface>`_. Each interface offers a different set of features, and Reticulum
Connecting Reticulum Instances Over the Internet
================================================
Reticulum currently offers two interfaces for connecting instances over the Internet: :ref:`TCP<interfaces-tcps>`
and :ref:`I2P<interfaces-i2p>`. Each interface offers a different set of features, and Reticulum
users should carefully choose the interface which best suites their needs.
The ``TCPServerInterface`` allows users to host a node accessible over TCP/IP. This
The ``TCPServerInterface`` allows users to host an instance accessible over TCP/IP. This
method is generally faster, lower latency, and more energy efficient than using ``I2PInterface``,
however it leaks considerable metadata about the server host.
however it also leaks considerable metadata about the server host.
Direct TCP client connections are able to see your node's IP address and may be able
to use this information to determine your location or identity. Adversaries
@ -101,16 +117,16 @@ bandwidth and compute power, but also makes timing attacks and other forms of
deep-packet-inspection much more difficult. Similar to RNS, I2P uses cryptographic
public keys as destination addresses, which allows users to host nodes on non-static IPs.
In general it is recommended to use an I2P node if you are hosting your node
publicly.
In general it is recommended to use an I2P node if you want to host a publically accessible
instance, while preserving anonymity. If you care more about performance, and a slightly
easier setup, use TCP.
There is a experimental public testnet you can join by adding the following
There is a experimental public testnet you can join by adding one of the following
interfaces to your ``.reticulum/config`` file:
.. code::
# For connecting over TCP/IP:
[[RNS Testnet Frankfurt]]
type = TCPClientInterface
interface_enabled = yes
@ -120,7 +136,6 @@ interfaces to your ``.reticulum/config`` file:
# For connecting over I2P:
[[RNS Testnet I2P Node A]]
type = I2PInterface
interface_enabled = yes
@ -212,8 +227,11 @@ installing Reticulum or programs that depend on Reticulum.
Reticulum on Android
==============================================
Reticulum can be used on Android in different ways. The easiest way to get
started is using the `Termux app <https://termux.com/>`_, at the time of writing
available on `F-droid <https://f-droid.org>`_.
started is using an app like `Sideband <https://unsigned.io/sideband>`_.
For more control and features, you can use Reticulum and related programs via
the `Termux app <https://termux.com/>`_, at the time of writing available on
`F-droid <https://f-droid.org>`_.
Termux is a terminal emulator and Linux environment for Android based devices,
which includes the ability to use many different programs and libraries,
@ -253,3 +271,18 @@ From within Termux, execute the following:
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.
Adding Radio Interfaces
==============================================
Once you have Reticulum installed and working, you can add radio interfaces with
any compatible hardware you have available. For information on how to configure
this, see the :ref:`Interfaces<interfaces-main>` section of this manual.
A range of common LoRa development boards and transceiver modules can be used
as interfaces with Reticulum. You can refer to the following external resources
for more information:
* `How To Make Your Own RNodes <https://unsigned.io/how-to-make-your-own-rnodes/>`_
* `Installing RNode Firmware on Compatible LoRa Devices <https://unsigned.io/installing-rnode-firmware-on-t-beam-and-lora32-devices/>`_
* `Private, Secure and Uncensorable Messaging Over a LoRa Mesh <https://unsigned.io/private-messaging-over-lora/>`_
* `RNode Firmware <https://github.com/markqvist/RNode_Firmware/>`_

57
docs/manual/_sources/understanding.rst.txt
View File

@ -300,16 +300,36 @@ networks are fundamentally incompatible with the physical link types that Reticu
These routing methodologies assume trust at the physical layer, and often needs a lot more bandwidth than
Reticulum can assume is available.
Since Reticulum is designed to run over open radio spectrum, no such trust exists, and bandwidth is often
very limited. Existing routing protocols like BGP or OSPF carry too much overhead to be practically
Since Reticulum is designed to survive running over open radio spectrum, no such trust exists, and bandwidth
is often very limited. Existing routing protocols like BGP or OSPF carry too much overhead to be practically
useable over bandwidth-limited, high-latency links.
To overcome such challenges, Reticulum’s *Transport* system uses public-key cryptography to
implement the concept of *paths* that allow discovery of how to get information to a certain
implement the concept of *paths* that allow discovery of how to get information closer to a certain
destination. It is important to note that no single node in a Reticulum network knows the complete
path to a destination. Every Transport node participating in a Reticulum network will only
know what the most direct way to get a packet one hop closer to it's destination is.
.. _understanding-nodetypes:
Node Types
----------
Currently, Reticulum distinguishes between two types of network nodes. All nodes on a Reticulum network
are *Reticulum Instances*, and some are alo *Transport Nodes*. If a system running Reticulum is fixed in
one place, and is intended to be kept available most of the time, it can be a *Transport Node*, by enabling
it in the configuration.
This distinction is made by the user configuring the node, and is used to determine what nodes on the
network will help forward traffic, and what nodes rely on other nodes for wider connectivity.
If a node is a *Instance* it should be given the configuration directive ``enable_transport = No``, which
is the default setting.
If it is a *Transport Node*, it should be given the configuration directive ``enable_transport = Yes``.
.. _understanding-announce:
The Announce Mechanism in Detail
@ -325,14 +345,14 @@ according to some specific rules:
total it has been retransmitted to get here.
* | If the announce has been retransmitted *m+1* times, it will not be forwarded. By default, *m* is
set to 18.
set to 128.
* | The announce will be assigned a delay *d* = c\ :sup:`h` seconds, where *c* is a decay constant, and *h* is the amount of times this packet has already been forwarded.
* | The packet will be given a priority *p = 1/d*.
* | If at least *d* seconds has passed since the announce was received, and no other packets with a
priority higher than *p* are waiting in the queue (see Packet Prioritisation), and the channel is
priority higher than *p* are waiting in the queue, and the channel is
not utilized by other traffic, the announce will be forwarded.
* | If no other nodes are heard retransmitting the announce with a greater hop count than when
@ -354,10 +374,15 @@ packet towards the destination by looking up the next node with the shortest amo
destination.
According to these rules and default constants, an announce will propagate throughout the network
in a predictable way. In an example network utilising the default constants, and with an average link
distance of *Lavg =* 15 kilometers, an announce will be able to propagate outwards to a radius of 180
kilometers in 34 minutes, and a *maximum announce radius* of 270 kilometers in approximately 3
days.
in a predictable way.
As an example, in a network based only on radio transceivers with an average link distance of 15
kilometers, an announce will be able to propagate outwards over 12 hops, to a radius of 180
kilometers, in approximately 20 minutes.
The design and constants of the decay and delay functionality in the announce propagation is subject
to change and optimisation as real-world usage is explored. The announce propagation speed can be
increased at the cost of increased bandwidth consumption.
.. _understanding-paths:
@ -579,20 +604,6 @@ Reticulum, but non critical in understanding how the protocol works on a general
treated more as a reference than as essential reading.
Node Types
----------
Currently Reticulum defines two node types, the *Station* and the *Peer*. A node is a *station* if it fixed
in one place, and if it is intended to be kept online most of the time. Otherwise the node is a *peer*.
This distinction is made by the user configuring the node, and is used to determine what nodes on the
network will help forward traffic, and what nodes rely on other nodes for connectivity.
If a node is a *Peer* it should be given the configuration directive ``enable_transport = No``.
If it is a *Station*, it should be given the configuration directive ``enable_transport = Yes``.
Packet Prioritisation
---------------------

2
docs/manual/_static/documentation_options.js
View File

@ -1,6 +1,6 @@
var DOCUMENTATION_OPTIONS = {
URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
VERSION: '0.3.3 beta',
VERSION: '0.3.4 beta',
LANGUAGE: 'None',
COLLAPSE_INDEX: false,
BUILDER: 'html',

6
docs/manual/examples.html
View File

@ -5,7 +5,7 @@
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Code Examples &#8212; Reticulum Network Stack 0.3.3 beta documentation</title>
<title>Code Examples &#8212; Reticulum Network Stack 0.3.4 beta documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" />
@ -27,7 +27,7 @@
<li class="right" >
<a href="reference.html" title="API Reference"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.3 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.4 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Code Examples</a></li>
</ul>
</div>
@ -2366,7 +2366,7 @@ interface to efficiently pass files of any size over a Reticulum <a class="refer
<li class="right" >
<a href="reference.html" title="API Reference"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.3 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.4 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Code Examples</a></li>
</ul>
</div>

6
docs/manual/genindex.html
View File

@ -5,7 +5,7 @@
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Index &#8212; Reticulum Network Stack 0.3.3 beta documentation</title>
<title>Index &#8212; Reticulum Network Stack 0.3.4 beta documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" />
@ -23,7 +23,7 @@
<li class="right" style="margin-right: 10px">
<a href="#" title="General Index"
accesskey="I">index</a></li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.3 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.4 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Index</a></li>
</ul>
</div>
@ -416,7 +416,7 @@
<li class="right" style="margin-right: 10px">
<a href="#" title="General Index"
>index</a></li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.3 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.4 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Index</a></li>
</ul>
</div>

65
docs/manual/gettingstartedfast.html
View File

@ -5,7 +5,7 @@
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Getting Started Fast &#8212; Reticulum Network Stack 0.3.3 beta documentation</title>
<title>Getting Started Fast &#8212; Reticulum Network Stack 0.3.4 beta documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" />
@ -31,7 +31,7 @@
<li class="right" >
<a href="whatis.html" title="What is Reticulum?"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.3 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.4 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Getting Started Fast</a></li>
</ul>
</div>
@ -67,6 +67,10 @@ for the messaging and information-sharing protocol
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>
<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 and macOS.</p>
<a class="reference external image-reference" href="_images/sideband_1.png"><img alt="_images/sideband_1.png" class="align-center" src="_images/sideband_1.png" style="width: 400px;" /></a>
</div>
<div class="section" id="using-the-included-utilities">
<h2>Using the Included Utilities<a class="headerlink" href="#using-the-included-utilities" title="Permalink to this headline"></a></h2>
@ -87,23 +91,29 @@ default is located at <code class="docutils literal notranslate"><span class="pr
or use the interactive <code class="docutils literal notranslate"><span class="pre">rnsconfig</span></code> utility.</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 network (if there is one), and only allows you to
communicate with other Reticulum peers within your local broadcast domain.</p>
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 Reticulums knows which interfaces it should use, it will automatically
discover topography and configure transport of data to any destinations it
knows about.</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>
</div>
<div class="section" id="bridging-over-the-internet">
<h2>Bridging Over the Internet<a class="headerlink" href="#bridging-over-the-internet" title="Permalink to this headline"></a></h2>
<p>Reticulum currently offers two interfaces for connecting nodes over the internet:
<a class="reference external" href="https://markqvist.github.io/Reticulum/manual/interfaces.html#tcp-server-interface">TCP</a> and <a class="reference external" href="https://markqvist.github.io/Reticulum/manual/interfaces.html#i2p-interface">I2P</a>. Each interface offers a different set of features, and Reticulum
<div class="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 headline"></a></h2>
<p>Reticulum currently offers two interfaces 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 a node accessible over TCP/IP. This
<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 leaks considerable metadata about the server host.</p>
however it also leaks considerable metadata about the server host.</p>
<p>Direct TCP client connections are able to see your node’s IP address and may be able
to use this information to determine your location or identity. Adversaries
inspecting your network’s internet packets may be able to record packet metadata
@ -121,12 +131,12 @@ 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. Similar to RNS, I2P uses cryptographic
public keys as destination addresses, which allows users to host nodes on non-static IPs.</p>
<p>In general it is recommended to use an I2P node if you are hosting your node
publicly.</p>
<p>There is a experimental public testnet you can join by adding the following
<p>In general it is recommended to use an I2P node if you want to host a publically accessible
instance, while preserving anonymity. If you care more about performance, and a slightly
easier setup, use TCP.</p>
<p>There is a experimental public testnet you can join 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"># For connecting over TCP/IP:</span>
<span class="p">[[</span><span class="n">RNS</span> <span class="n">Testnet</span> <span class="n">Frankfurt</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="n">yes</span>
@ -136,7 +146,6 @@ interfaces to your <code class="docutils literal notranslate"><span class="pre">
<span class="c1"># For connecting over I2P:</span>
<span class="p">[[</span><span class="n">RNS</span> <span class="n">Testnet</span> <span class="n">I2P</span> <span class="n">Node</span> <span class="n">A</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">I2PInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="n">yes</span>
@ -217,8 +226,10 @@ installing Reticulum or programs that depend on Reticulum.</p>
<div class="section" id="reticulum-on-android">
<h2>Reticulum on Android<a class="headerlink" href="#reticulum-on-android" title="Permalink to this headline"></a></h2>
<p>Reticulum can be used on Android in different ways. The easiest way to get
started is using 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>
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>
@ -254,6 +265,21 @@ and a few extra commands are required.</p>
Android APKs. A detailed tutorial and example source code will be included
here at a later point.</p>
</div>
<div class="section" id="adding-radio-interfaces">
<h2>Adding Radio Interfaces<a class="headerlink" href="#adding-radio-interfaces" title="Permalink to this headline"></a></h2>
<p>Once you have Reticulum installed and working, you can add radio interfaces with
any compatible hardware you have available. 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>A range of common LoRa development boards and transceiver modules can be used
as interfaces with Reticulum. You can refer to the following external resources
for more information:</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-t-beam-and-lora32-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>
</div>
</div>
@ -269,11 +295,12 @@ here at a later point.</p>
<li><a class="reference internal" href="#try-using-a-reticulum-based-program">Try Using a Reticulum-based Program</a></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="#bridging-over-the-internet">Bridging Over the Internet</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="#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="#reticulum-on-arm64">Reticulum on ARM64</a></li>
<li><a class="reference internal" href="#reticulum-on-android">Reticulum on Android</a></li>
<li><a class="reference internal" href="#adding-radio-interfaces">Adding Radio Interfaces</a></li>
</ul>
</li>
</ul>
@ -317,7 +344,7 @@ here at a later point.</p>
<li class="right" >
<a href="whatis.html" title="What is Reticulum?"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.3 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.4 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Getting Started Fast</a></li>
</ul>
</div>

11
docs/manual/index.html
View File

@ -5,7 +5,7 @@
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Reticulum Network Stack Manual &#8212; Reticulum Network Stack 0.3.3 beta documentation</title>
<title>Reticulum Network Stack Manual &#8212; Reticulum Network Stack 0.3.4 beta documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" />
@ -27,7 +27,7 @@
<li class="right" >
<a href="whatis.html" title="What is Reticulum?"
accesskey="N">next</a> |</li>
<li class="nav-item nav-item-0"><a href="#">Reticulum Network Stack 0.3.3 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="#">Reticulum Network Stack 0.3.4 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Reticulum Network Stack Manual</a></li>
</ul>
</div>
@ -56,11 +56,12 @@ to participate in the development of Reticulum itself.</p>
<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#try-using-a-reticulum-based-program">Try Using a Reticulum-based Program</a></li>
<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#using-the-included-utilities">Using the Included Utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#creating-a-network-with-reticulum">Creating a Network With Reticulum</a></li>
<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#bridging-over-the-internet">Bridging Over the Internet</a></li>
<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#connecting-reticulum-instances-over-the-internet">Connecting Reticulum Instances Over the Internet</a></li>
<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#develop-a-program-with-reticulum">Develop a Program with Reticulum</a></li>
<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#participate-in-reticulum-development">Participate in Reticulum Development</a></li>
<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#reticulum-on-arm64">Reticulum on ARM64</a></li>
<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#reticulum-on-android">Reticulum on Android</a></li>
<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#adding-radio-interfaces">Adding Radio Interfaces</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a><ul>
@ -112,6 +113,7 @@ to participate in the development of Reticulum itself.</p>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="understanding.html#reticulum-transport">Reticulum Transport</a><ul>
<li class="toctree-l3"><a class="reference internal" href="understanding.html#node-types">Node Types</a></li>
<li class="toctree-l3"><a class="reference internal" href="understanding.html#the-announce-mechanism-in-detail">The Announce Mechanism in Detail</a></li>
<li class="toctree-l3"><a class="reference internal" href="understanding.html#reaching-the-destination">Reaching the Destination</a></li>
<li class="toctree-l3"><a class="reference internal" href="understanding.html#resources">Resources</a></li>
@ -119,7 +121,6 @@ to participate in the development of Reticulum itself.</p>
</li>
<li class="toctree-l2"><a class="reference internal" href="understanding.html#reference-system-setup">Reference System Setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="understanding.html#protocol-specifics">Protocol Specifics</a><ul>
<li class="toctree-l3"><a class="reference internal" href="understanding.html#node-types">Node Types</a></li>
<li class="toctree-l3"><a class="reference internal" href="understanding.html#packet-prioritisation">Packet Prioritisation</a></li>
<li class="toctree-l3"><a class="reference internal" href="understanding.html#binary-packet-format">Binary Packet Format</a></li>
</ul>
@ -211,7 +212,7 @@ to participate in the development of Reticulum itself.</p>
<li class="right" >
<a href="whatis.html" title="What is Reticulum?"
>next</a> |</li>
<li class="nav-item nav-item-0"><a href="#">Reticulum Network Stack 0.3.3 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="#">Reticulum Network Stack 0.3.4 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Reticulum Network Stack Manual</a></li>
</ul>
</div>

6
docs/manual/interfaces.html
View File

@ -5,7 +5,7 @@
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Supported Interfaces &#8212; Reticulum Network Stack 0.3.3 beta documentation</title>
<title>Supported Interfaces &#8212; Reticulum Network Stack 0.3.4 beta documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" />
@ -31,7 +31,7 @@
<li class="right" >
<a href="networks.html" title="Building Networks"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.3 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.4 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Supported Interfaces</a></li>
</ul>
</div>
@ -580,7 +580,7 @@ disappear again.</p></li>
<li class="right" >
<a href="networks.html" title="Building Networks"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.3 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.4 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Supported Interfaces</a></li>
</ul>
</div>

6
docs/manual/networks.html
View File

@ -5,7 +5,7 @@
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Building Networks &#8212; Reticulum Network Stack 0.3.3 beta documentation</title>
<title>Building Networks &#8212; Reticulum Network Stack 0.3.4 beta documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" />
@ -31,7 +31,7 @@
<li class="right" >
<a href="using.html" title="Using Reticulum on Your System"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.3 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.4 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Building Networks</a></li>
</ul>
</div>
@ -247,7 +247,7 @@ connected outliers are now an integral part of the network.</p>
<li class="right" >
<a href="using.html" title="Using Reticulum on Your System"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.3 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.4 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Building Networks</a></li>
</ul>
</div>

BIN
docs/manual/objects.inv
View File

Binary file not shown.

6
docs/manual/reference.html
View File

@ -5,7 +5,7 @@
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>API Reference &#8212; Reticulum Network Stack 0.3.3 beta documentation</title>
<title>API Reference &#8212; Reticulum Network Stack 0.3.4 beta documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" />
@ -31,7 +31,7 @@
<li class="right" >
<a href="understanding.html" title="Understanding Reticulum"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.3 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.4 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">API Reference</a></li>
</ul>
</div>
@ -1238,7 +1238,7 @@ will announce it.</p>
<li class="right" >
<a href="understanding.html" title="Understanding Reticulum"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.3 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.4 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">API Reference</a></li>
</ul>
</div>

6
docs/manual/search.html
View File

@ -5,7 +5,7 @@
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Search &#8212; Reticulum Network Stack 0.3.3 beta documentation</title>
<title>Search &#8212; Reticulum Network Stack 0.3.4 beta documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" />
@ -29,7 +29,7 @@
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.3 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.4 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Search</a></li>
</ul>
</div>
@ -85,7 +85,7 @@
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.3 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.4 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Search</a></li>
</ul>
</div>

2
docs/manual/searchindex.js
View File

File diff suppressed because one or more lines are too long

50
docs/manual/understanding.html
View File

@ -5,7 +5,7 @@
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Understanding Reticulum &#8212; Reticulum Network Stack 0.3.3 beta documentation</title>
<title>Understanding Reticulum &#8212; Reticulum Network Stack 0.3.4 beta documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" />
@ -31,7 +31,7 @@
<li class="right" >
<a href="interfaces.html" title="Supported Interfaces"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.3 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.4 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Understanding Reticulum</a></li>
</ul>
</div>
@ -334,14 +334,26 @@ hops in the network.</p>
networks are fundamentally incompatible with the physical link types that Reticulum was designed to handle.
These routing methodologies assume trust at the physical layer, and often needs a lot more bandwidth than
Reticulum can assume is available.</p>
<p>Since Reticulum is designed to run over open radio spectrum, no such trust exists, and bandwidth is often
very limited. Existing routing protocols like BGP or OSPF carry too much overhead to be practically
<p>Since Reticulum is designed to survive running over open radio spectrum, no such trust exists, and bandwidth
is often very limited. Existing routing protocols like BGP or OSPF carry too much overhead to be practically
useable over bandwidth-limited, high-latency links.</p>
<p>To overcome such challenges, Reticulum’s <em>Transport</em> system uses public-key cryptography to
implement the concept of <em>paths</em> that allow discovery of how to get information to a certain
implement the concept of <em>paths</em> that allow discovery of how to get information closer to a certain
destination. It is important to note that no single node in a Reticulum network knows the complete
path to a destination. Every Transport node participating in a Reticulum network will only
know what the most direct way to get a packet one hop closer to it’s destination is.</p>
<div class="section" id="node-types">
<span id="understanding-nodetypes"></span><h3>Node Types<a class="headerlink" href="#node-types" title="Permalink to this headline"></a></h3>
<p>Currently, Reticulum distinguishes between two types of network nodes. All nodes on a Reticulum network
are <em>Reticulum Instances</em>, and some are alo <em>Transport Nodes</em>. If a system running Reticulum is fixed in
one place, and is intended to be kept available most of the time, it can be a <em>Transport Node</em>, by enabling
it in the configuration.</p>
<p>This distinction is made by the user configuring the node, and is used to determine what nodes on the
network will help forward traffic, and what nodes rely on other nodes for wider connectivity.</p>
<p>If a node is a <em>Instance</em> it should be given the configuration directive <code class="docutils literal notranslate"><span class="pre">enable_transport</span> <span class="pre">=</span> <span class="pre">No</span></code>, which
is the default setting.</p>
<p>If it is a <em>Transport Node</em>, it should be given the configuration directive <code class="docutils literal notranslate"><span class="pre">enable_transport</span> <span class="pre">=</span> <span class="pre">Yes</span></code>.</p>
</div>
<div class="section" id="the-announce-mechanism-in-detail">
<span id="understanding-announce"></span><h3>The Announce Mechanism in Detail<a class="headerlink" href="#the-announce-mechanism-in-detail" title="Permalink to this headline"></a></h3>
<p>When an <em>announce</em> is transmitted by a node, it will be forwarded by any node receiving it, but
@ -358,7 +370,7 @@ total it has been retransmitted to get here.</div>
</li>
<li><div class="line-block">
<div class="line">If the announce has been retransmitted <em>m+1</em> times, it will not be forwarded. By default, <em>m</em> is
set to 18.</div>
set to 128.</div>
</div>
</li>
<li><div class="line-block">
@ -371,7 +383,7 @@ set to 18.</div>
</li>
<li><div class="line-block">
<div class="line">If at least <em>d</em> seconds has passed since the announce was received, and no other packets with a
priority higher than <em>p</em> are waiting in the queue (see Packet Prioritisation), and the channel is
priority higher than <em>p</em> are waiting in the queue, and the channel is
not utilized by other traffic, the announce will be forwarded.</div>
</div>
</li>
@ -398,10 +410,13 @@ addressed to that destination. Any node with knowledge of the announce will be a
packet towards the destination by looking up the next node with the shortest amount of hops to the
destination.</p>
<p>According to these rules and default constants, an announce will propagate throughout the network
in a predictable way. In an example network utilising the default constants, and with an average link
distance of <em>Lavg =</em> 15 kilometers, an announce will be able to propagate outwards to a radius of 180
kilometers in 34 minutes, and a <em>maximum announce radius</em> of 270 kilometers in approximately 3
days.</p>
in a predictable way.</p>
<p>As an example, in a network based only on radio transceivers with an average link distance of 15
kilometers, an announce will be able to propagate outwards over 12 hops, to a radius of 180
kilometers, in approximately 20 minutes.</p>
<p>The design and constants of the decay and delay functionality in the announce propagation is subject
to change and optimisation as real-world usage is explored. The announce propagation speed can be
increased at the cost of increased bandwidth consumption.</p>
</div>
<div class="section" id="reaching-the-destination">
<span id="understanding-paths"></span><h3>Reaching the Destination<a class="headerlink" href="#reaching-the-destination" title="Permalink to this headline"></a></h3>
@ -657,15 +672,6 @@ even if you have none of the hardware already, and need to purchase everything.<
<p>This chapter will detail protocol specific information that is essential to the implementation of
Reticulum, but non critical in understanding how the protocol works on a general level. It should be
treated more as a reference than as essential reading.</p>
<div class="section" id="node-types">
<h3>Node Types<a class="headerlink" href="#node-types" title="Permalink to this headline"></a></h3>
<p>Currently Reticulum defines two node types, the <em>Station</em> and the <em>Peer</em>. A node is a <em>station</em> if it fixed
in one place, and if it is intended to be kept online most of the time. Otherwise the node is a <em>peer</em>.</p>
<p>This distinction is made by the user configuring the node, and is used to determine what nodes on the
network will help forward traffic, and what nodes rely on other nodes for connectivity.</p>
<p>If a node is a <em>Peer</em> it should be given the configuration directive <code class="docutils literal notranslate"><span class="pre">enable_transport</span> <span class="pre">=</span> <span class="pre">No</span></code>.</p>
<p>If it is a <em>Station</em>, it should be given the configuration directive <code class="docutils literal notranslate"><span class="pre">enable_transport</span> <span class="pre">=</span> <span class="pre">Yes</span></code>.</p>
</div>
<div class="section" id="packet-prioritisation">
<h3>Packet Prioritisation<a class="headerlink" href="#packet-prioritisation" title="Permalink to this headline"></a></h3>
<p>Currently, Reticulum is completely priority-agnostic regarding general traffic. All traffic is handled
@ -798,6 +804,7 @@ proof 11
</ul>
</li>
<li><a class="reference internal" href="#reticulum-transport">Reticulum Transport</a><ul>
<li><a class="reference internal" href="#node-types">Node Types</a></li>
<li><a class="reference internal" href="#the-announce-mechanism-in-detail">The Announce Mechanism in Detail</a></li>
<li><a class="reference internal" href="#reaching-the-destination">Reaching the Destination</a><ul>
<li><a class="reference internal" href="#link-establishment-in-detail">Link Establishment in Detail</a></li>
@ -808,7 +815,6 @@ proof 11
</li>
<li><a class="reference internal" href="#reference-system-setup">Reference System Setup</a></li>
<li><a class="reference internal" href="#protocol-specifics">Protocol Specifics</a><ul>
<li><a class="reference internal" href="#node-types">Node Types</a></li>
<li><a class="reference internal" href="#packet-prioritisation">Packet Prioritisation</a></li>
<li><a class="reference internal" href="#binary-packet-format">Binary Packet Format</a></li>
</ul>
@ -856,7 +862,7 @@ proof 11
<li class="right" >
<a href="interfaces.html" title="Supported Interfaces"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.3 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.4 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Understanding Reticulum</a></li>
</ul>
</div>

6
docs/manual/using.html
View File

@ -5,7 +5,7 @@
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Using Reticulum on Your System &#8212; Reticulum Network Stack 0.3.3 beta documentation</title>
<title>Using Reticulum on Your System &#8212; Reticulum Network Stack 0.3.4 beta documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" />
@ -31,7 +31,7 @@
<li class="right" >
<a href="gettingstartedfast.html" title="Getting Started Fast"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.3 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.4 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Using Reticulum on Your System</a></li>
</ul>
</div>
@ -330,7 +330,7 @@ WantedBy=multi-user.target
<li class="right" >
<a href="gettingstartedfast.html" title="Getting Started Fast"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.3 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.4 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Using Reticulum on Your System</a></li>
</ul>
</div>

6
docs/manual/whatis.html
View File

@ -5,7 +5,7 @@
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>What is Reticulum? &#8212; Reticulum Network Stack 0.3.3 beta documentation</title>
<title>What is Reticulum? &#8212; Reticulum Network Stack 0.3.4 beta documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" />
@ -31,7 +31,7 @@
<li class="right" >
<a href="index.html" title="Reticulum Network Stack Manual"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.3 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.4 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">What is Reticulum?</a></li>
</ul>
</div>
@ -184,7 +184,7 @@ network, and vice versa.</p>
<li class="right" >
<a href="index.html" title="Reticulum Network Stack Manual"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.3 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.4 beta documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">What is Reticulum?</a></li>
</ul>
</div>

2
docs/source/conf.py
View File

@ -22,7 +22,7 @@ copyright = '2021, Mark Qvist'
author = 'Mark Qvist'
# The full version, including alpha/beta/rc tags
release = '0.3.3 beta'
release = '0.3.4 beta'
# -- General configuration ---------------------------------------------------

65
docs/source/gettingstartedfast.rst
View File

@ -35,6 +35,15 @@ 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.
If you would rather use a program with a graphical user interface, you can take
a look at `Sideband <https://unsigned.io/sideband>`_, which is available for Android,
Linux and macOS.
.. image:: screenshots/sideband_1.png
:width: 400px
:align: center
:target: _images/sideband_1.png
Using the Included Utilities
=============================================
@ -59,27 +68,34 @@ or use the interactive ``rnsconfig`` utility.
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 network (if there is one), and only allows you to
communicate with other Reticulum peers within your local broadcast domain.
your existing ethernet and WiFi networks (if any), and only allows you to
communicate with other Reticulum peers within your local broadcast domains.
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.
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.
Once Reticulums knows which interfaces it should use, it will automatically
discover topography and configure transport of data to any destinations it
knows about.
Possibly, the examples in the config file are enough to get you started. If
you want more information, you can read the :ref:`Building Networks<networks-main>`
and :ref:`Interfaces<interfaces-main>` chapters of this manual.
Bridging Over the Internet
=============================================
Reticulum currently offers two interfaces for connecting nodes over the internet:
`TCP <https://markqvist.github.io/Reticulum/manual/interfaces.html#tcp-server-interface>`_ and `I2P <https://markqvist.github.io/Reticulum/manual/interfaces.html#i2p-interface>`_. Each interface offers a different set of features, and Reticulum
Connecting Reticulum Instances Over the Internet
================================================
Reticulum currently offers two interfaces for connecting instances over the Internet: :ref:`TCP<interfaces-tcps>`
and :ref:`I2P<interfaces-i2p>`. Each interface offers a different set of features, and Reticulum
users should carefully choose the interface which best suites their needs.
The ``TCPServerInterface`` allows users to host a node accessible over TCP/IP. This
The ``TCPServerInterface`` allows users to host an instance accessible over TCP/IP. This
method is generally faster, lower latency, and more energy efficient than using ``I2PInterface``,
however it leaks considerable metadata about the server host.
however it also leaks considerable metadata about the server host.
Direct TCP client connections are able to see your node's IP address and may be able
to use this information to determine your location or identity. Adversaries
@ -101,16 +117,16 @@ bandwidth and compute power, but also makes timing attacks and other forms of
deep-packet-inspection much more difficult. Similar to RNS, I2P uses cryptographic
public keys as destination addresses, which allows users to host nodes on non-static IPs.
In general it is recommended to use an I2P node if you are hosting your node
publicly.
In general it is recommended to use an I2P node if you want to host a publically accessible
instance, while preserving anonymity. If you care more about performance, and a slightly
easier setup, use TCP.
There is a experimental public testnet you can join by adding the following
There is a experimental public testnet you can join by adding one of the following
interfaces to your ``.reticulum/config`` file:
.. code::
# For connecting over TCP/IP:
[[RNS Testnet Frankfurt]]
type = TCPClientInterface
interface_enabled = yes
@ -120,7 +136,6 @@ interfaces to your ``.reticulum/config`` file:
# For connecting over I2P:
[[RNS Testnet I2P Node A]]
type = I2PInterface
interface_enabled = yes
@ -212,8 +227,11 @@ installing Reticulum or programs that depend on Reticulum.
Reticulum on Android
==============================================
Reticulum can be used on Android in different ways. The easiest way to get
started is using the `Termux app <https://termux.com/>`_, at the time of writing
available on `F-droid <https://f-droid.org>`_.
started is using an app like `Sideband <https://unsigned.io/sideband>`_.
For more control and features, you can use Reticulum and related programs via
the `Termux app <https://termux.com/>`_, at the time of writing available on
`F-droid <https://f-droid.org>`_.
Termux is a terminal emulator and Linux environment for Android based devices,
which includes the ability to use many different programs and libraries,
@ -253,3 +271,18 @@ From within Termux, execute the following:
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.
Adding Radio Interfaces
==============================================
Once you have Reticulum installed and working, you can add radio interfaces with
any compatible hardware you have available. For information on how to configure
this, see the :ref:`Interfaces<interfaces-main>` section of this manual.
A range of common LoRa development boards and transceiver modules can be used
as interfaces with Reticulum. You can refer to the following external resources
for more information:
* `How To Make Your Own RNodes <https://unsigned.io/how-to-make-your-own-rnodes/>`_
* `Installing RNode Firmware on Compatible LoRa Devices <https://unsigned.io/installing-rnode-firmware-on-t-beam-and-lora32-devices/>`_
* `Private, Secure and Uncensorable Messaging Over a LoRa Mesh <https://unsigned.io/private-messaging-over-lora/>`_
* `RNode Firmware <https://github.com/markqvist/RNode_Firmware/>`_

BIN
docs/source/screenshots/sideband_1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 79 KiB

57
docs/source/understanding.rst
View File

@ -300,16 +300,36 @@ networks are fundamentally incompatible with the physical link types that Reticu
These routing methodologies assume trust at the physical layer, and often needs a lot more bandwidth than
Reticulum can assume is available.
Since Reticulum is designed to run over open radio spectrum, no such trust exists, and bandwidth is often
very limited. Existing routing protocols like BGP or OSPF carry too much overhead to be practically
Since Reticulum is designed to survive running over open radio spectrum, no such trust exists, and bandwidth
is often very limited. Existing routing protocols like BGP or OSPF carry too much overhead to be practically
useable over bandwidth-limited, high-latency links.
To overcome such challenges, Reticulum’s *Transport* system uses public-key cryptography to
implement the concept of *paths* that allow discovery of how to get information to a certain
implement the concept of *paths* that allow discovery of how to get information closer to a certain
destination. It is important to note that no single node in a Reticulum network knows the complete
path to a destination. Every Transport node participating in a Reticulum network will only
know what the most direct way to get a packet one hop closer to it's destination is.
.. _understanding-nodetypes:
Node Types
----------
Currently, Reticulum distinguishes between two types of network nodes. All nodes on a Reticulum network
are *Reticulum Instances*, and some are alo *Transport Nodes*. If a system running Reticulum is fixed in
one place, and is intended to be kept available most of the time, it can be a *Transport Node*, by enabling
it in the configuration.
This distinction is made by the user configuring the node, and is used to determine what nodes on the
network will help forward traffic, and what nodes rely on other nodes for wider connectivity.
If a node is a *Instance* it should be given the configuration directive ``enable_transport = No``, which
is the default setting.
If it is a *Transport Node*, it should be given the configuration directive ``enable_transport = Yes``.
.. _understanding-announce:
The Announce Mechanism in Detail
@ -325,14 +345,14 @@ according to some specific rules:
total it has been retransmitted to get here.
* | If the announce has been retransmitted *m+1* times, it will not be forwarded. By default, *m* is
set to 18.
set to 128.
* | The announce will be assigned a delay *d* = c\ :sup:`h` seconds, where *c* is a decay constant, and *h* is the amount of times this packet has already been forwarded.
* | The packet will be given a priority *p = 1/d*.
* | If at least *d* seconds has passed since the announce was received, and no other packets with a
priority higher than *p* are waiting in the queue (see Packet Prioritisation), and the channel is
priority higher than *p* are waiting in the queue, and the channel is
not utilized by other traffic, the announce will be forwarded.
* | If no other nodes are heard retransmitting the announce with a greater hop count than when
@ -354,10 +374,15 @@ packet towards the destination by looking up the next node with the shortest amo
destination.
According to these rules and default constants, an announce will propagate throughout the network
in a predictable way. In an example network utilising the default constants, and with an average link
distance of *Lavg =* 15 kilometers, an announce will be able to propagate outwards to a radius of 180
kilometers in 34 minutes, and a *maximum announce radius* of 270 kilometers in approximately 3
days.
in a predictable way.
As an example, in a network based only on radio transceivers with an average link distance of 15
kilometers, an announce will be able to propagate outwards over 12 hops, to a radius of 180
kilometers, in approximately 20 minutes.
The design and constants of the decay and delay functionality in the announce propagation is subject
to change and optimisation as real-world usage is explored. The announce propagation speed can be
increased at the cost of increased bandwidth consumption.
.. _understanding-paths:
@ -579,20 +604,6 @@ Reticulum, but non critical in understanding how the protocol works on a general
treated more as a reference than as essential reading.
Node Types
----------
Currently Reticulum defines two node types, the *Station* and the *Peer*. A node is a *station* if it fixed
in one place, and if it is intended to be kept online most of the time. Otherwise the node is a *peer*.
This distinction is made by the user configuring the node, and is used to determine what nodes on the
network will help forward traffic, and what nodes rely on other nodes for connectivity.
If a node is a *Peer* it should be given the configuration directive ``enable_transport = No``.
If it is a *Station*, it should be given the configuration directive ``enable_transport = Yes``.
Packet Prioritisation
---------------------