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

Updated documentation

Browse Source
This commit is contained in:
Mark Qvist 2022-05-22 15:17:25 +02:00
parent 44ba5624bc
commit e4871f7667
7 changed files with 131 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
docs/manual/_sources/interfaces.rst.txt
View File

@ -634,25 +634,51 @@ Interface Modes
The optional ``mode`` setting is available on all interfaces, and allows The optional ``mode`` setting is available on all interfaces, and allows
selecting the high-level behaviour of the interface from a number of modes. selecting the high-level behaviour of the interface from a number of modes.
These modes affect how Reticulum selects paths in the network, how announces These modes affect how Reticulum selects paths in the network, how announces
are propagated and how long paths are valid. are propagated, how long paths are valid and how paths are discovered.
Configuring modes on interfaces is not strictly necessary, but can be useful Configuring modes on interfaces is **not** strictly necessary, but can be useful
when building or connecting to more complex networks. When not running a when building or connecting to more complex networks. If your Reticulum
Transport Node, it is rarely useful to configure an interface mode. instance is not running a Transport Node, it is rarely useful to configure
interface modes, and in such cases interfaces should generally be left in
the default mode.
* | The default value is ``full``. In this mode, all discovery, * | The default mode is ``full``. In this mode, all discovery,
meshing and transport functionality is activated. meshing and transport functionality is activated.
* | The ``gateway`` mode (or shorthand ``gw``) also has all
discovery, meshing and transport functionality available,
but will additionally try to discover unknown paths on
behalf of other nodes residing on the ``gateway`` interface.
If Reticulum receives a path request for an unknown
destination, from a node on a ``gateway`` interface, it
will try to discover this path via all other active interfaces,
and forward the discovered path to the requestor if one is
found.
| If you want to allow other nodes to widely resolve paths or connect
to a network via an interface, it might be useful to put it in this
mode. By creating a chain of ``gateway`` interfaces, other
nodes will be able to immediately discover paths to any
destination along the chain.
| *Please note!* It is the interface *facing the clients* that
must be put into ``gateway`` mode for this to work, not
the interface facing the wider network (for this, the ``boundary``
mode can be useful, though).
* | In the ``access_point`` (or shorthand ``ap``) mode, the * | In the ``access_point`` (or shorthand ``ap``) mode, the
interface will operate as a network access point. In this interface will operate as a network access point. In this
mode, announces will not be automatically broadcasted on mode, announces will not be automatically broadcasted on
the interface, and paths to destinations on the interface the interface, and paths to destinations on the interface
will have a much shorter expiry time. This mode is useful will have a much shorter expiry time. In addition, path
for creating interfaces that remain quiet, unless when requests from clients on the access point interface will
someone is actually using them. An example of this could be handled in the same way as the ``gateway`` interface.
be a radio interface serving a wide area, where users are
expected to connect momentarily, use the network, and then | This mode is useful for creating interfaces that remain
disappear again. quiet, until someone actually starts 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 ``roaming`` mode should be used on interfaces that are * | The ``roaming`` mode should be used on interfaces that are
roaming (physically mobile), seen from the perspective of roaming (physically mobile), seen from the perspective of

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

@ -809,12 +809,14 @@ Announce Propagation Rules
-------------------------- --------------------------
The following table illustrates the rules for automatically propagating announces The following table illustrates the rules for automatically propagating announces
from one interface type to another, for all possible combinations. See the from one interface type to another, for all possible combinations. For the purpose
:ref:`Interface Modes<interfaces-modes>` section for a conceptual overview of the of announce propagation, the *Full* and *Gateway* modes are identical.
different interface modes, and how they are configured.
.. image:: graphics/if_mode_graph_b.png .. image:: graphics/if_mode_graph_b.png
See the :ref:`Interface Modes<interfaces-modes>` section for a conceptual overview
of the different interface modes, and how they are configured.
.. ..
(.. code-block:: text) (.. code-block:: text)
Full ────── ✓ ──┐ ┌── ✓ ── Full Full ────── ✓ ──┐ ┌── ✓ ── Full

53
docs/manual/interfaces.html
View File

@ -611,28 +611,59 @@ option, to set the interface speed in <em>bits per second</em>.</div>
<p>The optional <code class="docutils literal notranslate"><span class="pre">mode</span></code> setting is available on all interfaces, and allows <p>The optional <code class="docutils literal notranslate"><span class="pre">mode</span></code> setting is available on all interfaces, and allows
selecting the high-level behaviour of the interface from a number of modes. selecting the high-level behaviour of the interface from a number of modes.
These modes affect how Reticulum selects paths in the network, how announces These modes affect how Reticulum selects paths in the network, how announces
are propagated and how long paths are valid.</p> are propagated, how long paths are valid and how paths are discovered.</p>
<p>Configuring modes on interfaces is not strictly necessary, but can be useful <p>Configuring modes on interfaces is <strong>not</strong> strictly necessary, but can be useful
when building or connecting to more complex networks. When not running a when building or connecting to more complex networks. If your Reticulum
Transport Node, it is rarely useful to configure an interface mode.</p> instance is not running a Transport Node, it is rarely useful to configure
interface modes, and in such cases interfaces should generally be left in
the default mode.</p>
<blockquote> <blockquote>
<div><ul> <div><ul>
<li><div class="line-block"> <li><div class="line-block">
<div class="line">The default value is <code class="docutils literal notranslate"><span class="pre">full</span></code>. In this mode, all discovery, <div class="line">The default mode is <code class="docutils literal notranslate"><span class="pre">full</span></code>. In this mode, all discovery,
meshing and transport functionality is activated.</div> meshing and transport functionality is activated.</div>
</div> </div>
</li> </li>
<li><div class="line-block"> <li><div class="line-block">
<div class="line">The <code class="docutils literal notranslate"><span class="pre">gateway</span></code> mode (or shorthand <code class="docutils literal notranslate"><span class="pre">gw</span></code>) also has all
discovery, meshing and transport functionality available,
but will additionally try to discover unknown paths on
behalf of other nodes residing on the <code class="docutils literal notranslate"><span class="pre">gateway</span></code> interface.
If Reticulum receives a path request for an unknown
destination, from a node on a <code class="docutils literal notranslate"><span class="pre">gateway</span></code> interface, it
will try to discover this path via all other active interfaces,
and forward the discovered path to the requestor if one is
found.</div>
</div>
<div class="line-block">
<div class="line">If you want to allow other nodes to widely resolve paths or connect
to a network via an interface, it might be useful to put it in this
mode. By creating a chain of <code class="docutils literal notranslate"><span class="pre">gateway</span></code> interfaces, other
nodes will be able to immediately discover paths to any
destination along the chain.</div>
</div>
<div class="line-block">
<div class="line"><em>Please note!</em> It is the interface <em>facing the clients</em> that
must be put into <code class="docutils literal notranslate"><span class="pre">gateway</span></code> mode for this to work, not
the interface facing the wider network (for this, the <code class="docutils literal notranslate"><span class="pre">boundary</span></code>
mode can be useful, though).</div>
</div>
</li>
<li><div class="line-block">
<div class="line">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 <div class="line">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 interface will operate as a network access point. In this
mode, announces will not be automatically broadcasted on mode, announces will not be automatically broadcasted on
the interface, and paths to destinations on the interface the interface, and paths to destinations on the interface
will have a much shorter expiry time. This mode is useful will have a much shorter expiry time. In addition, path
for creating interfaces that remain quiet, unless when requests from clients on the access point interface will
someone is actually using them. An example of this could be handled in the same way as the <code class="docutils literal notranslate"><span class="pre">gateway</span></code> interface.</div>
be a radio interface serving a wide area, where users are </div>
expected to connect momentarily, use the network, and then <div class="line-block">
disappear again.</div> <div class="line">This mode is useful for creating interfaces that remain
quiet, until someone actually starts 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.</div>
</div> </div>
</li> </li>
<li><div class="line-block"> <li><div class="line-block">

2
docs/manual/searchindex.js
View File

File diff suppressed because one or more lines are too long

7
docs/manual/understanding.html
View File

@ -861,10 +861,11 @@ but excluding any interface access codes.
<div class="section" id="announce-propagation-rules"> <div class="section" id="announce-propagation-rules">
<span id="understanding-announcepropagation"></span><h3>Announce Propagation Rules<a class="headerlink" href="#announce-propagation-rules" title="Permalink to this headline"></a></h3> <span id="understanding-announcepropagation"></span><h3>Announce Propagation Rules<a class="headerlink" href="#announce-propagation-rules" title="Permalink to this headline"></a></h3>
<p>The following table illustrates the rules for automatically propagating announces <p>The following table illustrates the rules for automatically propagating announces
from one interface type to another, for all possible combinations. See the from one interface type to another, for all possible combinations. For the purpose
<a class="reference internal" href="interfaces.html#interfaces-modes"><span class="std std-ref">Interface Modes</span></a> section for a conceptual overview of the of announce propagation, the <em>Full</em> and <em>Gateway</em> modes are identical.</p>
different interface modes, and how they are configured.</p>
<img alt="_images/if_mode_graph_b.png" src="_images/if_mode_graph_b.png" /> <img alt="_images/if_mode_graph_b.png" src="_images/if_mode_graph_b.png" />
<p>See the <a class="reference internal" href="interfaces.html#interfaces-modes"><span class="std std-ref">Interface Modes</span></a> section for a conceptual overview
of the different interface modes, and how they are configured.</p>
</div> </div>
</div> </div>
</div> </div>

48
docs/source/interfaces.rst
View File

@ -634,25 +634,51 @@ Interface Modes
The optional ``mode`` setting is available on all interfaces, and allows The optional ``mode`` setting is available on all interfaces, and allows
selecting the high-level behaviour of the interface from a number of modes. selecting the high-level behaviour of the interface from a number of modes.
These modes affect how Reticulum selects paths in the network, how announces These modes affect how Reticulum selects paths in the network, how announces
are propagated and how long paths are valid. are propagated, how long paths are valid and how paths are discovered.
Configuring modes on interfaces is not strictly necessary, but can be useful Configuring modes on interfaces is **not** strictly necessary, but can be useful
when building or connecting to more complex networks. When not running a when building or connecting to more complex networks. If your Reticulum
Transport Node, it is rarely useful to configure an interface mode. instance is not running a Transport Node, it is rarely useful to configure
interface modes, and in such cases interfaces should generally be left in
the default mode.
* | The default value is ``full``. In this mode, all discovery, * | The default mode is ``full``. In this mode, all discovery,
meshing and transport functionality is activated. meshing and transport functionality is activated.
* | The ``gateway`` mode (or shorthand ``gw``) also has all
discovery, meshing and transport functionality available,
but will additionally try to discover unknown paths on
behalf of other nodes residing on the ``gateway`` interface.
If Reticulum receives a path request for an unknown
destination, from a node on a ``gateway`` interface, it
will try to discover this path via all other active interfaces,
and forward the discovered path to the requestor if one is
found.
| If you want to allow other nodes to widely resolve paths or connect
to a network via an interface, it might be useful to put it in this
mode. By creating a chain of ``gateway`` interfaces, other
nodes will be able to immediately discover paths to any
destination along the chain.
| *Please note!* It is the interface *facing the clients* that
must be put into ``gateway`` mode for this to work, not
the interface facing the wider network (for this, the ``boundary``
mode can be useful, though).
* | In the ``access_point`` (or shorthand ``ap``) mode, the * | In the ``access_point`` (or shorthand ``ap``) mode, the
interface will operate as a network access point. In this interface will operate as a network access point. In this
mode, announces will not be automatically broadcasted on mode, announces will not be automatically broadcasted on
the interface, and paths to destinations on the interface the interface, and paths to destinations on the interface
will have a much shorter expiry time. This mode is useful will have a much shorter expiry time. In addition, path
for creating interfaces that remain quiet, unless when requests from clients on the access point interface will
someone is actually using them. An example of this could be handled in the same way as the ``gateway`` interface.
be a radio interface serving a wide area, where users are
expected to connect momentarily, use the network, and then | This mode is useful for creating interfaces that remain
disappear again. quiet, until someone actually starts 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 ``roaming`` mode should be used on interfaces that are * | The ``roaming`` mode should be used on interfaces that are
roaming (physically mobile), seen from the perspective of roaming (physically mobile), seen from the perspective of

8
docs/source/understanding.rst
View File

@ -809,12 +809,14 @@ Announce Propagation Rules
-------------------------- --------------------------
The following table illustrates the rules for automatically propagating announces The following table illustrates the rules for automatically propagating announces
from one interface type to another, for all possible combinations. See the from one interface type to another, for all possible combinations. For the purpose
:ref:`Interface Modes<interfaces-modes>` section for a conceptual overview of the of announce propagation, the *Full* and *Gateway* modes are identical.
different interface modes, and how they are configured.
.. image:: graphics/if_mode_graph_b.png .. image:: graphics/if_mode_graph_b.png
See the :ref:`Interface Modes<interfaces-modes>` section for a conceptual overview
of the different interface modes, and how they are configured.
.. ..
(.. code-block:: text) (.. code-block:: text)
Full ────── ✓ ──┐ ┌── ✓ ── Full Full ────── ✓ ──┐ ┌── ✓ ── Full