Updated documentation

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

View File

@ -634,25 +634,51 @@ Interface Modes
The optional ``mode`` setting is available on all interfaces, and allows
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
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
when building or connecting to more complex networks. When not running a
Transport Node, it is rarely useful to configure an interface mode.
Configuring modes on interfaces is **not** strictly necessary, but can be useful
when building or connecting to more complex networks. If your Reticulum
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.
* | 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
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 remain 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.
will have a much shorter expiry time. In addition, path
requests from clients on the access point interface will
be handled in the same way as the ``gateway`` interface.
| 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.
* | The ``roaming`` mode should be used on interfaces that are
roaming (physically mobile), seen from the perspective of

View File

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

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
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
are propagated and how long paths are valid.</p>
<p>Configuring modes on interfaces is not strictly necessary, but can be useful
when building or connecting to more complex networks. When not running a
Transport Node, it is rarely useful to configure an interface mode.</p>
are propagated, how long paths are valid and how paths are discovered.</p>
<p>Configuring modes on interfaces is <strong>not</strong> strictly necessary, but can be useful
when building or connecting to more complex networks. If your Reticulum
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>
<div><ul>
<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>
</div>
</li>
<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
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 remain 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.</div>
will have a much shorter expiry time. In addition, path
requests from clients on the access point interface will
be handled in the same way as the <code class="docutils literal notranslate"><span class="pre">gateway</span></code> interface.</div>
</div>
<div class="line-block">
<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>
</li>
<li><div class="line-block">

File diff suppressed because one or more lines are too long

View File

@ -861,10 +861,11 @@ but excluding any interface access codes.
<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>
<p>The following table illustrates the rules for automatically propagating announces
from one interface type to another, for all possible combinations. 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>
from one interface type to another, for all possible combinations. For the purpose
of announce propagation, the <em>Full</em> and <em>Gateway</em> modes are identical.</p>
<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>

View File

@ -634,25 +634,51 @@ Interface Modes
The optional ``mode`` setting is available on all interfaces, and allows
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
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
when building or connecting to more complex networks. When not running a
Transport Node, it is rarely useful to configure an interface mode.
Configuring modes on interfaces is **not** strictly necessary, but can be useful
when building or connecting to more complex networks. If your Reticulum
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.
* | 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
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 remain 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.
will have a much shorter expiry time. In addition, path
requests from clients on the access point interface will
be handled in the same way as the ``gateway`` interface.
| 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.
* | The ``roaming`` mode should be used on interfaces that are
roaming (physically mobile), seen from the perspective of

View File

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