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 20:15:35 +02:00
parent ee90605b30
commit fc83c5b082
9 changed files with 159 additions and 124 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -97,32 +97,36 @@ The ``TCPServerInterface`` allows users to host an instance accessible over TCP/
method is generally faster, lower latency, and more energy efficient than using ``I2PInterface``,
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
Direct TCP client connections are able to see the IP address of your instance 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
like time of transmission and packet size. By default TCP does not encrypt traffic,
so an adversary may be able to use packet inspection to learn that a system is running
Reticulum, and what other IP adresses connect to it. Hosting a node via TCP server also
requires a public IP address.
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 adresses 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.
The ``I2PInterface`` routes messages through the `Invisible Internet Protocol
(I2P) <https://geti2p.net/en/>`_. To properly use this interface, users must also run an I2P daemon in
parallel to ``rnsd``. For always-on nodes it is recommended to use `i2pd <https://i2pd.website/>`_ because it
parallel to ``rnsd``. For always-on I2P nodes it is recommended to use `i2pd <https://i2pd.website/>`_ because it
generally runs more efficiently.
By default, I2P will fully encrypt all traffic sent over the network, and
obfuscate both the sender's and receiver's IP addresses. Running an I2P node
By default, I2P will encrypt 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. Similar to RNS, I2P uses cryptographic
public keys as destination addresses, which allows users to host nodes on non-static IPs.
deep-packet-inspection much more difficult.
I2P also allows users to host globally available Reticulum instances from non-public IPs and behind firewalls.
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 one of the following
interfaces to your ``.reticulum/config`` file:
Connect to the Public Testnet
===========================================
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 ``.reticulum/config`` file:
.. code::
@ -141,6 +145,10 @@ interfaces to your ``.reticulum/config`` file:
interface_enabled = yes
peers = ykzlw5ujbaqc2xkec4cpvgyxj257wcrmmgkuxqmqcur7cq3w3lha.b32.i2p
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.
Develop a Program with Reticulum
===========================================

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

@ -44,8 +44,7 @@ be a microwave network using off-the-shelf radios. At the time of release of thi
recommended setup for development and testing is using LoRa radio modules with an open source firmware
(see the section :ref:`Reference System Setup<understanding-referencesystem>`), connected to a small
computer like a Raspberry Pi. As an example, the default reference setup provides a channel capacity
of 5.4 Kbps, and a usable direct node-to-node range of around 15 kilometers (indefinitely extendable
by using multiple hops).
of 5.4 Kbps, and a usable direct node-to-node range of around 15 kilometers (extendable by using multiple hops).
.. _understanding-goals:
@ -543,57 +542,62 @@ or stream data directly from files.
.. _understanding-referencesystem:
Reference System Setup
Reference Setup
======================
This section will detail the recommended *Reference System Setup* for Reticulum. It is important to
note that Reticulum is designed to be usable over more or less any medium that allows you to send
and receive data in a digital form, and satisfies some very low minimum requirements. The
communication channel must support at least half-duplex operation, and provide an average
throughput of around 1000 bits per second, and supports a physical layer MTU of 500 bytes. The
Reticulum software should be able to run on more or less any hardware that can provide a Python 3.x
This section will detail a recommended *Reference Setup* for Reticulum. It is important to
note that Reticulum is designed to be usable on more or less any computing device, and over more
or less any medium that allows you to send and receive data, which satisfies some very low
minimum requirements.
The communication channel must support at least half-duplex operation, and provide an average
throughput of around 500 bits per second, and supports a physical layer MTU of 500 bytes. The
Reticulum stack should be able to run on more or less any hardware that can provide a Python 3.x
runtime environment.
That being said, the reference setup has been outlined to provide a common platform for anyone
That being said, this reference setup has been outlined to provide a common platform for anyone
who wants to help in the development of Reticulum, and for everyone who wants to know a
recommended setup to get started. A reference system consists of three parts:
recommended setup to get started experimenting. A reference system consists of three parts:
* **A channel access device**
Or *CAD* , in short, provides access to the physical medium whereupon the communication
* **An Interface Device**
Which provides access to the physical medium whereupon the communication
takes place, for example a radio with an integrated modem. A setup with a separate modem
connected to a radio would also be termed a “channel access device”.
* **A host device**
Some sort of computing device that can run the necessary software, communicates with the
channel access device, and provides user interaction.
* **A software stack**
connected to a radio would also be an interface device.
* **A Host Device**
Some sort of computing device that can run the necessary software, communicate with the
interface device, and provide user interaction.
* **A Software Stack**
The software implementing the Reticulum protocol and applications using it.
The reference setup can be considered a relatively stable platform to develop on, and also to start
building networks on. While details of the implementation might change at the current stage of
building networks or applications on. While details of the implementation might change at the current stage of
development, it is the goal to maintain hardware compatibility for as long as entirely possible, and
the current reference setup has been determined to provide a functional platform for many years
into the future. The current Reference System Setup is as follows:
* **Channel Access Device**
* **Interface Device**
A data radio consisting of a LoRa radio module, and a microcontroller with open source
firmware, that can connect to host devices via USB. It operates in either the 430, 868 or 900
MHz frequency bands. More details can be found on the `RNode Page <https://unsigned.io/rnode>`_.
* **Host device**
* **Host Device**
Any computer device running Linux and Python. A Raspberry Pi with a Debian based OS is
recommended.
* **Software stack**
The current Reference Implementation Release of Reticulum, running on a Debian based
* **Software Stack**
The most recently released Python Implementation of Reticulum, running on a Debian based
operating system.
It is very important to note, that the reference channel access device **does not** use the LoRaWAN
standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will
need a plain LoRa radio module connected to an MCU with the correct firmware. Full details on how to
To avoid confusion, it is very important to note, that the reference interface device **does not**
use the LoRaWAN standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will
need a plain LoRa radio module connected to an controller with the correct firmware. Full details on how to
get or make such a device is available on the `RNode Page <https://unsigned.io/rnode>`_.
With the current reference setup, it should be possible to get on a Reticulum network for around 100$
even if you have none of the hardware already, and need to purchase everything.
This reference setup is of course just a recommendation for getting started easily, and you should
tailor it to your own specific needs, or whatever hardware you have available.
.. _understanding-protocolspecifics:
Protocol Specifics
@ -675,7 +679,7 @@ Binary Packet Format
+- Packet Example -+
HEADER FIELD ADDRESSES FIELD CONTEXT FIELD DATA FIELD
HEADER FIELD DESTINATION FIELDS CONTEXT FIELD DATA FIELD
_______|_______ ________________|________________ ________|______ __|_
| | | | | | | |
01010000 00000100 [ADDR1, 10 bytes] [ADDR2, 10 bytes] [CONTEXT, 1 byte] [DATA]
@ -689,7 +693,7 @@ Binary Packet Format
+- Packet Example -+
HEADER FIELD ADDRESSES FIELD CONTEXT FIELD DATA FIELD
HEADER FIELD DESTINATION FIELD CONTEXT FIELD DATA FIELD
_______|_______ _______|_______ ________|______ __|_
| | | | | | | |
00000000 00000111 [ADDR1, 10 bytes] [CONTEXT, 1 byte] [DATA]

34
docs/manual/gettingstartedfast.html
View File

@ -114,28 +114,31 @@ users should carefully choose the interface which best suites their needs.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">TCPServerInterface</span></code> allows users to host an instance accessible over TCP/IP. This
method is generally faster, lower latency, and more energy efficient than using <code class="docutils literal notranslate"><span class="pre">I2PInterface</span></code>,
however it also leaks 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
<p>Direct TCP client connections are able to see the IP address of your instance 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
like time of transmission and packet size. By default TCP does not encrypt traffic,
so an adversary may be able to use packet inspection to learn that a system is running
Reticulum, and what other IP adresses connect to it. Hosting a node via TCP server also
requires a public IP address.</p>
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 adresses connect to it.
Hosting a publicly reachable instance over TCP also requires a publicly reachable IP address,
which most Internet connections don’t offer anymore.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">I2PInterface</span></code> routes messages through the <a class="reference external" href="https://geti2p.net/en/">Invisible Internet Protocol
(I2P)</a>. To properly use this interface, users must also run an I2P daemon in
parallel to <code class="docutils literal notranslate"><span class="pre">rnsd</span></code>. For always-on nodes it is recommended to use <a class="reference external" href="https://i2pd.website/">i2pd</a> because it
parallel to <code class="docutils literal notranslate"><span class="pre">rnsd</span></code>. For always-on I2P nodes it is recommended to use <a class="reference external" href="https://i2pd.website/">i2pd</a> because it
generally runs more efficiently.</p>
<p>By default, I2P will fully encrypt all traffic sent over the network, and
obfuscate both the sender’s and receiver’s IP addresses. Running an I2P node
<p>By default, I2P will encrypt 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. Similar to RNS, I2P uses cryptographic
public keys as destination addresses, which allows users to host nodes on non-static IPs.</p>
deep-packet-inspection much more difficult.</p>
<p>I2P also allows users to host globally available Reticulum instances from non-public IPs and behind firewalls.</p>
<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>
<div class="section" id="connect-to-the-public-testnet">
<h2>Connect to the Public Testnet<a class="headerlink" href="#connect-to-the-public-testnet" title="Permalink to this headline"></a></h2>
<p>An experimental public testnet has been made accessible over both I2P and TCP. You can join it
by adding one of the following interfaces to your <code class="docutils literal notranslate"><span class="pre">.reticulum/config</span></code> file:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># 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>
@ -152,6 +155,10 @@ interfaces to your <code class="docutils literal notranslate"><span class="pre">
<span class="n">peers</span> <span class="o">=</span> <span class="n">ykzlw5ujbaqc2xkec4cpvgyxj257wcrmmgkuxqmqcur7cq3w3lha</span><span class="o">.</span><span class="n">b32</span><span class="o">.</span><span class="n">i2p</span>
</pre></div>
</div>
<p>Many other Reticulum instances are connecting to this testnet, and you can also join it
via other entry points if you know them. There is absolutely no control over the network
topography, usage or what types of instances connect. It will also occasionally be used
to test various failure scenarios, and there are no availability or service guarantees.</p>
</div>
<div class="section" id="develop-a-program-with-reticulum">
<h2>Develop a Program with Reticulum<a class="headerlink" href="#develop-a-program-with-reticulum" title="Permalink to this headline"></a></h2>
@ -296,6 +303,7 @@ for more information:</p>
<li><a class="reference internal" href="#using-the-included-utilities">Using the Included Utilities</a></li>
<li><a class="reference internal" href="#creating-a-network-with-reticulum">Creating a Network With Reticulum</a></li>
<li><a class="reference internal" href="#connecting-reticulum-instances-over-the-internet">Connecting Reticulum Instances Over the Internet</a></li>
<li><a class="reference internal" href="#connect-to-the-public-testnet">Connect to the Public Testnet</a></li>
<li><a class="reference internal" href="#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>

3
docs/manual/index.html
View File

@ -57,6 +57,7 @@ to participate in the development of Reticulum itself.</p>
<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#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#connect-to-the-public-testnet">Connect to the Public Testnet</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>
@ -119,7 +120,7 @@ to participate in the development of Reticulum itself.</p>
<li class="toctree-l3"><a class="reference internal" href="understanding.html#resources">Resources</a></li>
</ul>
</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#reference-setup">Reference 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#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>

BIN
docs/manual/objects.inv
View File

Binary file not shown.

2
docs/manual/searchindex.js
View File

File diff suppressed because one or more lines are too long

56
docs/manual/understanding.html
View File

@ -75,8 +75,7 @@ be a microwave network using off-the-shelf radios. At the time of release of thi
recommended setup for development and testing is using LoRa radio modules with an open source firmware
(see the section <a class="reference internal" href="#understanding-referencesystem"><span class="std std-ref">Reference System Setup</span></a>), connected to a small
computer like a Raspberry Pi. As an example, the default reference setup provides a channel capacity
of 5.4 Kbps, and a usable direct node-to-node range of around 15 kilometers (indefinitely extendable
by using multiple hops).</p>
of 5.4 Kbps, and a usable direct node-to-node range of around 15 kilometers (extendable by using multiple hops).</p>
</div>
<div class="section" id="goals">
<span id="understanding-goals"></span><h2>Goals<a class="headerlink" href="#goals" title="Permalink to this headline"></a></h2>
@ -602,70 +601,73 @@ of codes to reliably transfer any amount of data. They can be used to transfer d
or stream data directly from files.</p>
</div>
</div>
<div class="section" id="reference-system-setup">
<span id="understanding-referencesystem"></span><h2>Reference System Setup<a class="headerlink" href="#reference-system-setup" title="Permalink to this headline"></a></h2>
<p>This section will detail the recommended <em>Reference System Setup</em> for Reticulum. It is important to
note that Reticulum is designed to be usable over more or less any medium that allows you to send
and receive data in a digital form, and satisfies some very low minimum requirements. The
communication channel must support at least half-duplex operation, and provide an average
throughput of around 1000 bits per second, and supports a physical layer MTU of 500 bytes. The
Reticulum software should be able to run on more or less any hardware that can provide a Python 3.x
<div class="section" id="reference-setup">
<span id="understanding-referencesystem"></span><h2>Reference Setup<a class="headerlink" href="#reference-setup" title="Permalink to this headline"></a></h2>
<p>This section will detail a recommended <em>Reference Setup</em> for Reticulum. It is important to
note that Reticulum is designed to be usable on more or less any computing device, and over more
or less any medium that allows you to send and receive data, which satisfies some very low
minimum requirements.</p>
<p>The communication channel must support at least half-duplex operation, and provide an average
throughput of around 500 bits per second, and supports a physical layer MTU of 500 bytes. The
Reticulum stack should be able to run on more or less any hardware that can provide a Python 3.x
runtime environment.</p>
<p>That being said, the reference setup has been outlined to provide a common platform for anyone
<p>That being said, this reference setup has been outlined to provide a common platform for anyone
who wants to help in the development of Reticulum, and for everyone who wants to know a
recommended setup to get started. A reference system consists of three parts:</p>
recommended setup to get started experimenting. A reference system consists of three parts:</p>
<ul class="simple">
<li><dl class="simple">
<dt><strong>A channel access device</strong></dt><dd><p>Or <em>CAD</em> , in short, provides access to the physical medium whereupon the communication
<dt><strong>An Interface Device</strong></dt><dd><p>Which provides access to the physical medium whereupon the communication
takes place, for example a radio with an integrated modem. A setup with a separate modem
connected to a radio would also be termed a “channel access device”.</p>
connected to a radio would also be an interface device.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt><strong>A host device</strong></dt><dd><p>Some sort of computing device that can run the necessary software, communicates with the
channel access device, and provides user interaction.</p>
<dt><strong>A Host Device</strong></dt><dd><p>Some sort of computing device that can run the necessary software, communicate with the
interface device, and provide user interaction.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt><strong>A software stack</strong></dt><dd><p>The software implementing the Reticulum protocol and applications using it.</p>
<dt><strong>A Software Stack</strong></dt><dd><p>The software implementing the Reticulum protocol and applications using it.</p>
</dd>
</dl>
</li>
</ul>
<p>The reference setup can be considered a relatively stable platform to develop on, and also to start
building networks on. While details of the implementation might change at the current stage of
building networks or applications on. While details of the implementation might change at the current stage of
development, it is the goal to maintain hardware compatibility for as long as entirely possible, and
the current reference setup has been determined to provide a functional platform for many years
into the future. The current Reference System Setup is as follows:</p>
<ul class="simple">
<li><dl class="simple">
<dt><strong>Channel Access Device</strong></dt><dd><p>A data radio consisting of a LoRa radio module, and a microcontroller with open source
<dt><strong>Interface Device</strong></dt><dd><p>A data radio consisting of a LoRa radio module, and a microcontroller with open source
firmware, that can connect to host devices via USB. It operates in either the 430, 868 or 900
MHz frequency bands. More details can be found on the <a class="reference external" href="https://unsigned.io/rnode">RNode Page</a>.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt><strong>Host device</strong></dt><dd><p>Any computer device running Linux and Python. A Raspberry Pi with a Debian based OS is
<dt><strong>Host Device</strong></dt><dd><p>Any computer device running Linux and Python. A Raspberry Pi with a Debian based OS is
recommended.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt><strong>Software stack</strong></dt><dd><p>The current Reference Implementation Release of Reticulum, running on a Debian based
<dt><strong>Software Stack</strong></dt><dd><p>The most recently released Python Implementation of Reticulum, running on a Debian based
operating system.</p>
</dd>
</dl>
</li>
</ul>
<p>It is very important to note, that the reference channel access device <strong>does not</strong> use the LoRaWAN
standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will
need a plain LoRa radio module connected to an MCU with the correct firmware. Full details on how to
<p>To avoid confusion, it is very important to note, that the reference interface device <strong>does not</strong>
use the LoRaWAN standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will
need a plain LoRa radio module connected to an controller with the correct firmware. Full details on how to
get or make such a device is available on the <a class="reference external" href="https://unsigned.io/rnode">RNode Page</a>.</p>
<p>With the current reference setup, it should be possible to get on a Reticulum network for around 100$
even if you have none of the hardware already, and need to purchase everything.</p>
<p>This reference setup is of course just a recommendation for getting started easily, and you should
tailor it to your own specific needs, or whatever hardware you have available.</p>
</div>
<div class="section" id="protocol-specifics">
<span id="understanding-protocolspecifics"></span><h2>Protocol Specifics<a class="headerlink" href="#protocol-specifics" title="Permalink to this headline"></a></h2>
@ -736,7 +738,7 @@ proof 11
+- Packet Example -+
HEADER FIELD ADDRESSES FIELD CONTEXT FIELD DATA FIELD
HEADER FIELD DESTINATION FIELDS CONTEXT FIELD DATA FIELD
_______|_______ ________________|________________ ________|______ __|_
| | | | | | | |
01010000 00000100 [ADDR1, 10 bytes] [ADDR2, 10 bytes] [CONTEXT, 1 byte] [DATA]
@ -750,7 +752,7 @@ proof 11
+- Packet Example -+
HEADER FIELD ADDRESSES FIELD CONTEXT FIELD DATA FIELD
HEADER FIELD DESTINATION FIELD CONTEXT FIELD DATA FIELD
_______|_______ _______|_______ ________|______ __|_
| | | | | | | |
00000000 00000111 [ADDR1, 10 bytes] [CONTEXT, 1 byte] [DATA]
@ -813,7 +815,7 @@ proof 11
<li><a class="reference internal" href="#resources">Resources</a></li>
</ul>
</li>
<li><a class="reference internal" href="#reference-system-setup">Reference System Setup</a></li>
<li><a class="reference internal" href="#reference-setup">Reference Setup</a></li>
<li><a class="reference internal" href="#protocol-specifics">Protocol Specifics</a><ul>
<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>

34
docs/source/gettingstartedfast.rst
View File

@ -97,32 +97,36 @@ The ``TCPServerInterface`` allows users to host an instance accessible over TCP/
method is generally faster, lower latency, and more energy efficient than using ``I2PInterface``,
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
Direct TCP client connections are able to see the IP address of your instance 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
like time of transmission and packet size. By default TCP does not encrypt traffic,
so an adversary may be able to use packet inspection to learn that a system is running
Reticulum, and what other IP adresses connect to it. Hosting a node via TCP server also
requires a public IP address.
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 adresses 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.
The ``I2PInterface`` routes messages through the `Invisible Internet Protocol
(I2P) <https://geti2p.net/en/>`_. To properly use this interface, users must also run an I2P daemon in
parallel to ``rnsd``. For always-on nodes it is recommended to use `i2pd <https://i2pd.website/>`_ because it
parallel to ``rnsd``. For always-on I2P nodes it is recommended to use `i2pd <https://i2pd.website/>`_ because it
generally runs more efficiently.
By default, I2P will fully encrypt all traffic sent over the network, and
obfuscate both the sender's and receiver's IP addresses. Running an I2P node
By default, I2P will encrypt 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. Similar to RNS, I2P uses cryptographic
public keys as destination addresses, which allows users to host nodes on non-static IPs.
deep-packet-inspection much more difficult.
I2P also allows users to host globally available Reticulum instances from non-public IPs and behind firewalls.
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 one of the following
interfaces to your ``.reticulum/config`` file:
Connect to the Public Testnet
===========================================
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 ``.reticulum/config`` file:
.. code::
@ -141,6 +145,10 @@ interfaces to your ``.reticulum/config`` file:
interface_enabled = yes
peers = ykzlw5ujbaqc2xkec4cpvgyxj257wcrmmgkuxqmqcur7cq3w3lha.b32.i2p
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.
Develop a Program with Reticulum
===========================================

60
docs/source/understanding.rst
View File

@ -44,8 +44,7 @@ be a microwave network using off-the-shelf radios. At the time of release of thi
recommended setup for development and testing is using LoRa radio modules with an open source firmware
(see the section :ref:`Reference System Setup<understanding-referencesystem>`), connected to a small
computer like a Raspberry Pi. As an example, the default reference setup provides a channel capacity
of 5.4 Kbps, and a usable direct node-to-node range of around 15 kilometers (indefinitely extendable
by using multiple hops).
of 5.4 Kbps, and a usable direct node-to-node range of around 15 kilometers (extendable by using multiple hops).
.. _understanding-goals:
@ -543,57 +542,62 @@ or stream data directly from files.
.. _understanding-referencesystem:
Reference System Setup
Reference Setup
======================
This section will detail the recommended *Reference System Setup* for Reticulum. It is important to
note that Reticulum is designed to be usable over more or less any medium that allows you to send
and receive data in a digital form, and satisfies some very low minimum requirements. The
communication channel must support at least half-duplex operation, and provide an average
throughput of around 1000 bits per second, and supports a physical layer MTU of 500 bytes. The
Reticulum software should be able to run on more or less any hardware that can provide a Python 3.x
This section will detail a recommended *Reference Setup* for Reticulum. It is important to
note that Reticulum is designed to be usable on more or less any computing device, and over more
or less any medium that allows you to send and receive data, which satisfies some very low
minimum requirements.
The communication channel must support at least half-duplex operation, and provide an average
throughput of around 500 bits per second, and supports a physical layer MTU of 500 bytes. The
Reticulum stack should be able to run on more or less any hardware that can provide a Python 3.x
runtime environment.
That being said, the reference setup has been outlined to provide a common platform for anyone
That being said, this reference setup has been outlined to provide a common platform for anyone
who wants to help in the development of Reticulum, and for everyone who wants to know a
recommended setup to get started. A reference system consists of three parts:
recommended setup to get started experimenting. A reference system consists of three parts:
* **A channel access device**
Or *CAD* , in short, provides access to the physical medium whereupon the communication
* **An Interface Device**
Which provides access to the physical medium whereupon the communication
takes place, for example a radio with an integrated modem. A setup with a separate modem
connected to a radio would also be termed a “channel access device”.
* **A host device**
Some sort of computing device that can run the necessary software, communicates with the
channel access device, and provides user interaction.
* **A software stack**
connected to a radio would also be an interface device.
* **A Host Device**
Some sort of computing device that can run the necessary software, communicate with the
interface device, and provide user interaction.
* **A Software Stack**
The software implementing the Reticulum protocol and applications using it.
The reference setup can be considered a relatively stable platform to develop on, and also to start
building networks on. While details of the implementation might change at the current stage of
building networks or applications on. While details of the implementation might change at the current stage of
development, it is the goal to maintain hardware compatibility for as long as entirely possible, and
the current reference setup has been determined to provide a functional platform for many years
into the future. The current Reference System Setup is as follows:
* **Channel Access Device**
* **Interface Device**
A data radio consisting of a LoRa radio module, and a microcontroller with open source
firmware, that can connect to host devices via USB. It operates in either the 430, 868 or 900
MHz frequency bands. More details can be found on the `RNode Page <https://unsigned.io/rnode>`_.
* **Host device**
* **Host Device**
Any computer device running Linux and Python. A Raspberry Pi with a Debian based OS is
recommended.
* **Software stack**
The current Reference Implementation Release of Reticulum, running on a Debian based
* **Software Stack**
The most recently released Python Implementation of Reticulum, running on a Debian based
operating system.
It is very important to note, that the reference channel access device **does not** use the LoRaWAN
standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will
need a plain LoRa radio module connected to an MCU with the correct firmware. Full details on how to
To avoid confusion, it is very important to note, that the reference interface device **does not**
use the LoRaWAN standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will
need a plain LoRa radio module connected to an controller with the correct firmware. Full details on how to
get or make such a device is available on the `RNode Page <https://unsigned.io/rnode>`_.
With the current reference setup, it should be possible to get on a Reticulum network for around 100$
even if you have none of the hardware already, and need to purchase everything.
This reference setup is of course just a recommendation for getting started easily, and you should
tailor it to your own specific needs, or whatever hardware you have available.
.. _understanding-protocolspecifics:
Protocol Specifics
@ -675,7 +679,7 @@ Binary Packet Format
+- Packet Example -+
HEADER FIELD ADDRESSES FIELD CONTEXT FIELD DATA FIELD
HEADER FIELD DESTINATION FIELDS CONTEXT FIELD DATA FIELD
_______|_______ ________________|________________ ________|______ __|_
| | | | | | | |
01010000 00000100 [ADDR1, 10 bytes] [ADDR2, 10 bytes] [CONTEXT, 1 byte] [DATA]
@ -689,7 +693,7 @@ Binary Packet Format
+- Packet Example -+
HEADER FIELD ADDRESSES FIELD CONTEXT FIELD DATA FIELD
HEADER FIELD DESTINATION FIELD CONTEXT FIELD DATA FIELD
_______|_______ _______|_______ ________|______ __|_
| | | | | | | |
00000000 00000111 [ADDR1, 10 bytes] [CONTEXT, 1 byte] [DATA]