mirror of
https://github.com/markqvist/Reticulum.git
synced 2024-11-04 21:30:14 +00:00
Updated documentation
This commit is contained in:
parent
ee90605b30
commit
fc83c5b082
@ -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
|
||||
===========================================
|
||||
|
@ -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]
|
||||
|
@ -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>
|
||||
|
@ -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>
|
||||
|
Binary file not shown.
File diff suppressed because one or more lines are too long
@ -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>
|
||||
|
@ -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
|
||||
===========================================
|
||||
|
@ -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]
|
||||
|
Loading…
Reference in New Issue
Block a user