mirror of
https://github.com/markqvist/Reticulum.git
synced 2024-12-24 23:19:36 -05:00
Updated documentation
This commit is contained in:
Mark Qvist
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/>`_
|
||||
* `Private, Secure and Uncensorable Messaging Over a LoRa Mesh <https://unsigned.io/private-messaging-over-lora/>`_
|
||||
* `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
|
||||
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:
|
||||
|
||||
Auto Interface
|
||||
@ -512,39 +578,3 @@ beaconing functionality described above.
|
||||
# This is useful for modems with a
|
||||
# small internal packet buffer.
|
||||
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
|
||||
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
|
||||
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
|
||||
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
|
||||
performance, a network should contain the amount of transport nodes that
|
||||
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
|
||||
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
|
||||
and UDP "channels". You could also build such a network using MQTT or ZeroMQ as
|
||||
the underlying carrier for Reticulum.
|
||||
and UDP "channels". You could also build such a network using other already-established
|
||||
communications channels as the underlying carrier for Reticulum.
|
||||
|
||||
However, most real-world networks will probably involve either some form of
|
||||
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
|
||||
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
|
||||
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://github.com/markqvist/RNode_Firmware/">RNode Firmware</a></p></li>
|
||||
</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>
|
||||
|
||||
|
||||
@ -95,6 +95,7 @@ to participate in the development of Reticulum itself.</p>
|
||||
</ul>
|
||||
</li>
|
||||
<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#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>
|
||||
@ -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#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#common-interface-options">Common Interface Options</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<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
|
||||
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>
|
||||
<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">
|
||||
<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
|
||||
@ -485,36 +567,6 @@ beaconing functionality described above.</p>
|
||||
</pre></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>
|
||||
|
||||
|
||||
@ -527,6 +579,7 @@ disappear again.</p></li>
|
||||
<h3><a href="index.html">Table of Contents</a></h3>
|
||||
<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="#i2p-interface">I2P 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="#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="#common-interface-options">Common Interface Options</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
@ -70,6 +70,13 @@ also very useful when just a few devices needs to communicate.</div>
|
||||
</div>
|
||||
</li>
|
||||
<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
|
||||
to filter traffic or discriminate it based on the source of the traffic.</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>
|
||||
</div>
|
||||
<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
|
||||
performance, a network should contain the amount of transport nodes that
|
||||
provides connectivity to the intended area / topography, and not many more
|
||||
than that.</p>
|
||||
than that.</em></p>
|
||||
</div></blockquote>
|
||||
</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>
|
||||
</div></blockquote>
|
||||
<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
|
||||
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
|
||||
the underlying carrier for Reticulum.</p>
|
||||
and UDP “channels”. You could also build such a network using other already-established
|
||||
communications channels as the underlying carrier for Reticulum.</p>
|
||||
<p>However, most real-world networks will probably involve either some form of
|
||||
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
|
||||
|
||||
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>
|
||||
<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.
|
||||
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
|
||||
initialise Reticulum when it starts.</p>
|
||||
<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/>`_
|
||||
* `Private, Secure and Uncensorable Messaging Over a LoRa Mesh <https://unsigned.io/private-messaging-over-lora/>`_
|
||||
* `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
|
||||
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:
|
||||
|
||||
Auto Interface
|
||||
@ -512,39 +578,3 @@ beaconing functionality described above.
|
||||
# This is useful for modems with a
|
||||
# small internal packet buffer.
|
||||
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
|
||||
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
|
||||
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
|
||||
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
|
||||
performance, a network should contain the amount of transport nodes that
|
||||
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
|
||||
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
|
||||
and UDP "channels". You could also build such a network using MQTT or ZeroMQ as
|
||||
the underlying carrier for Reticulum.
|
||||
and UDP "channels". You could also build such a network using other already-established
|
||||
communications channels as the underlying carrier for Reticulum.
|
||||
|
||||
However, most real-world networks will probably involve either some form of
|
||||
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
|
||||
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
|
||||
initialise Reticulum when it starts.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user