mirror of
https://github.com/markqvist/Reticulum.git
synced 2024-11-05 05:40:14 +00:00
Updated manual and documentation
This commit is contained in:
parent
b2d61843d0
commit
2b43436f56
Binary file not shown.
BIN
docs/manual/_images/if_mode_graph.png
Normal file
BIN
docs/manual/_images/if_mode_graph.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 46 KiB |
BIN
docs/manual/_images/if_mode_graph_b.png
Normal file
BIN
docs/manual/_images/if_mode_graph_b.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 25 KiB |
@ -19,125 +19,6 @@ types, have a look at the :ref:`Building Networks<networks-main>` chapter of thi
|
||||
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-modes:
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
* | The default value is ``full``. In this mode, all discovery,
|
||||
meshing and transport functionality is activated.
|
||||
|
||||
* | 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.
|
||||
|
||||
* | The ``roaming`` mode should be used on interfaces that are
|
||||
roaming (physically mobile), seen from the perspective of
|
||||
other nodes in the network. As an example, if a vehicle is
|
||||
equipped with an external LoRa interface, and an internal,
|
||||
WiFi-based interface, that serves devices that are moving
|
||||
_with_ the vehicle, the external LoRa interface should be
|
||||
configured as ``roaming``, and the internal interface can
|
||||
be left in the default mode. With transport enabled, such
|
||||
a setup will allow all internal devices to reach each other,
|
||||
and all other devices that are available on the LoRa side
|
||||
of the network, when they are in range. Devices on the LoRa
|
||||
side of the network will also be able to reach devices
|
||||
internal to the vehicle, when it is in range. Paths via
|
||||
``roaming`` interfaces also expire faster.
|
||||
|
||||
* | The purpose of the ``boundary`` mode is to specify interfaces
|
||||
that establish connectivity with network segments that are
|
||||
significantly different than the one this node exists on.
|
||||
As an example, if a Reticulum instance is part of a LoRa-based
|
||||
network, but also has a high-speed connection to a
|
||||
public Transport Node available on the Internet, the interface
|
||||
connecting over the Internet should be set to ``boundary`` mode.
|
||||
|
||||
For a table describing the impact of all modes on announce propagation,
|
||||
please see the :ref:`Announce Propagation Rules<understanding-announcepropagation>` section.
|
||||
|
||||
.. _interfaces-auto:
|
||||
|
||||
Auto Interface
|
||||
@ -664,3 +545,182 @@ 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 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``.
|
||||
|
||||
*If an interface exceeds its announce cap, it will queue announces
|
||||
for later transmission. Reticulum will always prioritise propagating
|
||||
announces from nearby nodes first. This ensures that the local
|
||||
topology is prioritised, and that slow networks are not overwhelmed
|
||||
by interconnected fast networks.*
|
||||
|
||||
*Destinations that are rapidly re-announcing will be down-prioritised
|
||||
further. Trying to get "first-in-line" by announce spamming will have
|
||||
the exact opposite effect: Getting moved to the back of the queue every
|
||||
time a new announce from the excessively announcing destination is received.*
|
||||
|
||||
*This means that it is always beneficial to select a balanced
|
||||
announce rate, and not announce more often than is actually necesarry
|
||||
for your application to function.*
|
||||
|
||||
* | 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-modes:
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
* | The default value is ``full``. In this mode, all discovery,
|
||||
meshing and transport functionality is activated.
|
||||
|
||||
* | 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.
|
||||
|
||||
* | The ``roaming`` mode should be used on interfaces that are
|
||||
roaming (physically mobile), seen from the perspective of
|
||||
other nodes in the network. As an example, if a vehicle is
|
||||
equipped with an external LoRa interface, and an internal,
|
||||
WiFi-based interface, that serves devices that are moving
|
||||
_with_ the vehicle, the external LoRa interface should be
|
||||
configured as ``roaming``, and the internal interface can
|
||||
be left in the default mode. With transport enabled, such
|
||||
a setup will allow all internal devices to reach each other,
|
||||
and all other devices that are available on the LoRa side
|
||||
of the network, when they are in range. Devices on the LoRa
|
||||
side of the network will also be able to reach devices
|
||||
internal to the vehicle, when it is in range. Paths via
|
||||
``roaming`` interfaces also expire faster.
|
||||
|
||||
* | The purpose of the ``boundary`` mode is to specify interfaces
|
||||
that establish connectivity with network segments that are
|
||||
significantly different than the one this node exists on.
|
||||
As an example, if a Reticulum instance is part of a LoRa-based
|
||||
network, but also has a high-speed connection to a
|
||||
public Transport Node available on the Internet, the interface
|
||||
connecting over the Internet should be set to ``boundary`` mode.
|
||||
|
||||
For a table describing the impact of all modes on announce propagation,
|
||||
please see the :ref:`Announce Propagation Rules<understanding-announcepropagation>` section.
|
||||
|
||||
.. _interfaces-announcerates:
|
||||
|
||||
Announce Rate Control
|
||||
=====================
|
||||
|
||||
The built-in announce control mechanisms and the default ``announce_cap``
|
||||
option described above are sufficient most of the time, but in some cases, especially on fast
|
||||
interfaces, it may be useful to control the target announce rate. Using the
|
||||
``announce_rate_target``, ``announce_rate_grace`` and ``announce_rate_penalty``
|
||||
options, this can be done on a per-interface basis, and moderates the *rate at
|
||||
which received announces are re-broadcasted to other interfaces*.
|
||||
|
||||
* | The ``announce_rate_target`` option sets the minimum amount of time,
|
||||
in seconds, that should pass between received announces, for any one
|
||||
destination. As an example, setting this value to ``3600`` means that
|
||||
announces *received* on this interface will only be re-transmitted and
|
||||
propagated to other interfaces once every hour, no matter how often they
|
||||
are received.
|
||||
|
||||
* | The optional ``announce_rate_grace`` defines the number of times a destination
|
||||
can violate the announce rate before the target rate is enforced.
|
||||
|
||||
* | The optional ``announce_rate_penalty`` configures an extra amount of
|
||||
time that is added to the normal rate target. As an example, if a penalty
|
||||
of ``7200`` seconds is defined, once the rate target is enforced, the
|
||||
destination in question will only have its announces propagated every
|
||||
3 hours, until it lowers its actual announce rate to within the target.
|
||||
|
||||
These mechanisms, in conjunction with the ``annouce_cap`` mechanisms mentioned
|
||||
above means that it is essential to select a balanced announce strategy for
|
||||
your destinations. The more balanced you can make this decision, the easier
|
||||
it will be for your destinations to make it into slower networks that many hops
|
||||
away. Or you can prioritise only reaching high-capacity networks with more frequent
|
||||
announces.
|
||||
|
||||
Current statistics and information about announce rates can be viewed using the
|
||||
``rnpath -r`` command.
|
||||
|
||||
It is important to note that there is no one right or wrong way to set up announce
|
||||
rates. Slower networks will naturally tend towards using less frequent announces to
|
||||
conserve bandwidth, while very fast networks can support applications that
|
||||
need very frequent announces. Reticulum implements these mechanisms to ensure
|
||||
that a large span of network types can seamlessly *co-exist* and interconnect.
|
||||
|
||||
|
@ -813,8 +813,10 @@ 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.
|
||||
|
||||
.. code-block:: text
|
||||
.. image:: graphics/if_mode_graph_b.png
|
||||
|
||||
..
|
||||
(.. code-block:: text)
|
||||
Full ────── ✓ ──┐ ┌── ✓ ── Full
|
||||
AP ──────── ✓ ──┼───> Full >───┼── ✕ ── AP
|
||||
Boundary ── ✓ ──┤ ├── ✓ ── Boundary
|
||||
@ -835,4 +837,3 @@ different interface modes, and how they are configured.
|
||||
Boundary ── ✓ ──┤ ├── ✓ ── Boundary
|
||||
Roaming ─── ✕ ──┘ └── ✕ ── Roaming
|
||||
|
||||
|
||||
|
@ -19,6 +19,122 @@ instance is simply shared. This works for any number of programs running
|
||||
concurrently, and is very easy to use, but depending on your use case, there
|
||||
are other options.
|
||||
|
||||
Configuration & Data
|
||||
--------------------
|
||||
|
||||
A Reticulum stores all information that it needs to function in a single file-
|
||||
system directory. By default, this directory is ``~/.reticulum``, but you can
|
||||
use any directory you wish. You can also run multiple separate Reticulum
|
||||
instances on the same physical system, in complete isolation from each other,
|
||||
or connected together.
|
||||
|
||||
In most cases, a single physical system will only need to run one Reticulum
|
||||
instance. This can either be launched at boot, as a system service, or simply
|
||||
be brought up when a program needs it. In either case, any number of programs
|
||||
running on the same system will automatically share the same Reticulum instance,
|
||||
if the configuration allows for it, which it does by default.
|
||||
|
||||
The entire configuration of Reticulum is found in the ``~/.reticulum/config``
|
||||
file. When Reticulum is first started on a new system, a basic, functional
|
||||
configuration file is created. The default configuration looks like this:
|
||||
|
||||
.. code::
|
||||
|
||||
# This is the default Reticulum config file.
|
||||
# You should probably edit it to include any additional,
|
||||
# interfaces and settings you might need.
|
||||
|
||||
# Only the most basic options are included in this default
|
||||
# configuration. To see a more verbose, and much longer,
|
||||
# configuration example, you can run the command:
|
||||
# rnsd --exampleconfig
|
||||
|
||||
|
||||
[reticulum]
|
||||
|
||||
# If you enable Transport, your system will route traffic
|
||||
# for other peers, pass announces and serve path requests.
|
||||
# This should only be done for systems that are suited to
|
||||
# act as transport nodes, ie. if they are stationary and
|
||||
# always-on. This directive is optional and can be removed
|
||||
# for brevity.
|
||||
|
||||
enable_transport = False
|
||||
|
||||
|
||||
# By default, the first program to launch the Reticulum
|
||||
# Network Stack will create a shared instance, that other
|
||||
# programs can communicate with. Only the shared instance
|
||||
# opens all the configured interfaces directly, and other
|
||||
# local programs communicate with the shared instance over
|
||||
# a local socket. This is completely transparent to the
|
||||
# user, and should generally be turned on. This directive
|
||||
# is optional and can be removed for brevity.
|
||||
|
||||
share_instance = Yes
|
||||
|
||||
|
||||
# If you want to run multiple *different* shared instances
|
||||
# on the same system, you will need to specify different
|
||||
# shared instance ports for each. The defaults are given
|
||||
# below, and again, these options can be left out if you
|
||||
# don't need them.
|
||||
|
||||
shared_instance_port = 37428
|
||||
instance_control_port = 37429
|
||||
|
||||
|
||||
# You can configure Reticulum to panic and forcibly close
|
||||
# if an unrecoverable interface error occurs, such as the
|
||||
# hardware device for an interface disappearing. This is
|
||||
# an optional directive, and can be left out for brevity.
|
||||
# This behaviour is disabled by default.
|
||||
|
||||
panic_on_interface_error = No
|
||||
|
||||
|
||||
[logging]
|
||||
# Valid log levels are 0 through 7:
|
||||
# 0: Log only critical information
|
||||
# 1: Log errors and lower log levels
|
||||
# 2: Log warnings and lower log levels
|
||||
# 3: Log notices and lower log levels
|
||||
# 4: Log info and lower (this is the default)
|
||||
# 5: Verbose logging
|
||||
# 6: Debug logging
|
||||
# 7: Extreme logging
|
||||
|
||||
loglevel = 4
|
||||
|
||||
|
||||
# The interfaces section defines the physical and virtual
|
||||
# interfaces Reticulum will use to communicate on. This
|
||||
# section will contain examples for a variety of interface
|
||||
# types. You can modify these or use them as a basis for
|
||||
# your own config, or simply remove the unused ones.
|
||||
|
||||
[interfaces]
|
||||
|
||||
# This interface enables communication with other
|
||||
# link-local Reticulum nodes over UDP. It does not
|
||||
# need any functional IP infrastructure like routers
|
||||
# or DHCP servers, but will require that at least link-
|
||||
# local IPv6 is enabled in your operating system, which
|
||||
# should be enabled by default in almost any OS. See
|
||||
# the Reticulum Manual for more configuration options.
|
||||
|
||||
[[Default Interface]]
|
||||
type = AutoInterface
|
||||
interface_enabled = True
|
||||
|
||||
If Reticulum infrastructure already exists locally, you probably don't need to
|
||||
change anything, and you may already be connected to a wider network. If not,
|
||||
you will probably need to add relevant *interfaces* to the configuration, in
|
||||
order to communicate with other systems. It is a good idea to read the comments
|
||||
and explanations in the above default config. It will teach you the basic
|
||||
concepts you need to understand to configure your network. Once you have done that,
|
||||
take a look at the :ref:`Interfaces<interfaces-main>` chapter of this manual.
|
||||
|
||||
Included Utility Programs
|
||||
-------------------------
|
||||
|
||||
@ -30,8 +146,8 @@ other programs, applications and services can utilise.
|
||||
The rnsd Utility
|
||||
================
|
||||
|
||||
To do so is very easy. Simply run the included ``rnsd`` command. When ``rnsd``
|
||||
is running, it will keep all configured interfaces open, handle transport if
|
||||
It is very easy to run Reticulum as a service. Simply run the included ``rnsd`` command.
|
||||
When ``rnsd`` is running, it will keep all configured interfaces open, handle transport if
|
||||
it is enabled, and allow any other programs to immediately utilise the
|
||||
Reticulum network it is configured for.
|
||||
|
||||
|
@ -70,6 +70,7 @@ to participate in the development of Reticulum itself.</p>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="using.html#configuration-data">Configuration & Data</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="using.html#included-utility-programs">Included Utility Programs</a><ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="using.html#the-rnsd-utility">The rnsd Utility</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="using.html#the-rnstatus-utility">The rnstatus Utility</a></li>
|
||||
@ -95,8 +96,6 @@ 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#interface-modes">Interface Modes</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>
|
||||
@ -107,6 +106,9 @@ to participate in the development of Reticulum itself.</p>
|
||||
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#pipe-interface">Pipe 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>
|
||||
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#interface-modes">Interface Modes</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#announce-rate-control">Announce Rate Control</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a><ul>
|
||||
|
@ -53,149 +53,6 @@ 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="interface-modes">
|
||||
<span id="interfaces-modes"></span><h2>Interface Modes<a class="headerlink" href="#interface-modes" title="Permalink to this headline">¶</a></h2>
|
||||
<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>
|
||||
<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,
|
||||
meshing and transport functionality is activated.</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>
|
||||
</div>
|
||||
</li>
|
||||
<li><div class="line-block">
|
||||
<div class="line">The <code class="docutils literal notranslate"><span class="pre">roaming</span></code> mode should be used on interfaces that are
|
||||
roaming (physically mobile), seen from the perspective of
|
||||
other nodes in the network. As an example, if a vehicle is
|
||||
equipped with an external LoRa interface, and an internal,
|
||||
WiFi-based interface, that serves devices that are moving
|
||||
_with_ the vehicle, the external LoRa interface should be
|
||||
configured as <code class="docutils literal notranslate"><span class="pre">roaming</span></code>, and the internal interface can
|
||||
be left in the default mode. With transport enabled, such
|
||||
a setup will allow all internal devices to reach each other,
|
||||
and all other devices that are available on the LoRa side
|
||||
of the network, when they are in range. Devices on the LoRa
|
||||
side of the network will also be able to reach devices
|
||||
internal to the vehicle, when it is in range. Paths via
|
||||
<code class="docutils literal notranslate"><span class="pre">roaming</span></code> interfaces also expire faster.</div>
|
||||
</div>
|
||||
</li>
|
||||
<li><div class="line-block">
|
||||
<div class="line">The purpose of the <code class="docutils literal notranslate"><span class="pre">boundary</span></code> mode is to specify interfaces
|
||||
that establish connectivity with network segments that are
|
||||
significantly different than the one this node exists on.
|
||||
As an example, if a Reticulum instance is part of a LoRa-based
|
||||
network, but also has a high-speed connection to a
|
||||
public Transport Node available on the Internet, the interface
|
||||
connecting over the Internet should be set to <code class="docutils literal notranslate"><span class="pre">boundary</span></code> mode.</div>
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
</div></blockquote>
|
||||
<p>For a table describing the impact of all modes on announce propagation,
|
||||
please see the <a class="reference internal" href="understanding.html#understanding-announcepropagation"><span class="std std-ref">Announce Propagation Rules</span></a> section.</p>
|
||||
</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
|
||||
@ -653,6 +510,211 @@ 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 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>
|
||||
<blockquote>
|
||||
<div><p><em>If an interface exceeds its announce cap, it will queue announces
|
||||
for later transmission. Reticulum will always prioritise propagating
|
||||
announces from nearby nodes first. This ensures that the local
|
||||
topology is prioritised, and that slow networks are not overwhelmed
|
||||
by interconnected fast networks.</em></p>
|
||||
<p><em>Destinations that are rapidly re-announcing will be down-prioritised
|
||||
further. Trying to get “first-in-line” by announce spamming will have
|
||||
the exact opposite effect: Getting moved to the back of the queue every
|
||||
time a new announce from the excessively announcing destination is received.</em></p>
|
||||
<p><em>This means that it is always beneficial to select a balanced
|
||||
announce rate, and not announce more often than is actually necesarry
|
||||
for your application to function.</em></p>
|
||||
</div></blockquote>
|
||||
</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="interface-modes">
|
||||
<span id="interfaces-modes"></span><h2>Interface Modes<a class="headerlink" href="#interface-modes" title="Permalink to this headline">¶</a></h2>
|
||||
<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>
|
||||
<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,
|
||||
meshing and transport functionality is activated.</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>
|
||||
</div>
|
||||
</li>
|
||||
<li><div class="line-block">
|
||||
<div class="line">The <code class="docutils literal notranslate"><span class="pre">roaming</span></code> mode should be used on interfaces that are
|
||||
roaming (physically mobile), seen from the perspective of
|
||||
other nodes in the network. As an example, if a vehicle is
|
||||
equipped with an external LoRa interface, and an internal,
|
||||
WiFi-based interface, that serves devices that are moving
|
||||
_with_ the vehicle, the external LoRa interface should be
|
||||
configured as <code class="docutils literal notranslate"><span class="pre">roaming</span></code>, and the internal interface can
|
||||
be left in the default mode. With transport enabled, such
|
||||
a setup will allow all internal devices to reach each other,
|
||||
and all other devices that are available on the LoRa side
|
||||
of the network, when they are in range. Devices on the LoRa
|
||||
side of the network will also be able to reach devices
|
||||
internal to the vehicle, when it is in range. Paths via
|
||||
<code class="docutils literal notranslate"><span class="pre">roaming</span></code> interfaces also expire faster.</div>
|
||||
</div>
|
||||
</li>
|
||||
<li><div class="line-block">
|
||||
<div class="line">The purpose of the <code class="docutils literal notranslate"><span class="pre">boundary</span></code> mode is to specify interfaces
|
||||
that establish connectivity with network segments that are
|
||||
significantly different than the one this node exists on.
|
||||
As an example, if a Reticulum instance is part of a LoRa-based
|
||||
network, but also has a high-speed connection to a
|
||||
public Transport Node available on the Internet, the interface
|
||||
connecting over the Internet should be set to <code class="docutils literal notranslate"><span class="pre">boundary</span></code> mode.</div>
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
</div></blockquote>
|
||||
<p>For a table describing the impact of all modes on announce propagation,
|
||||
please see the <a class="reference internal" href="understanding.html#understanding-announcepropagation"><span class="std std-ref">Announce Propagation Rules</span></a> section.</p>
|
||||
</div>
|
||||
<div class="section" id="announce-rate-control">
|
||||
<span id="interfaces-announcerates"></span><h2>Announce Rate Control<a class="headerlink" href="#announce-rate-control" title="Permalink to this headline">¶</a></h2>
|
||||
<p>The built-in announce control mechanisms and the default <code class="docutils literal notranslate"><span class="pre">announce_cap</span></code>
|
||||
option described above are sufficient most of the time, but in some cases, especially on fast
|
||||
interfaces, it may be useful to control the target announce rate. Using the
|
||||
<code class="docutils literal notranslate"><span class="pre">announce_rate_target</span></code>, <code class="docutils literal notranslate"><span class="pre">announce_rate_grace</span></code> and <code class="docutils literal notranslate"><span class="pre">announce_rate_penalty</span></code>
|
||||
options, this can be done on a per-interface basis, and moderates the <em>rate at
|
||||
which received announces are re-broadcasted to other interfaces</em>.</p>
|
||||
<blockquote>
|
||||
<div><ul>
|
||||
<li><div class="line-block">
|
||||
<div class="line">The <code class="docutils literal notranslate"><span class="pre">announce_rate_target</span></code> option sets the minimum amount of time,
|
||||
in seconds, that should pass between received announces, for any one
|
||||
destination. As an example, setting this value to <code class="docutils literal notranslate"><span class="pre">3600</span></code> means that
|
||||
announces <em>received</em> on this interface will only be re-transmitted and
|
||||
propagated to other interfaces once every hour, no matter how often they
|
||||
are received.</div>
|
||||
</div>
|
||||
</li>
|
||||
<li><div class="line-block">
|
||||
<div class="line">The optional <code class="docutils literal notranslate"><span class="pre">announce_rate_grace</span></code> defines the number of times a destination
|
||||
can violate the announce rate before the target rate is enforced.</div>
|
||||
</div>
|
||||
</li>
|
||||
<li><div class="line-block">
|
||||
<div class="line">The optional <code class="docutils literal notranslate"><span class="pre">announce_rate_penalty</span></code> configures an extra amount of
|
||||
time that is added to the normal rate target. As an example, if a penalty
|
||||
of <code class="docutils literal notranslate"><span class="pre">7200</span></code> seconds is defined, once the rate target is enforced, the
|
||||
destination in question will only have its announces propagated every
|
||||
3 hours, until it lowers its actual announce rate to within the target.</div>
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
</div></blockquote>
|
||||
<p>These mechanisms, in conjunction with the <code class="docutils literal notranslate"><span class="pre">annouce_cap</span></code> mechanisms mentioned
|
||||
above means that it is essential to select a balanced announce strategy for
|
||||
your destinations. The more balanced you can make this decision, the easier
|
||||
it will be for your destinations to make it into slower networks that many hops
|
||||
away. Or you can prioritise only reaching high-capacity networks with more frequent
|
||||
announces.</p>
|
||||
<p>Current statistics and information about announce rates can be viewed using the
|
||||
<code class="docutils literal notranslate"><span class="pre">rnpath</span> <span class="pre">-r</span></code> command.</p>
|
||||
<p>It is important to note that there is no one right or wrong way to set up announce
|
||||
rates. Slower networks will naturally tend towards using less frequent announces to
|
||||
conserve bandwidth, while very fast networks can support applications that
|
||||
need very frequent announces. Reticulum implements these mechanisms to ensure
|
||||
that a large span of network types can seamlessly <em>co-exist</em> and interconnect.</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
@ -665,8 +727,6 @@ beaconing functionality described above.</p>
|
||||
<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="#interface-modes">Interface Modes</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>
|
||||
@ -677,6 +737,9 @@ beaconing functionality described above.</p>
|
||||
<li><a class="reference internal" href="#pipe-interface">Pipe 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>
|
||||
<li><a class="reference internal" href="#interface-modes">Interface Modes</a></li>
|
||||
<li><a class="reference internal" href="#announce-rate-control">Announce Rate Control</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
Binary file not shown.
File diff suppressed because one or more lines are too long
@ -864,27 +864,7 @@ but excluding any interface access codes.
|
||||
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>
|
||||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Full ────── ✓ ──┐ ┌── ✓ ── Full
|
||||
AP ──────── ✓ ──┼───> Full >───┼── ✕ ── AP
|
||||
Boundary ── ✓ ──┤ ├── ✓ ── Boundary
|
||||
Roaming ─── ✓ ──┘ └── ✓ ── Roaming
|
||||
|
||||
Full ────── ✕ ──┐ ┌── ✓ ── Full
|
||||
AP ──────── ✕ ──┼────> AP >────┼── ✕ ── AP
|
||||
Boundary ── ✕ ──┤ ├── ✓ ── Boundary
|
||||
Roaming ─── ✕ ──┘ └── ✓ ── Roaming
|
||||
|
||||
Full ────── ✓ ──┐ ┌── ✓ ── Full
|
||||
AP ──────── ✓ ──┼─> Roaming >──┼── ✕ ── AP
|
||||
Boundary ── ✕ ──┤ ├── ✕ ── Boundary
|
||||
Roaming ─── ✕ ──┘ └── ✕ ── Roaming
|
||||
|
||||
Full ────── ✓ ──┐ ┌── ✓ ── Full
|
||||
AP ──────── ✓ ──┼─> Boundary >─┼── ✕ ── AP
|
||||
Boundary ── ✓ ──┤ ├── ✓ ── Boundary
|
||||
Roaming ─── ✕ ──┘ └── ✕ ── Roaming
|
||||
</pre></div>
|
||||
</div>
|
||||
<img alt="_images/if_mode_graph_b.png" src="_images/if_mode_graph_b.png" />
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
@ -56,6 +56,117 @@ program starts up and also wants access to the same Reticulum network, the
|
||||
instance is simply shared. This works for any number of programs running
|
||||
concurrently, and is very easy to use, but depending on your use case, there
|
||||
are other options.</p>
|
||||
<div class="section" id="configuration-data">
|
||||
<h2>Configuration & Data<a class="headerlink" href="#configuration-data" title="Permalink to this headline">¶</a></h2>
|
||||
<p>A Reticulum stores all information that it needs to function in a single file-
|
||||
system directory. By default, this directory is <code class="docutils literal notranslate"><span class="pre">~/.reticulum</span></code>, but you can
|
||||
use any directory you wish. You can also run multiple separate Reticulum
|
||||
instances on the same physical system, in complete isolation from each other,
|
||||
or connected together.</p>
|
||||
<p>In most cases, a single physical system will only need to run one Reticulum
|
||||
instance. This can either be launched at boot, as a system service, or simply
|
||||
be brought up when a program needs it. In either case, any number of programs
|
||||
running on the same system will automatically share the same Reticulum instance,
|
||||
if the configuration allows for it, which it does by default.</p>
|
||||
<p>The entire configuration of Reticulum is found in the <code class="docutils literal notranslate"><span class="pre">~/.reticulum/config</span></code>
|
||||
file. When Reticulum is first started on a new system, a basic, functional
|
||||
configuration file is created. The default configuration looks like this:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This is the default Reticulum config file.</span>
|
||||
<span class="c1"># You should probably edit it to include any additional,</span>
|
||||
<span class="c1"># interfaces and settings you might need.</span>
|
||||
|
||||
<span class="c1"># Only the most basic options are included in this default</span>
|
||||
<span class="c1"># configuration. To see a more verbose, and much longer,</span>
|
||||
<span class="c1"># configuration example, you can run the command:</span>
|
||||
<span class="c1"># rnsd --exampleconfig</span>
|
||||
|
||||
|
||||
<span class="p">[</span><span class="n">reticulum</span><span class="p">]</span>
|
||||
|
||||
<span class="c1"># If you enable Transport, your system will route traffic</span>
|
||||
<span class="c1"># for other peers, pass announces and serve path requests.</span>
|
||||
<span class="c1"># This should only be done for systems that are suited to</span>
|
||||
<span class="c1"># act as transport nodes, ie. if they are stationary and</span>
|
||||
<span class="c1"># always-on. This directive is optional and can be removed</span>
|
||||
<span class="c1"># for brevity.</span>
|
||||
|
||||
<span class="n">enable_transport</span> <span class="o">=</span> <span class="kc">False</span>
|
||||
|
||||
|
||||
<span class="c1"># By default, the first program to launch the Reticulum</span>
|
||||
<span class="c1"># Network Stack will create a shared instance, that other</span>
|
||||
<span class="c1"># programs can communicate with. Only the shared instance</span>
|
||||
<span class="c1"># opens all the configured interfaces directly, and other</span>
|
||||
<span class="c1"># local programs communicate with the shared instance over</span>
|
||||
<span class="c1"># a local socket. This is completely transparent to the</span>
|
||||
<span class="c1"># user, and should generally be turned on. This directive</span>
|
||||
<span class="c1"># is optional and can be removed for brevity.</span>
|
||||
|
||||
<span class="n">share_instance</span> <span class="o">=</span> <span class="n">Yes</span>
|
||||
|
||||
|
||||
<span class="c1"># If you want to run multiple *different* shared instances</span>
|
||||
<span class="c1"># on the same system, you will need to specify different</span>
|
||||
<span class="c1"># shared instance ports for each. The defaults are given</span>
|
||||
<span class="c1"># below, and again, these options can be left out if you</span>
|
||||
<span class="c1"># don't need them.</span>
|
||||
|
||||
<span class="n">shared_instance_port</span> <span class="o">=</span> <span class="mi">37428</span>
|
||||
<span class="n">instance_control_port</span> <span class="o">=</span> <span class="mi">37429</span>
|
||||
|
||||
|
||||
<span class="c1"># You can configure Reticulum to panic and forcibly close</span>
|
||||
<span class="c1"># if an unrecoverable interface error occurs, such as the</span>
|
||||
<span class="c1"># hardware device for an interface disappearing. This is</span>
|
||||
<span class="c1"># an optional directive, and can be left out for brevity.</span>
|
||||
<span class="c1"># This behaviour is disabled by default.</span>
|
||||
|
||||
<span class="n">panic_on_interface_error</span> <span class="o">=</span> <span class="n">No</span>
|
||||
|
||||
|
||||
<span class="p">[</span><span class="n">logging</span><span class="p">]</span>
|
||||
<span class="c1"># Valid log levels are 0 through 7:</span>
|
||||
<span class="c1"># 0: Log only critical information</span>
|
||||
<span class="c1"># 1: Log errors and lower log levels</span>
|
||||
<span class="c1"># 2: Log warnings and lower log levels</span>
|
||||
<span class="c1"># 3: Log notices and lower log levels</span>
|
||||
<span class="c1"># 4: Log info and lower (this is the default)</span>
|
||||
<span class="c1"># 5: Verbose logging</span>
|
||||
<span class="c1"># 6: Debug logging</span>
|
||||
<span class="c1"># 7: Extreme logging</span>
|
||||
|
||||
<span class="n">loglevel</span> <span class="o">=</span> <span class="mi">4</span>
|
||||
|
||||
|
||||
<span class="c1"># The interfaces section defines the physical and virtual</span>
|
||||
<span class="c1"># interfaces Reticulum will use to communicate on. This</span>
|
||||
<span class="c1"># section will contain examples for a variety of interface</span>
|
||||
<span class="c1"># types. You can modify these or use them as a basis for</span>
|
||||
<span class="c1"># your own config, or simply remove the unused ones.</span>
|
||||
|
||||
<span class="p">[</span><span class="n">interfaces</span><span class="p">]</span>
|
||||
|
||||
<span class="c1"># This interface enables communication with other</span>
|
||||
<span class="c1"># link-local Reticulum nodes over UDP. It does not</span>
|
||||
<span class="c1"># need any functional IP infrastructure like routers</span>
|
||||
<span class="c1"># or DHCP servers, but will require that at least link-</span>
|
||||
<span class="c1"># local IPv6 is enabled in your operating system, which</span>
|
||||
<span class="c1"># should be enabled by default in almost any OS. See</span>
|
||||
<span class="c1"># the Reticulum Manual for more configuration options.</span>
|
||||
|
||||
<span class="p">[[</span><span class="n">Default</span> <span class="n">Interface</span><span class="p">]]</span>
|
||||
<span class="nb">type</span> <span class="o">=</span> <span class="n">AutoInterface</span>
|
||||
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If Reticulum infrastructure already exists locally, you probably don’t need to
|
||||
change anything, and you may already be connected to a wider network. If not,
|
||||
you will probably need to add relevant <em>interfaces</em> to the configuration, in
|
||||
order to communicate with other systems. It is a good idea to read the comments
|
||||
and explanations in the above default config. It will teach you the basic
|
||||
concepts you need to understand to configure your network. Once you have done that,
|
||||
take a look at the <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Interfaces</span></a> chapter of this manual.</p>
|
||||
</div>
|
||||
<div class="section" id="included-utility-programs">
|
||||
<h2>Included Utility Programs<a class="headerlink" href="#included-utility-programs" title="Permalink to this headline">¶</a></h2>
|
||||
<p>If you often use Reticulum from several different programs, or simply want
|
||||
@ -64,8 +175,8 @@ a transport node, you might want to run Reticulum as a separate service that
|
||||
other programs, applications and services can utilise.</p>
|
||||
<div class="section" id="the-rnsd-utility">
|
||||
<h3>The rnsd Utility<a class="headerlink" href="#the-rnsd-utility" title="Permalink to this headline">¶</a></h3>
|
||||
<p>To do so is very easy. Simply run the included <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> command. When <code class="docutils literal notranslate"><span class="pre">rnsd</span></code>
|
||||
is running, it will keep all configured interfaces open, handle transport if
|
||||
<p>It is very easy to run Reticulum as a service. Simply run the included <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> command.
|
||||
When <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> is running, it will keep all configured interfaces open, handle transport if
|
||||
it is enabled, and allow any other programs to immediately utilise the
|
||||
Reticulum network it is configured for.</p>
|
||||
<p>You can even run multiple instances of rnsd with different configurations on
|
||||
@ -298,6 +409,7 @@ WantedBy=multi-user.target
|
||||
<h3><a href="index.html">Table of Contents</a></h3>
|
||||
<ul>
|
||||
<li><a class="reference internal" href="#">Using Reticulum on Your System</a><ul>
|
||||
<li><a class="reference internal" href="#configuration-data">Configuration & Data</a></li>
|
||||
<li><a class="reference internal" href="#included-utility-programs">Included Utility Programs</a><ul>
|
||||
<li><a class="reference internal" href="#the-rnsd-utility">The rnsd Utility</a></li>
|
||||
<li><a class="reference internal" href="#the-rnstatus-utility">The rnstatus Utility</a></li>
|
||||
|
BIN
docs/source/graphics/if_mode_graph.png
Normal file
BIN
docs/source/graphics/if_mode_graph.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 46 KiB |
BIN
docs/source/graphics/if_mode_graph_b.png
Normal file
BIN
docs/source/graphics/if_mode_graph_b.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 25 KiB |
BIN
docs/source/graphics/if_mode_graph_b.xcf
Normal file
BIN
docs/source/graphics/if_mode_graph_b.xcf
Normal file
Binary file not shown.
@ -19,125 +19,6 @@ types, have a look at the :ref:`Building Networks<networks-main>` chapter of thi
|
||||
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-modes:
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
* | The default value is ``full``. In this mode, all discovery,
|
||||
meshing and transport functionality is activated.
|
||||
|
||||
* | 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.
|
||||
|
||||
* | The ``roaming`` mode should be used on interfaces that are
|
||||
roaming (physically mobile), seen from the perspective of
|
||||
other nodes in the network. As an example, if a vehicle is
|
||||
equipped with an external LoRa interface, and an internal,
|
||||
WiFi-based interface, that serves devices that are moving
|
||||
_with_ the vehicle, the external LoRa interface should be
|
||||
configured as ``roaming``, and the internal interface can
|
||||
be left in the default mode. With transport enabled, such
|
||||
a setup will allow all internal devices to reach each other,
|
||||
and all other devices that are available on the LoRa side
|
||||
of the network, when they are in range. Devices on the LoRa
|
||||
side of the network will also be able to reach devices
|
||||
internal to the vehicle, when it is in range. Paths via
|
||||
``roaming`` interfaces also expire faster.
|
||||
|
||||
* | The purpose of the ``boundary`` mode is to specify interfaces
|
||||
that establish connectivity with network segments that are
|
||||
significantly different than the one this node exists on.
|
||||
As an example, if a Reticulum instance is part of a LoRa-based
|
||||
network, but also has a high-speed connection to a
|
||||
public Transport Node available on the Internet, the interface
|
||||
connecting over the Internet should be set to ``boundary`` mode.
|
||||
|
||||
For a table describing the impact of all modes on announce propagation,
|
||||
please see the :ref:`Announce Propagation Rules<understanding-announcepropagation>` section.
|
||||
|
||||
.. _interfaces-auto:
|
||||
|
||||
Auto Interface
|
||||
@ -664,3 +545,182 @@ 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 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``.
|
||||
|
||||
*If an interface exceeds its announce cap, it will queue announces
|
||||
for later transmission. Reticulum will always prioritise propagating
|
||||
announces from nearby nodes first. This ensures that the local
|
||||
topology is prioritised, and that slow networks are not overwhelmed
|
||||
by interconnected fast networks.*
|
||||
|
||||
*Destinations that are rapidly re-announcing will be down-prioritised
|
||||
further. Trying to get "first-in-line" by announce spamming will have
|
||||
the exact opposite effect: Getting moved to the back of the queue every
|
||||
time a new announce from the excessively announcing destination is received.*
|
||||
|
||||
*This means that it is always beneficial to select a balanced
|
||||
announce rate, and not announce more often than is actually necesarry
|
||||
for your application to function.*
|
||||
|
||||
* | 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-modes:
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
* | The default value is ``full``. In this mode, all discovery,
|
||||
meshing and transport functionality is activated.
|
||||
|
||||
* | 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.
|
||||
|
||||
* | The ``roaming`` mode should be used on interfaces that are
|
||||
roaming (physically mobile), seen from the perspective of
|
||||
other nodes in the network. As an example, if a vehicle is
|
||||
equipped with an external LoRa interface, and an internal,
|
||||
WiFi-based interface, that serves devices that are moving
|
||||
_with_ the vehicle, the external LoRa interface should be
|
||||
configured as ``roaming``, and the internal interface can
|
||||
be left in the default mode. With transport enabled, such
|
||||
a setup will allow all internal devices to reach each other,
|
||||
and all other devices that are available on the LoRa side
|
||||
of the network, when they are in range. Devices on the LoRa
|
||||
side of the network will also be able to reach devices
|
||||
internal to the vehicle, when it is in range. Paths via
|
||||
``roaming`` interfaces also expire faster.
|
||||
|
||||
* | The purpose of the ``boundary`` mode is to specify interfaces
|
||||
that establish connectivity with network segments that are
|
||||
significantly different than the one this node exists on.
|
||||
As an example, if a Reticulum instance is part of a LoRa-based
|
||||
network, but also has a high-speed connection to a
|
||||
public Transport Node available on the Internet, the interface
|
||||
connecting over the Internet should be set to ``boundary`` mode.
|
||||
|
||||
For a table describing the impact of all modes on announce propagation,
|
||||
please see the :ref:`Announce Propagation Rules<understanding-announcepropagation>` section.
|
||||
|
||||
.. _interfaces-announcerates:
|
||||
|
||||
Announce Rate Control
|
||||
=====================
|
||||
|
||||
The built-in announce control mechanisms and the default ``announce_cap``
|
||||
option described above are sufficient most of the time, but in some cases, especially on fast
|
||||
interfaces, it may be useful to control the target announce rate. Using the
|
||||
``announce_rate_target``, ``announce_rate_grace`` and ``announce_rate_penalty``
|
||||
options, this can be done on a per-interface basis, and moderates the *rate at
|
||||
which received announces are re-broadcasted to other interfaces*.
|
||||
|
||||
* | The ``announce_rate_target`` option sets the minimum amount of time,
|
||||
in seconds, that should pass between received announces, for any one
|
||||
destination. As an example, setting this value to ``3600`` means that
|
||||
announces *received* on this interface will only be re-transmitted and
|
||||
propagated to other interfaces once every hour, no matter how often they
|
||||
are received.
|
||||
|
||||
* | The optional ``announce_rate_grace`` defines the number of times a destination
|
||||
can violate the announce rate before the target rate is enforced.
|
||||
|
||||
* | The optional ``announce_rate_penalty`` configures an extra amount of
|
||||
time that is added to the normal rate target. As an example, if a penalty
|
||||
of ``7200`` seconds is defined, once the rate target is enforced, the
|
||||
destination in question will only have its announces propagated every
|
||||
3 hours, until it lowers its actual announce rate to within the target.
|
||||
|
||||
These mechanisms, in conjunction with the ``annouce_cap`` mechanisms mentioned
|
||||
above means that it is essential to select a balanced announce strategy for
|
||||
your destinations. The more balanced you can make this decision, the easier
|
||||
it will be for your destinations to make it into slower networks that many hops
|
||||
away. Or you can prioritise only reaching high-capacity networks with more frequent
|
||||
announces.
|
||||
|
||||
Current statistics and information about announce rates can be viewed using the
|
||||
``rnpath -r`` command.
|
||||
|
||||
It is important to note that there is no one right or wrong way to set up announce
|
||||
rates. Slower networks will naturally tend towards using less frequent announces to
|
||||
conserve bandwidth, while very fast networks can support applications that
|
||||
need very frequent announces. Reticulum implements these mechanisms to ensure
|
||||
that a large span of network types can seamlessly *co-exist* and interconnect.
|
||||
|
||||
|
@ -813,8 +813,10 @@ 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.
|
||||
|
||||
.. code-block:: text
|
||||
.. image:: graphics/if_mode_graph_b.png
|
||||
|
||||
..
|
||||
(.. code-block:: text)
|
||||
Full ────── ✓ ──┐ ┌── ✓ ── Full
|
||||
AP ──────── ✓ ──┼───> Full >───┼── ✕ ── AP
|
||||
Boundary ── ✓ ──┤ ├── ✓ ── Boundary
|
||||
@ -835,4 +837,3 @@ different interface modes, and how they are configured.
|
||||
Boundary ── ✓ ──┤ ├── ✓ ── Boundary
|
||||
Roaming ─── ✕ ──┘ └── ✕ ── Roaming
|
||||
|
||||
|
||||
|
@ -19,6 +19,122 @@ instance is simply shared. This works for any number of programs running
|
||||
concurrently, and is very easy to use, but depending on your use case, there
|
||||
are other options.
|
||||
|
||||
Configuration & Data
|
||||
--------------------
|
||||
|
||||
A Reticulum stores all information that it needs to function in a single file-
|
||||
system directory. By default, this directory is ``~/.reticulum``, but you can
|
||||
use any directory you wish. You can also run multiple separate Reticulum
|
||||
instances on the same physical system, in complete isolation from each other,
|
||||
or connected together.
|
||||
|
||||
In most cases, a single physical system will only need to run one Reticulum
|
||||
instance. This can either be launched at boot, as a system service, or simply
|
||||
be brought up when a program needs it. In either case, any number of programs
|
||||
running on the same system will automatically share the same Reticulum instance,
|
||||
if the configuration allows for it, which it does by default.
|
||||
|
||||
The entire configuration of Reticulum is found in the ``~/.reticulum/config``
|
||||
file. When Reticulum is first started on a new system, a basic, functional
|
||||
configuration file is created. The default configuration looks like this:
|
||||
|
||||
.. code::
|
||||
|
||||
# This is the default Reticulum config file.
|
||||
# You should probably edit it to include any additional,
|
||||
# interfaces and settings you might need.
|
||||
|
||||
# Only the most basic options are included in this default
|
||||
# configuration. To see a more verbose, and much longer,
|
||||
# configuration example, you can run the command:
|
||||
# rnsd --exampleconfig
|
||||
|
||||
|
||||
[reticulum]
|
||||
|
||||
# If you enable Transport, your system will route traffic
|
||||
# for other peers, pass announces and serve path requests.
|
||||
# This should only be done for systems that are suited to
|
||||
# act as transport nodes, ie. if they are stationary and
|
||||
# always-on. This directive is optional and can be removed
|
||||
# for brevity.
|
||||
|
||||
enable_transport = False
|
||||
|
||||
|
||||
# By default, the first program to launch the Reticulum
|
||||
# Network Stack will create a shared instance, that other
|
||||
# programs can communicate with. Only the shared instance
|
||||
# opens all the configured interfaces directly, and other
|
||||
# local programs communicate with the shared instance over
|
||||
# a local socket. This is completely transparent to the
|
||||
# user, and should generally be turned on. This directive
|
||||
# is optional and can be removed for brevity.
|
||||
|
||||
share_instance = Yes
|
||||
|
||||
|
||||
# If you want to run multiple *different* shared instances
|
||||
# on the same system, you will need to specify different
|
||||
# shared instance ports for each. The defaults are given
|
||||
# below, and again, these options can be left out if you
|
||||
# don't need them.
|
||||
|
||||
shared_instance_port = 37428
|
||||
instance_control_port = 37429
|
||||
|
||||
|
||||
# You can configure Reticulum to panic and forcibly close
|
||||
# if an unrecoverable interface error occurs, such as the
|
||||
# hardware device for an interface disappearing. This is
|
||||
# an optional directive, and can be left out for brevity.
|
||||
# This behaviour is disabled by default.
|
||||
|
||||
panic_on_interface_error = No
|
||||
|
||||
|
||||
[logging]
|
||||
# Valid log levels are 0 through 7:
|
||||
# 0: Log only critical information
|
||||
# 1: Log errors and lower log levels
|
||||
# 2: Log warnings and lower log levels
|
||||
# 3: Log notices and lower log levels
|
||||
# 4: Log info and lower (this is the default)
|
||||
# 5: Verbose logging
|
||||
# 6: Debug logging
|
||||
# 7: Extreme logging
|
||||
|
||||
loglevel = 4
|
||||
|
||||
|
||||
# The interfaces section defines the physical and virtual
|
||||
# interfaces Reticulum will use to communicate on. This
|
||||
# section will contain examples for a variety of interface
|
||||
# types. You can modify these or use them as a basis for
|
||||
# your own config, or simply remove the unused ones.
|
||||
|
||||
[interfaces]
|
||||
|
||||
# This interface enables communication with other
|
||||
# link-local Reticulum nodes over UDP. It does not
|
||||
# need any functional IP infrastructure like routers
|
||||
# or DHCP servers, but will require that at least link-
|
||||
# local IPv6 is enabled in your operating system, which
|
||||
# should be enabled by default in almost any OS. See
|
||||
# the Reticulum Manual for more configuration options.
|
||||
|
||||
[[Default Interface]]
|
||||
type = AutoInterface
|
||||
interface_enabled = True
|
||||
|
||||
If Reticulum infrastructure already exists locally, you probably don't need to
|
||||
change anything, and you may already be connected to a wider network. If not,
|
||||
you will probably need to add relevant *interfaces* to the configuration, in
|
||||
order to communicate with other systems. It is a good idea to read the comments
|
||||
and explanations in the above default config. It will teach you the basic
|
||||
concepts you need to understand to configure your network. Once you have done that,
|
||||
take a look at the :ref:`Interfaces<interfaces-main>` chapter of this manual.
|
||||
|
||||
Included Utility Programs
|
||||
-------------------------
|
||||
|
||||
@ -30,8 +146,8 @@ other programs, applications and services can utilise.
|
||||
The rnsd Utility
|
||||
================
|
||||
|
||||
To do so is very easy. Simply run the included ``rnsd`` command. When ``rnsd``
|
||||
is running, it will keep all configured interfaces open, handle transport if
|
||||
It is very easy to run Reticulum as a service. Simply run the included ``rnsd`` command.
|
||||
When ``rnsd`` is running, it will keep all configured interfaces open, handle transport if
|
||||
it is enabled, and allow any other programs to immediately utilise the
|
||||
Reticulum network it is configured for.
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user