mirror of
https://github.com/markqvist/Reticulum.git
synced 2024-11-05 05:40:14 +00:00
Updated documentation
This commit is contained in:
parent
b8ca89c2b6
commit
29df5950c8
@ -324,3 +324,7 @@ for more information:
|
|||||||
* `Installing RNode Firmware on Compatible LoRa Devices <https://unsigned.io/installing-rnode-firmware-on-t-beam-and-lora32-devices/>`_
|
* `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/>`_
|
* `Private, Secure and Uncensorable Messaging Over a LoRa Mesh <https://unsigned.io/private-messaging-over-lora/>`_
|
||||||
* `RNode Firmware <https://github.com/markqvist/RNode_Firmware/>`_
|
* `RNode Firmware <https://github.com/markqvist/RNode_Firmware/>`_
|
||||||
|
|
||||||
|
If you have communications hardware that you think would be suitable for use with Reticulum,
|
||||||
|
you are welcome to head over to the `GitHub discussion pages <https://github.com/markqvist/Reticulum/discussions>`_
|
||||||
|
and propose adding an interface for the hardware.
|
@ -18,6 +18,72 @@ For a high-level overview of how networks can be formed over different interface
|
|||||||
types, have a look at the :ref:`Building Networks<networks-main>` chapter of this
|
types, have a look at the :ref:`Building Networks<networks-main>` chapter of this
|
||||||
manual.
|
manual.
|
||||||
|
|
||||||
|
|
||||||
|
.. _interfaces-options:
|
||||||
|
|
||||||
|
Common Interface Options
|
||||||
|
========================
|
||||||
|
|
||||||
|
A number of general configuration options are available on most interfaces.
|
||||||
|
These can be used to control various aspects of interface behaviour.
|
||||||
|
|
||||||
|
|
||||||
|
* | The ``enabled`` option tells Reticulum whether or not
|
||||||
|
to bring up the interface. Defaults to ``False``. For any
|
||||||
|
interface to be brought up, the ``enabled`` option
|
||||||
|
must be set to ``True`` or ``Yes``.
|
||||||
|
|
||||||
|
* | The ``mode`` option allows selecting the high-level behaviour
|
||||||
|
of the interface from a number of options.
|
||||||
|
|
||||||
|
- The default value is ``full``. In this mode, all discovery,
|
||||||
|
meshing and transport functionality is available.
|
||||||
|
|
||||||
|
- In the ``access_point`` (or shorthand ``ap``) mode, the
|
||||||
|
interface will operate as a network access point. In this
|
||||||
|
mode, announces will not be automatically broadcasted on
|
||||||
|
the interface, and paths to destinations on the interface
|
||||||
|
will have a much shorter expiry time. This mode is useful
|
||||||
|
for creating interfaces that are mostly quiet, unless when
|
||||||
|
someone is actually using them. An example of this could
|
||||||
|
be a radio interface serving a wide area, where users are
|
||||||
|
expected to connect momentarily, use the network, and then
|
||||||
|
disappear again.
|
||||||
|
|
||||||
|
* | The ``outgoing`` option sets whether an interface is allowed
|
||||||
|
to transmit. Defaults to ``True``. If set to ``False`` or ``No``
|
||||||
|
the interface will only receive data, and never transmit.
|
||||||
|
|
||||||
|
* | The ``network_name`` option sets the virtual network name for
|
||||||
|
the interface. This allows multiple separate network segments
|
||||||
|
to exist on the same physical channel or medium.
|
||||||
|
|
||||||
|
* | The ``passphrase`` option sets an authentication passphrase on
|
||||||
|
the interface. This option can be used in conjunction with the
|
||||||
|
``network_name`` option, or be used alone.
|
||||||
|
|
||||||
|
* | The ``ifac_size`` option allows customising the length of the
|
||||||
|
Interface Authentication Codes carried by each packet on named
|
||||||
|
and/or authenticated network segments. It is set by default to
|
||||||
|
a size suitable for the interface in question, but can be set
|
||||||
|
to a custom size between 8 and 512 bits by using this option.
|
||||||
|
In normal usage, this option should not be changed from the
|
||||||
|
default.
|
||||||
|
|
||||||
|
* | The ``announce_cap`` option lets you configure the maximum
|
||||||
|
bandwidth to allocate, at any given time, to propagating
|
||||||
|
announces and other network upkeep traffic. It is configured at
|
||||||
|
2% by default, and should normally not need to be changed. Can
|
||||||
|
be set to any value between ``1`` and ``100``.
|
||||||
|
|
||||||
|
* | The ``bitrate`` option configures the interface bitrate.
|
||||||
|
Reticulum will use interface speeds reported by hardware, or
|
||||||
|
try to guess a suitable rate when the hardware doesn't report
|
||||||
|
any. In most cases, the automatically found rate should be
|
||||||
|
sufficient, but it can be configured by using the ``bitrate``
|
||||||
|
option, to set the interface speed in *bits per second*.
|
||||||
|
|
||||||
|
|
||||||
.. _interfaces-auto:
|
.. _interfaces-auto:
|
||||||
|
|
||||||
Auto Interface
|
Auto Interface
|
||||||
@ -512,39 +578,3 @@ beaconing functionality described above.
|
|||||||
# This is useful for modems with a
|
# This is useful for modems with a
|
||||||
# small internal packet buffer.
|
# small internal packet buffer.
|
||||||
flow_control = false
|
flow_control = false
|
||||||
|
|
||||||
|
|
||||||
.. _interfaces-options:
|
|
||||||
|
|
||||||
Common Interface Options
|
|
||||||
========================
|
|
||||||
|
|
||||||
A number of general options are available on most interfaces.
|
|
||||||
These can be used to control various aspects of interface behaviour.
|
|
||||||
|
|
||||||
|
|
||||||
The ``enabled`` option tells Reticulum whether or not
|
|
||||||
to bring up the interface. Defaults to ``False``. For any
|
|
||||||
interface to be brought up, the ``enabled`` option
|
|
||||||
must be set to ``True`` or ``Yes``.
|
|
||||||
|
|
||||||
The ``outgoing`` option sets whether an interface is allowed
|
|
||||||
to transmit. Defaults to ``True``. If set to ``False`` or ``No``
|
|
||||||
the interface will only receive data, and never transmit.
|
|
||||||
|
|
||||||
The ``mode`` option allows selecting the high-level behaviour
|
|
||||||
of the interface from a number of options.
|
|
||||||
|
|
||||||
- The default value is ``full``. In this mode, all discovery,
|
|
||||||
meshing and transport functionality is available.
|
|
||||||
|
|
||||||
- In the ``access_point`` (or shorthand ``ap``) mode, the
|
|
||||||
interface will operate as a network access point. In this
|
|
||||||
mode, announces will not be automatically broadcasted on
|
|
||||||
the interface, and paths to destinations on the interface
|
|
||||||
will have a much shorter expiry time. This mode is useful
|
|
||||||
for creating interfaces that are mostly quiet, unless when
|
|
||||||
someone is actually using them. An example of this could
|
|
||||||
be a radio interface serving a wide area, where users are
|
|
||||||
expected to connect momentarily, use the network, and then
|
|
||||||
disappear again.
|
|
||||||
|
@ -27,6 +27,11 @@ with Reticulum:
|
|||||||
While the adress space can support billions of endpoints, Reticulum is
|
While the adress space can support billions of endpoints, Reticulum is
|
||||||
also very useful when just a few devices needs to communicate.
|
also very useful when just a few devices needs to communicate.
|
||||||
|
|
||||||
|
* | Low-bandwidth networks, like LoRa and packet radio, can interoperate and
|
||||||
|
interconnect with much larger and higher bandwidth networks without issue.
|
||||||
|
Reticulum automatically manages the flow of information to and from various
|
||||||
|
network segments, and when bandwidth is limited, local traffic is prioritised.
|
||||||
|
|
||||||
* | Reticulum provides sender/initiator anonymity by default. There is no way
|
* | Reticulum provides sender/initiator anonymity by default. There is no way
|
||||||
to filter traffic or discriminate it based on the source of the traffic.
|
to filter traffic or discriminate it based on the source of the traffic.
|
||||||
|
|
||||||
@ -47,18 +52,32 @@ with Reticulum:
|
|||||||
transport node. Letting every node be a transport node will in most cases
|
transport node. Letting every node be a transport node will in most cases
|
||||||
degrade the performance and reliability of the network.
|
degrade the performance and reliability of the network.
|
||||||
|
|
||||||
In general terms, if a node is stationary, well-connected and kept running
|
*In general terms, if a node is stationary, well-connected and kept running
|
||||||
most of the time, it is a good candidate to be a transport node. For optimal
|
most of the time, it is a good candidate to be a transport node. For optimal
|
||||||
performance, a network should contain the amount of transport nodes that
|
performance, a network should contain the amount of transport nodes that
|
||||||
provides connectivity to the intended area / topography, and not many more
|
provides connectivity to the intended area / topography, and not many more
|
||||||
than that.
|
than that.*
|
||||||
|
|
||||||
|
* | Reticulum is designed to work reliably in open, trustless environments. This
|
||||||
|
means you can use it to create open-access networks, where participants can
|
||||||
|
join and leave in an free and unorganised manner. This property allows an
|
||||||
|
entirely new, and so far, mostly unexplored class of networked applications,
|
||||||
|
where networks, and the information flow within them can form and dissolve
|
||||||
|
organically.
|
||||||
|
|
||||||
|
* | You can just as easily create closed networks, since Reticulum allows you to
|
||||||
|
add authentication to any interface. This means you can restrict access on
|
||||||
|
any interface type, even when using legacy devices, such as modems. You can
|
||||||
|
also mix authenticated and open interfaces on the same system. See the
|
||||||
|
:ref:`Common Interface Options<interfaces-options>` section of the :ref:`Interfaces<interfaces-main>`
|
||||||
|
chapter of this manual for information on how to set up interface authentication.
|
||||||
|
|
||||||
|
|
||||||
Reticulum allows you to mix very different kinds of networking mediums into a
|
Reticulum allows you to mix very different kinds of networking mediums into a
|
||||||
unified mesh, or to keep everything within one medium. You could build a "virtual
|
unified mesh, or to keep everything within one medium. You could build a "virtual
|
||||||
network" running entirely over the Internet, where all nodes communicate over TCP
|
network" running entirely over the Internet, where all nodes communicate over TCP
|
||||||
and UDP "channels". You could also build such a network using MQTT or ZeroMQ as
|
and UDP "channels". You could also build such a network using other already-established
|
||||||
the underlying carrier for Reticulum.
|
communications channels as the underlying carrier for Reticulum.
|
||||||
|
|
||||||
However, most real-world networks will probably involve either some form of
|
However, most real-world networks will probably involve either some form of
|
||||||
wireless or direct hardline communications. To allow Reticulum to communicate
|
wireless or direct hardline communications. To allow Reticulum to communicate
|
||||||
|
@ -6,7 +6,8 @@ Using Reticulum on Your System
|
|||||||
|
|
||||||
Reticulum is not installed as a driver or kernel module, as one might expect
|
Reticulum is not installed as a driver or kernel module, as one might expect
|
||||||
of a networking stack. Instead, Reticulum is distributed as a Python module.
|
of a networking stack. Instead, Reticulum is distributed as a Python module.
|
||||||
This means that no special privileges are required to install or use it.
|
This means that no special privileges are required to install or use it. It
|
||||||
|
is also very light-weight, and easy to transfer to and install on new systems.
|
||||||
Any program or application that uses Reticulum will automatically load and
|
Any program or application that uses Reticulum will automatically load and
|
||||||
initialise Reticulum when it starts.
|
initialise Reticulum when it starts.
|
||||||
|
|
||||||
|
@ -311,6 +311,9 @@ for more information:</p>
|
|||||||
<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://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>
|
<li><p><a class="reference external" href="https://github.com/markqvist/RNode_Firmware/">RNode Firmware</a></p></li>
|
||||||
</ul>
|
</ul>
|
||||||
|
<p>If you have communications hardware that you think would be suitable for use with Reticulum,
|
||||||
|
you are welcome to head over to the <a class="reference external" href="https://github.com/markqvist/Reticulum/discussions">GitHub discussion pages</a>
|
||||||
|
and propose adding an interface for the hardware.</p>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
|
@ -95,6 +95,7 @@ to participate in the development of Reticulum itself.</p>
|
|||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Supported Interfaces</a><ul>
|
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Supported Interfaces</a><ul>
|
||||||
|
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#common-interface-options">Common Interface Options</a></li>
|
||||||
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#auto-interface">Auto Interface</a></li>
|
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#auto-interface">Auto Interface</a></li>
|
||||||
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#i2p-interface">I2P Interface</a></li>
|
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#i2p-interface">I2P Interface</a></li>
|
||||||
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#tcp-server-interface">TCP Server Interface</a></li>
|
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#tcp-server-interface">TCP Server Interface</a></li>
|
||||||
@ -104,7 +105,6 @@ to participate in the development of Reticulum itself.</p>
|
|||||||
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#serial-interface">Serial Interface</a></li>
|
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#serial-interface">Serial Interface</a></li>
|
||||||
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#kiss-interface">KISS Interface</a></li>
|
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#kiss-interface">KISS Interface</a></li>
|
||||||
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#ax-25-kiss-interface">AX.25 KISS Interface</a></li>
|
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#ax-25-kiss-interface">AX.25 KISS Interface</a></li>
|
||||||
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#common-interface-options">Common Interface Options</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a><ul>
|
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a><ul>
|
||||||
|
@ -53,6 +53,88 @@ and gives example configurations for the respective interface types.</p>
|
|||||||
<p>For a high-level overview of how networks can be formed over different interface
|
<p>For a high-level overview of how networks can be formed over different interface
|
||||||
types, have a look at the <a class="reference internal" href="networks.html#networks-main"><span class="std std-ref">Building Networks</span></a> chapter of this
|
types, have a look at the <a class="reference internal" href="networks.html#networks-main"><span class="std std-ref">Building Networks</span></a> chapter of this
|
||||||
manual.</p>
|
manual.</p>
|
||||||
|
<div class="section" id="common-interface-options">
|
||||||
|
<span id="interfaces-options"></span><h2>Common Interface Options<a class="headerlink" href="#common-interface-options" title="Permalink to this headline">¶</a></h2>
|
||||||
|
<p>A number of general configuration options are available on most interfaces.
|
||||||
|
These can be used to control various aspects of interface behaviour.</p>
|
||||||
|
<blockquote>
|
||||||
|
<div><ul>
|
||||||
|
<li><div class="line-block">
|
||||||
|
<div class="line">The <code class="docutils literal notranslate"><span class="pre">enabled</span></code> option tells Reticulum whether or not
|
||||||
|
to bring up the interface. Defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>. For any
|
||||||
|
interface to be brought up, the <code class="docutils literal notranslate"><span class="pre">enabled</span></code> option
|
||||||
|
must be set to <code class="docutils literal notranslate"><span class="pre">True</span></code> or <code class="docutils literal notranslate"><span class="pre">Yes</span></code>.</div>
|
||||||
|
</div>
|
||||||
|
</li>
|
||||||
|
<li><div class="line-block">
|
||||||
|
<div class="line">The <code class="docutils literal notranslate"><span class="pre">mode</span></code> option allows selecting the high-level behaviour
|
||||||
|
of the interface from a number of options.</div>
|
||||||
|
</div>
|
||||||
|
<blockquote>
|
||||||
|
<div><ul class="simple">
|
||||||
|
<li><p>The default value is <code class="docutils literal notranslate"><span class="pre">full</span></code>. In this mode, all discovery,
|
||||||
|
meshing and transport functionality is available.</p></li>
|
||||||
|
<li><p>In the <code class="docutils literal notranslate"><span class="pre">access_point</span></code> (or shorthand <code class="docutils literal notranslate"><span class="pre">ap</span></code>) mode, the
|
||||||
|
interface will operate as a network access point. In this
|
||||||
|
mode, announces will not be automatically broadcasted on
|
||||||
|
the interface, and paths to destinations on the interface
|
||||||
|
will have a much shorter expiry time. This mode is useful
|
||||||
|
for creating interfaces that are mostly quiet, unless when
|
||||||
|
someone is actually using them. An example of this could
|
||||||
|
be a radio interface serving a wide area, where users are
|
||||||
|
expected to connect momentarily, use the network, and then
|
||||||
|
disappear again.</p></li>
|
||||||
|
</ul>
|
||||||
|
</div></blockquote>
|
||||||
|
</li>
|
||||||
|
<li><div class="line-block">
|
||||||
|
<div class="line">The <code class="docutils literal notranslate"><span class="pre">outgoing</span></code> option sets whether an interface is allowed
|
||||||
|
to transmit. Defaults to <code class="docutils literal notranslate"><span class="pre">True</span></code>. If set to <code class="docutils literal notranslate"><span class="pre">False</span></code> or <code class="docutils literal notranslate"><span class="pre">No</span></code>
|
||||||
|
the interface will only receive data, and never transmit.</div>
|
||||||
|
</div>
|
||||||
|
</li>
|
||||||
|
<li><div class="line-block">
|
||||||
|
<div class="line">The <code class="docutils literal notranslate"><span class="pre">network_name</span></code> option sets the virtual network name for
|
||||||
|
the interface. This allows multiple separate network segments
|
||||||
|
to exist on the same physical channel or medium.</div>
|
||||||
|
</div>
|
||||||
|
</li>
|
||||||
|
<li><div class="line-block">
|
||||||
|
<div class="line">The <code class="docutils literal notranslate"><span class="pre">passphrase</span></code> option sets an authentication passphrase on
|
||||||
|
the interface. This option can be used in conjunction with the
|
||||||
|
<code class="docutils literal notranslate"><span class="pre">network_name</span></code> option, or be used alone.</div>
|
||||||
|
</div>
|
||||||
|
</li>
|
||||||
|
<li><div class="line-block">
|
||||||
|
<div class="line">The <code class="docutils literal notranslate"><span class="pre">ifac_size</span></code> option allows customising the length of the
|
||||||
|
Interface Authentication Codes carried by each packet on named
|
||||||
|
and/or authenticated network segments. It is set by default to
|
||||||
|
a size suitable for the interface in question, but can be set
|
||||||
|
to a custom size between 8 and 512 bits by using this option.
|
||||||
|
In normal usage, this option should not be changed from the
|
||||||
|
default.</div>
|
||||||
|
</div>
|
||||||
|
</li>
|
||||||
|
<li><div class="line-block">
|
||||||
|
<div class="line">The <code class="docutils literal notranslate"><span class="pre">announce_cap</span></code> option lets you configure the maximum
|
||||||
|
bandwidth to allocate, at any given time, to propagating
|
||||||
|
announces and other network upkeep traffic. It is configured at
|
||||||
|
2% by default, and should normally not need to be changed. Can
|
||||||
|
be set to any value between <code class="docutils literal notranslate"><span class="pre">1</span></code> and <code class="docutils literal notranslate"><span class="pre">100</span></code>.</div>
|
||||||
|
</div>
|
||||||
|
</li>
|
||||||
|
<li><div class="line-block">
|
||||||
|
<div class="line">The <code class="docutils literal notranslate"><span class="pre">bitrate</span></code> option configures the interface bitrate.
|
||||||
|
Reticulum will use interface speeds reported by hardware, or
|
||||||
|
try to guess a suitable rate when the hardware doesn’t report
|
||||||
|
any. In most cases, the automatically found rate should be
|
||||||
|
sufficient, but it can be configured by using the <code class="docutils literal notranslate"><span class="pre">bitrate</span></code>
|
||||||
|
option, to set the interface speed in <em>bits per second</em>.</div>
|
||||||
|
</div>
|
||||||
|
</li>
|
||||||
|
</ul>
|
||||||
|
</div></blockquote>
|
||||||
|
</div>
|
||||||
<div class="section" id="auto-interface">
|
<div class="section" id="auto-interface">
|
||||||
<span id="interfaces-auto"></span><h2>Auto Interface<a class="headerlink" href="#auto-interface" title="Permalink to this headline">¶</a></h2>
|
<span id="interfaces-auto"></span><h2>Auto Interface<a class="headerlink" href="#auto-interface" title="Permalink to this headline">¶</a></h2>
|
||||||
<p>The Auto Interface enables communication with other discoverable Reticulum
|
<p>The Auto Interface enables communication with other discoverable Reticulum
|
||||||
@ -485,36 +567,6 @@ beaconing functionality described above.</p>
|
|||||||
</pre></div>
|
</pre></div>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
<div class="section" id="common-interface-options">
|
|
||||||
<span id="interfaces-options"></span><h2>Common Interface Options<a class="headerlink" href="#common-interface-options" title="Permalink to this headline">¶</a></h2>
|
|
||||||
<p>A number of general options are available on most interfaces.
|
|
||||||
These can be used to control various aspects of interface behaviour.</p>
|
|
||||||
<p>The <code class="docutils literal notranslate"><span class="pre">enabled</span></code> option tells Reticulum whether or not
|
|
||||||
to bring up the interface. Defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>. For any
|
|
||||||
interface to be brought up, the <code class="docutils literal notranslate"><span class="pre">enabled</span></code> option
|
|
||||||
must be set to <code class="docutils literal notranslate"><span class="pre">True</span></code> or <code class="docutils literal notranslate"><span class="pre">Yes</span></code>.</p>
|
|
||||||
<p>The <code class="docutils literal notranslate"><span class="pre">outgoing</span></code> option sets whether an interface is allowed
|
|
||||||
to transmit. Defaults to <code class="docutils literal notranslate"><span class="pre">True</span></code>. If set to <code class="docutils literal notranslate"><span class="pre">False</span></code> or <code class="docutils literal notranslate"><span class="pre">No</span></code>
|
|
||||||
the interface will only receive data, and never transmit.</p>
|
|
||||||
<p>The <code class="docutils literal notranslate"><span class="pre">mode</span></code> option allows selecting the high-level behaviour
|
|
||||||
of the interface from a number of options.</p>
|
|
||||||
<blockquote>
|
|
||||||
<div><ul class="simple">
|
|
||||||
<li><p>The default value is <code class="docutils literal notranslate"><span class="pre">full</span></code>. In this mode, all discovery,
|
|
||||||
meshing and transport functionality is available.</p></li>
|
|
||||||
<li><p>In the <code class="docutils literal notranslate"><span class="pre">access_point</span></code> (or shorthand <code class="docutils literal notranslate"><span class="pre">ap</span></code>) mode, the
|
|
||||||
interface will operate as a network access point. In this
|
|
||||||
mode, announces will not be automatically broadcasted on
|
|
||||||
the interface, and paths to destinations on the interface
|
|
||||||
will have a much shorter expiry time. This mode is useful
|
|
||||||
for creating interfaces that are mostly quiet, unless when
|
|
||||||
someone is actually using them. An example of this could
|
|
||||||
be a radio interface serving a wide area, where users are
|
|
||||||
expected to connect momentarily, use the network, and then
|
|
||||||
disappear again.</p></li>
|
|
||||||
</ul>
|
|
||||||
</div></blockquote>
|
|
||||||
</div>
|
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
|
|
||||||
@ -527,6 +579,7 @@ disappear again.</p></li>
|
|||||||
<h3><a href="index.html">Table of Contents</a></h3>
|
<h3><a href="index.html">Table of Contents</a></h3>
|
||||||
<ul>
|
<ul>
|
||||||
<li><a class="reference internal" href="#">Supported Interfaces</a><ul>
|
<li><a class="reference internal" href="#">Supported Interfaces</a><ul>
|
||||||
|
<li><a class="reference internal" href="#common-interface-options">Common Interface Options</a></li>
|
||||||
<li><a class="reference internal" href="#auto-interface">Auto Interface</a></li>
|
<li><a class="reference internal" href="#auto-interface">Auto Interface</a></li>
|
||||||
<li><a class="reference internal" href="#i2p-interface">I2P Interface</a></li>
|
<li><a class="reference internal" href="#i2p-interface">I2P Interface</a></li>
|
||||||
<li><a class="reference internal" href="#tcp-server-interface">TCP Server Interface</a></li>
|
<li><a class="reference internal" href="#tcp-server-interface">TCP Server Interface</a></li>
|
||||||
@ -536,7 +589,6 @@ disappear again.</p></li>
|
|||||||
<li><a class="reference internal" href="#serial-interface">Serial Interface</a></li>
|
<li><a class="reference internal" href="#serial-interface">Serial Interface</a></li>
|
||||||
<li><a class="reference internal" href="#kiss-interface">KISS Interface</a></li>
|
<li><a class="reference internal" href="#kiss-interface">KISS Interface</a></li>
|
||||||
<li><a class="reference internal" href="#ax-25-kiss-interface">AX.25 KISS Interface</a></li>
|
<li><a class="reference internal" href="#ax-25-kiss-interface">AX.25 KISS Interface</a></li>
|
||||||
<li><a class="reference internal" href="#common-interface-options">Common Interface Options</a></li>
|
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
</ul>
|
</ul>
|
||||||
|
@ -70,6 +70,13 @@ also very useful when just a few devices needs to communicate.</div>
|
|||||||
</div>
|
</div>
|
||||||
</li>
|
</li>
|
||||||
<li><div class="line-block">
|
<li><div class="line-block">
|
||||||
|
<div class="line">Low-bandwidth networks, like LoRa and packet radio, can interoperate and
|
||||||
|
interconnect with much larger and higher bandwidth networks without issue.
|
||||||
|
Reticulum automatically manages the flow of information to and from various
|
||||||
|
network segments, and when bandwidth is limited, local traffic is prioritised.</div>
|
||||||
|
</div>
|
||||||
|
</li>
|
||||||
|
<li><div class="line-block">
|
||||||
<div class="line">Reticulum provides sender/initiator anonymity by default. There is no way
|
<div class="line">Reticulum provides sender/initiator anonymity by default. There is no way
|
||||||
to filter traffic or discriminate it based on the source of the traffic.</div>
|
to filter traffic or discriminate it based on the source of the traffic.</div>
|
||||||
</div>
|
</div>
|
||||||
@ -97,20 +104,38 @@ transport node. Letting every node be a transport node will in most cases
|
|||||||
degrade the performance and reliability of the network.</div>
|
degrade the performance and reliability of the network.</div>
|
||||||
</div>
|
</div>
|
||||||
<blockquote>
|
<blockquote>
|
||||||
<div><p>In general terms, if a node is stationary, well-connected and kept running
|
<div><p><em>In general terms, if a node is stationary, well-connected and kept running
|
||||||
most of the time, it is a good candidate to be a transport node. For optimal
|
most of the time, it is a good candidate to be a transport node. For optimal
|
||||||
performance, a network should contain the amount of transport nodes that
|
performance, a network should contain the amount of transport nodes that
|
||||||
provides connectivity to the intended area / topography, and not many more
|
provides connectivity to the intended area / topography, and not many more
|
||||||
than that.</p>
|
than that.</em></p>
|
||||||
</div></blockquote>
|
</div></blockquote>
|
||||||
</li>
|
</li>
|
||||||
|
<li><div class="line-block">
|
||||||
|
<div class="line">Reticulum is designed to work reliably in open, trustless environments. This
|
||||||
|
means you can use it to create open-access networks, where participants can
|
||||||
|
join and leave in an free and unorganised manner. This property allows an
|
||||||
|
entirely new, and so far, mostly unexplored class of networked applications,
|
||||||
|
where networks, and the information flow within them can form and dissolve
|
||||||
|
organically.</div>
|
||||||
|
</div>
|
||||||
|
</li>
|
||||||
|
<li><div class="line-block">
|
||||||
|
<div class="line">You can just as easily create closed networks, since Reticulum allows you to
|
||||||
|
add authentication to any interface. This means you can restrict access on
|
||||||
|
any interface type, even when using legacy devices, such as modems. You can
|
||||||
|
also mix authenticated and open interfaces on the same system. See the
|
||||||
|
<a class="reference internal" href="interfaces.html#interfaces-options"><span class="std std-ref">Common Interface Options</span></a> section of the <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Interfaces</span></a>
|
||||||
|
chapter of this manual for information on how to set up interface authentication.</div>
|
||||||
|
</div>
|
||||||
|
</li>
|
||||||
</ul>
|
</ul>
|
||||||
</div></blockquote>
|
</div></blockquote>
|
||||||
<p>Reticulum allows you to mix very different kinds of networking mediums into a
|
<p>Reticulum allows you to mix very different kinds of networking mediums into a
|
||||||
unified mesh, or to keep everything within one medium. You could build a “virtual
|
unified mesh, or to keep everything within one medium. You could build a “virtual
|
||||||
network” running entirely over the Internet, where all nodes communicate over TCP
|
network” running entirely over the Internet, where all nodes communicate over TCP
|
||||||
and UDP “channels”. You could also build such a network using MQTT or ZeroMQ as
|
and UDP “channels”. You could also build such a network using other already-established
|
||||||
the underlying carrier for Reticulum.</p>
|
communications channels as the underlying carrier for Reticulum.</p>
|
||||||
<p>However, most real-world networks will probably involve either some form of
|
<p>However, most real-world networks will probably involve either some form of
|
||||||
wireless or direct hardline communications. To allow Reticulum to communicate
|
wireless or direct hardline communications. To allow Reticulum to communicate
|
||||||
over any type of medium, you must specify it in the configuration file, by default
|
over any type of medium, you must specify it in the configuration file, by default
|
||||||
|
File diff suppressed because one or more lines are too long
@ -45,7 +45,8 @@
|
|||||||
<span id="using-main"></span><h1>Using Reticulum on Your System<a class="headerlink" href="#using-reticulum-on-your-system" title="Permalink to this headline">¶</a></h1>
|
<span id="using-main"></span><h1>Using Reticulum on Your System<a class="headerlink" href="#using-reticulum-on-your-system" title="Permalink to this headline">¶</a></h1>
|
||||||
<p>Reticulum is not installed as a driver or kernel module, as one might expect
|
<p>Reticulum is not installed as a driver or kernel module, as one might expect
|
||||||
of a networking stack. Instead, Reticulum is distributed as a Python module.
|
of a networking stack. Instead, Reticulum is distributed as a Python module.
|
||||||
This means that no special privileges are required to install or use it.
|
This means that no special privileges are required to install or use it. It
|
||||||
|
is also very light-weight, and easy to transfer to and install on new systems.
|
||||||
Any program or application that uses Reticulum will automatically load and
|
Any program or application that uses Reticulum will automatically load and
|
||||||
initialise Reticulum when it starts.</p>
|
initialise Reticulum when it starts.</p>
|
||||||
<p>In many cases, this approach is sufficient. When any program needs to use
|
<p>In many cases, this approach is sufficient. When any program needs to use
|
||||||
|
@ -324,3 +324,7 @@ for more information:
|
|||||||
* `Installing RNode Firmware on Compatible LoRa Devices <https://unsigned.io/installing-rnode-firmware-on-t-beam-and-lora32-devices/>`_
|
* `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/>`_
|
* `Private, Secure and Uncensorable Messaging Over a LoRa Mesh <https://unsigned.io/private-messaging-over-lora/>`_
|
||||||
* `RNode Firmware <https://github.com/markqvist/RNode_Firmware/>`_
|
* `RNode Firmware <https://github.com/markqvist/RNode_Firmware/>`_
|
||||||
|
|
||||||
|
If you have communications hardware that you think would be suitable for use with Reticulum,
|
||||||
|
you are welcome to head over to the `GitHub discussion pages <https://github.com/markqvist/Reticulum/discussions>`_
|
||||||
|
and propose adding an interface for the hardware.
|
@ -18,6 +18,72 @@ For a high-level overview of how networks can be formed over different interface
|
|||||||
types, have a look at the :ref:`Building Networks<networks-main>` chapter of this
|
types, have a look at the :ref:`Building Networks<networks-main>` chapter of this
|
||||||
manual.
|
manual.
|
||||||
|
|
||||||
|
|
||||||
|
.. _interfaces-options:
|
||||||
|
|
||||||
|
Common Interface Options
|
||||||
|
========================
|
||||||
|
|
||||||
|
A number of general configuration options are available on most interfaces.
|
||||||
|
These can be used to control various aspects of interface behaviour.
|
||||||
|
|
||||||
|
|
||||||
|
* | The ``enabled`` option tells Reticulum whether or not
|
||||||
|
to bring up the interface. Defaults to ``False``. For any
|
||||||
|
interface to be brought up, the ``enabled`` option
|
||||||
|
must be set to ``True`` or ``Yes``.
|
||||||
|
|
||||||
|
* | The ``mode`` option allows selecting the high-level behaviour
|
||||||
|
of the interface from a number of options.
|
||||||
|
|
||||||
|
- The default value is ``full``. In this mode, all discovery,
|
||||||
|
meshing and transport functionality is available.
|
||||||
|
|
||||||
|
- In the ``access_point`` (or shorthand ``ap``) mode, the
|
||||||
|
interface will operate as a network access point. In this
|
||||||
|
mode, announces will not be automatically broadcasted on
|
||||||
|
the interface, and paths to destinations on the interface
|
||||||
|
will have a much shorter expiry time. This mode is useful
|
||||||
|
for creating interfaces that are mostly quiet, unless when
|
||||||
|
someone is actually using them. An example of this could
|
||||||
|
be a radio interface serving a wide area, where users are
|
||||||
|
expected to connect momentarily, use the network, and then
|
||||||
|
disappear again.
|
||||||
|
|
||||||
|
* | The ``outgoing`` option sets whether an interface is allowed
|
||||||
|
to transmit. Defaults to ``True``. If set to ``False`` or ``No``
|
||||||
|
the interface will only receive data, and never transmit.
|
||||||
|
|
||||||
|
* | The ``network_name`` option sets the virtual network name for
|
||||||
|
the interface. This allows multiple separate network segments
|
||||||
|
to exist on the same physical channel or medium.
|
||||||
|
|
||||||
|
* | The ``passphrase`` option sets an authentication passphrase on
|
||||||
|
the interface. This option can be used in conjunction with the
|
||||||
|
``network_name`` option, or be used alone.
|
||||||
|
|
||||||
|
* | The ``ifac_size`` option allows customising the length of the
|
||||||
|
Interface Authentication Codes carried by each packet on named
|
||||||
|
and/or authenticated network segments. It is set by default to
|
||||||
|
a size suitable for the interface in question, but can be set
|
||||||
|
to a custom size between 8 and 512 bits by using this option.
|
||||||
|
In normal usage, this option should not be changed from the
|
||||||
|
default.
|
||||||
|
|
||||||
|
* | The ``announce_cap`` option lets you configure the maximum
|
||||||
|
bandwidth to allocate, at any given time, to propagating
|
||||||
|
announces and other network upkeep traffic. It is configured at
|
||||||
|
2% by default, and should normally not need to be changed. Can
|
||||||
|
be set to any value between ``1`` and ``100``.
|
||||||
|
|
||||||
|
* | The ``bitrate`` option configures the interface bitrate.
|
||||||
|
Reticulum will use interface speeds reported by hardware, or
|
||||||
|
try to guess a suitable rate when the hardware doesn't report
|
||||||
|
any. In most cases, the automatically found rate should be
|
||||||
|
sufficient, but it can be configured by using the ``bitrate``
|
||||||
|
option, to set the interface speed in *bits per second*.
|
||||||
|
|
||||||
|
|
||||||
.. _interfaces-auto:
|
.. _interfaces-auto:
|
||||||
|
|
||||||
Auto Interface
|
Auto Interface
|
||||||
@ -512,39 +578,3 @@ beaconing functionality described above.
|
|||||||
# This is useful for modems with a
|
# This is useful for modems with a
|
||||||
# small internal packet buffer.
|
# small internal packet buffer.
|
||||||
flow_control = false
|
flow_control = false
|
||||||
|
|
||||||
|
|
||||||
.. _interfaces-options:
|
|
||||||
|
|
||||||
Common Interface Options
|
|
||||||
========================
|
|
||||||
|
|
||||||
A number of general options are available on most interfaces.
|
|
||||||
These can be used to control various aspects of interface behaviour.
|
|
||||||
|
|
||||||
|
|
||||||
The ``enabled`` option tells Reticulum whether or not
|
|
||||||
to bring up the interface. Defaults to ``False``. For any
|
|
||||||
interface to be brought up, the ``enabled`` option
|
|
||||||
must be set to ``True`` or ``Yes``.
|
|
||||||
|
|
||||||
The ``outgoing`` option sets whether an interface is allowed
|
|
||||||
to transmit. Defaults to ``True``. If set to ``False`` or ``No``
|
|
||||||
the interface will only receive data, and never transmit.
|
|
||||||
|
|
||||||
The ``mode`` option allows selecting the high-level behaviour
|
|
||||||
of the interface from a number of options.
|
|
||||||
|
|
||||||
- The default value is ``full``. In this mode, all discovery,
|
|
||||||
meshing and transport functionality is available.
|
|
||||||
|
|
||||||
- In the ``access_point`` (or shorthand ``ap``) mode, the
|
|
||||||
interface will operate as a network access point. In this
|
|
||||||
mode, announces will not be automatically broadcasted on
|
|
||||||
the interface, and paths to destinations on the interface
|
|
||||||
will have a much shorter expiry time. This mode is useful
|
|
||||||
for creating interfaces that are mostly quiet, unless when
|
|
||||||
someone is actually using them. An example of this could
|
|
||||||
be a radio interface serving a wide area, where users are
|
|
||||||
expected to connect momentarily, use the network, and then
|
|
||||||
disappear again.
|
|
||||||
|
@ -27,6 +27,11 @@ with Reticulum:
|
|||||||
While the adress space can support billions of endpoints, Reticulum is
|
While the adress space can support billions of endpoints, Reticulum is
|
||||||
also very useful when just a few devices needs to communicate.
|
also very useful when just a few devices needs to communicate.
|
||||||
|
|
||||||
|
* | Low-bandwidth networks, like LoRa and packet radio, can interoperate and
|
||||||
|
interconnect with much larger and higher bandwidth networks without issue.
|
||||||
|
Reticulum automatically manages the flow of information to and from various
|
||||||
|
network segments, and when bandwidth is limited, local traffic is prioritised.
|
||||||
|
|
||||||
* | Reticulum provides sender/initiator anonymity by default. There is no way
|
* | Reticulum provides sender/initiator anonymity by default. There is no way
|
||||||
to filter traffic or discriminate it based on the source of the traffic.
|
to filter traffic or discriminate it based on the source of the traffic.
|
||||||
|
|
||||||
@ -47,18 +52,32 @@ with Reticulum:
|
|||||||
transport node. Letting every node be a transport node will in most cases
|
transport node. Letting every node be a transport node will in most cases
|
||||||
degrade the performance and reliability of the network.
|
degrade the performance and reliability of the network.
|
||||||
|
|
||||||
In general terms, if a node is stationary, well-connected and kept running
|
*In general terms, if a node is stationary, well-connected and kept running
|
||||||
most of the time, it is a good candidate to be a transport node. For optimal
|
most of the time, it is a good candidate to be a transport node. For optimal
|
||||||
performance, a network should contain the amount of transport nodes that
|
performance, a network should contain the amount of transport nodes that
|
||||||
provides connectivity to the intended area / topography, and not many more
|
provides connectivity to the intended area / topography, and not many more
|
||||||
than that.
|
than that.*
|
||||||
|
|
||||||
|
* | Reticulum is designed to work reliably in open, trustless environments. This
|
||||||
|
means you can use it to create open-access networks, where participants can
|
||||||
|
join and leave in an free and unorganised manner. This property allows an
|
||||||
|
entirely new, and so far, mostly unexplored class of networked applications,
|
||||||
|
where networks, and the information flow within them can form and dissolve
|
||||||
|
organically.
|
||||||
|
|
||||||
|
* | You can just as easily create closed networks, since Reticulum allows you to
|
||||||
|
add authentication to any interface. This means you can restrict access on
|
||||||
|
any interface type, even when using legacy devices, such as modems. You can
|
||||||
|
also mix authenticated and open interfaces on the same system. See the
|
||||||
|
:ref:`Common Interface Options<interfaces-options>` section of the :ref:`Interfaces<interfaces-main>`
|
||||||
|
chapter of this manual for information on how to set up interface authentication.
|
||||||
|
|
||||||
|
|
||||||
Reticulum allows you to mix very different kinds of networking mediums into a
|
Reticulum allows you to mix very different kinds of networking mediums into a
|
||||||
unified mesh, or to keep everything within one medium. You could build a "virtual
|
unified mesh, or to keep everything within one medium. You could build a "virtual
|
||||||
network" running entirely over the Internet, where all nodes communicate over TCP
|
network" running entirely over the Internet, where all nodes communicate over TCP
|
||||||
and UDP "channels". You could also build such a network using MQTT or ZeroMQ as
|
and UDP "channels". You could also build such a network using other already-established
|
||||||
the underlying carrier for Reticulum.
|
communications channels as the underlying carrier for Reticulum.
|
||||||
|
|
||||||
However, most real-world networks will probably involve either some form of
|
However, most real-world networks will probably involve either some form of
|
||||||
wireless or direct hardline communications. To allow Reticulum to communicate
|
wireless or direct hardline communications. To allow Reticulum to communicate
|
||||||
|
@ -6,7 +6,8 @@ Using Reticulum on Your System
|
|||||||
|
|
||||||
Reticulum is not installed as a driver or kernel module, as one might expect
|
Reticulum is not installed as a driver or kernel module, as one might expect
|
||||||
of a networking stack. Instead, Reticulum is distributed as a Python module.
|
of a networking stack. Instead, Reticulum is distributed as a Python module.
|
||||||
This means that no special privileges are required to install or use it.
|
This means that no special privileges are required to install or use it. It
|
||||||
|
is also very light-weight, and easy to transfer to and install on new systems.
|
||||||
Any program or application that uses Reticulum will automatically load and
|
Any program or application that uses Reticulum will automatically load and
|
||||||
initialise Reticulum when it starts.
|
initialise Reticulum when it starts.
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user