Updated documentation

This commit is contained in:
Mark Qvist 2026-11-07 13:25:25 +01:00
parent acb38a8a1c
commit 65a7208a9d
No known key found for this signature in database
37 changed files with 1648 additions and 144 deletions

View file

@ -1,4 +1,4 @@
# Sphinx build info version 1
# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
config: 1fa679ad0dc0d31233acdb7028711e33
config: 9b6eb4356bc445a42224e1983b6dd8e9
tags: 645f666f9bcd5a90fca523b33c5a78b7

View file

@ -23,6 +23,7 @@ to participate in the development of Reticulum itself.
zen
software
using
stamps
understanding
hardware
interfaces

View file

@ -965,13 +965,6 @@ Reticulum includes a powerful system for publishing your local interfaces to the
When an interface is made **discoverable**, your Reticulum instance will periodically broadcast an announce packet containing the connection details and parameters required for other peers to establish a connection. These announces are propagated over the network using the standard Reticulum announce mechanism using the ``rnstransport.discovery.interface`` destination type.
.. note::
To use the interface discovery functionality, the ``LXMF`` module must be installed in your Python environment. You can install it using pip:
.. code:: sh
pip install lxmf
Enabling Discovery
------------------

View file

@ -0,0 +1,251 @@
************************
Protecting Open Networks
************************
.. important::
Reticulum is currently transitioning towards full, on-network stamp verification and enforcement via a phased transition:
- The ``1.6.0`` release completely implements the required mechanisms, and will start excercising the verification system in the transport backend. By default, ``1.6.0`` does not enable full stamp generation, emission and enforcement, but all of these options can be early-enabled in the configuration.
- The ``1.6.1`` release will enable full stamp generation and emission of all types by default, but will leave the *enforcement* a configurable option.
- The ``1.6.2`` release will complete the transition, activating full stamp enforcement across all the systems.
The stated version numbers are the *intended* release sequence. If any issues or implementation problems are found during the initial network deployments, the transition points may be pushed later than this plan by interim releases.
While you can create entirely closed-off and private networks with Reticulum, the protocol itself is open and permissionless. On widely interconnected networks, anyone can create identities and globally reachable destinations without external permission or approval, and establish links anonymously over the network.
Such capabilities are powerful, and a required characteristic of a truly functional communications fabric, but also raise very large challenges, that have been almost impossible to solve in legacy networking technologies.
Reticulum approaches this particular problem, like most others, by employing cryptographic principles. This provides a comprehensive, multi-layered repertoire of defense mechanisms, which can be composed and employed in very effective ways.
In contrast to other networking paradigms, these mechanisms do not have to be bolted on to the application layer in hindsight, but are a core part of the protocol itself, which means that they can be applied universally and effectively:
All nodes help combat spam and network abuse, according to the rules *set by the actual owners of supplied resources* - not by any bureaucracy or external authority.
Rules and requirements can be adjusted live, dynamically and directly, and by those that actually operate and run the infrastructure and services.
The system has been designed so that it becomes very cheap computationally for resource-providing nodes to verify or reject traffic, and very expensive for malicious nodes to abuse the shared resources provided by the network's operators.
Cryptographic Stamps
====================
All networking primitives that consume shared network resources are gated by *stamps*. A stamp is compact, cryptographic token that proves that a certain amount of computation and energy has been expended in its creation.
The amount of such computation required for a stamp to be considered valid can be configured individually by the operator of the resource being made available, whether that is network transport, a node providing information for retrieval, a shared voice room, or something else entirely.
While the core functionality is completely automatic, and handled by Reticulum itself, the primitives are made available at the application layer API as well, so that developers can use them to implement further protections, if required by their usage scenarios. In most cases, however, simply setting the target *values* and required *costs* for the built-in mechanisms will be sufficient.
The *value* of a stamp is a decimal representation of how difficult a stamp was to create, on a scale from ``0.0`` to ``100.0``. The scale is **exponential**. An increase of one point is equal to *doubling* the average compute time required. Fractional values are supported, such as ``14.125``.
Internally, the fractional part is quantized to ``256`` different values, giving an approximately ``0.4%`` difficulty increase per step. You can use any decimal number when configuring stamps, such as ``9.3691`` and you do not have to worry about "landing on" the correct step values. Reticulum will automatically handle the quantization, wire-transport representation and value comparisons.
The term *cost* is used everywhere a stamp value *requirement* is configured or specified. In general, *value* refers to the actual, determined value of a given stamp, *cost* refers to a value requirement.
Base Primitives
---------------
Reticulum provides two types of base stamp primitives:
* **Detached stamps** can be tied to any external information, and are useful for stamping both static information and for one-time verification purposes. The stamp itself is a detached, short binary sequence, typically 14 to 32 bytes, that can be verified directly against the stamped material.
They can be configured from relatively easy to compute, even for embbedded systems and microcontrollers, all the way to something that is practically impossible, even with all the compute and memory on the planet.
* **Embedded stamps** are tied directly to a Reticulum Identity keyset, and embedded within it. The keyset itself *contains* the stamp, and there is no external, detached byte sequence for them.
Anyone can verify the value of an identity-embedded stamp simply from the public key material of the identity.
On-Network Types
----------------
The base primitives are used to implement scenario-specific network-level primitives that, if configured correctly, make spam and network abuse expensive, but validation and enforcement cheap and efficient.
* **Destination Stamps** are detached stamps associated with reticulum destinations. They are included in all announces sent by a destination, and by verifying that their value matches a transport node's cost requirement, they can be either accepted for rebroadcast onto the network, or rejected and dropped.
Destination stamps are *one-time* generations, and are reusable across announces. They limit the number of *new* destinations that can be created, and makes it expensive to spam a network with destinations that do not provide anything meaningful. As such, these stamps will typically target relatively high values, and their cost requirements should be set accordingly.
A generation time for such stamps in *minutes* rather than seconds can very well be reasonable on large, open-access networks. Due to their detached nature, they can also be pre-generated off-device (and do not require the private key material for generation), so that even low-powered nodes, such as microcontrollers, can use high-value destination stamps, by having them generated and loaded externally as a one-time procedure.
* **Path Request Stamps** are also detached stamps, but generated *individually* for every path request emitted on the network. These will typically have a much lower cost requirement than destination stamps, but if a node is overwhelmed by path requests, it can be tuned higher.
The stamp is generated against the individually unique *emission*, so that unstamped or low-value path requests for a destination cannot disrupt the resolution of legitimate ones toward that same destination.
* **Link Request Stamps** embedded stamps, carried in the ephemeral link request keyset. They are therefore completely transparent to the network, but can still be verified extremely quickly by any node along the link request path, who can then make a decision on whether or not to transport it.
Link request cost targets are set by the *endpoint destinations individually*. Every destination that includes a stamp in its announces will also include link request cost signalling. This means that any node that hears an announce from the destination will also know what link request stamp value to target, when establishing links to that destination.
Furthermore, spam and link request abuse can be filtered before even reaching the destination, if at least one node along the path validates the link request stamp value and cost requirement.
All of the stamp primitives, functionality and on-wire signalling is *transparent and backwards-compatible* with older versions of Reticulum transport nodes. This means, that even if a node doesn't itself understand stamp functionality, it will still transport all the required information. Stamped announces, path and link requests can cross older, non stamp-aware network segments transparently and unaffected.
.. _stamps-configuring:
Configuring Stamps
------------------
Reticulum, and its included utilities, provide sane default cost requirements and value targets for the different types of network stamps, but it is entirely up to the operator whether to follow the defaults. All of them are configurable on a per-node, per-application and per-destination basis.
Instance Configuration
^^^^^^^^^^^^^^^^^^^^^^
In reality, different kinds of networks will want to configure different kinds of costs and value targets for their use. For instance-wide defaults and settings, you can configure these in the ``[stamps]`` section of the Reticulum configuration file:
* | The ``stamp_destinations`` option enables generation and emission
of destination stamps in announces. This is a transitory option.
It will become mandatory and enabled by default in RNS ``1.6.1``.
* | The ``stamp_prs`` option enables stamping of path requests emitted
by this instance. This is a transitory option. It will become
mandatory and enabled by default in RNS ``1.6.1``.
* | The ``always_stamp_lrs`` option will stamp *all* outgoing link
requests, even to destinations that have not announced a link
request cost (and will, in that case, use the configured or
default link request cost). This option is mostly useful for
testing and diagnostics. In general use, Reticulum will handle
link request stamping and cost targets automatically.
* | The ``enforce_stamps`` option allows early activation of stamp
enforcement. When enabled, announces and path requests that do
not meet the configured cost requirements are dropped, and link
requests with insufficient stamps are ignored. This is a transitory
option. It will become mandatory and enabled by default in RNS
``1.6.2``.
* | The ``destination_cost`` option sets the default required stamp
cost for announced destinations to be accepted, and have their
announces propagated by this node. Defaults to ``23.5``.
* | The ``destination_value`` option sets the default stamp value that
this instance will target when generating new destination stamps.
An application can request higher targets for destinations that it
creates, but a requested lower value will always be clamped to the
configured default as a minimum. Defaults to ``25.0``.
*Destination stamps are one-time generations per destination, so it
is generally a good idea to target a slightly higher value than the
minimum required cost of the networks you want the destination to
be reachable on.*
* | The ``pr_cost`` option sets the required stamp cost for incoming
path requests. Defaults to ``15.8``.
* | The ``pr_value`` option sets the target stamp value for path
request stamps generated by this instance. Defaults to ``15.8``.
* | The ``lr_cost`` option sets the default link request stamp cost,
that destinations created on this instance will require. This
value can be freely overridden by applications that specify their
own link request cost requirements, and is solely used as the
default if no such specification is provided. Defaults to ``12.5``.
* | The ``lr_stamp_timeout`` and ``pr_stamp_timeout`` options set the
maximum amount of time, in seconds, to spend while attempting to
generate link and path request stamps respectively. If a stamp is
not generated within this timespan, the generation is cancelled,
and the link request or path request fails. Defaults to ``15``
seconds for both options.
An example of customised stamp cost and value configuration follows below:
.. code:: ini
[stamps]
stamp_destinations = yes
stamp_prs = yes
destination_cost = 24.8
destination_value = 26.25
pr_cost = 15.8
pr_value = 16.45
Stamp cost requirements can also be configured on a per-interface basis:
.. code:: ini
[[Public Gateway]]
type = BackboneInterface
mode = gateway
listen_on = 0.0.0.0
port = 4242
destination_cost = 25.0
pr_cost = 17.2
[[Local RNode]]
type = RNodeInterface
port = /dev/ttyUSB0
# Much lower requirements
# for the local network.
destination_cost = 11.2
pr_cost = 5.0
For Developers
^^^^^^^^^^^^^^
Applications can dynamically set their own stamp values and required link requests costs at runtime. Whenever the values are adjusted, the destination will have to send an announce for the updated information to become known by the rest of the network.
If you are setting these values at destination creation time, ensure that they are set *immediately* after the destination is instantiated, as Reticulum may queue internal, instance-local announces for the destination shortly after creation, so that the local shared instance and its clients are aware of the newly created destination.
.. code:: python
# Create a new destination
my_destination = RNS.Destination(
my_identity,
RNS.Destination.IN,
RNS.Destination.SINGLE,
"myapp", "service"
)
# Configure stamps
my_destination.set_value(30.0)
my_destination.set_link_cost(15.0)
Dynamically adjusting link request costs is a viable and intended mechanism for mitigating resource abuse, scraping, DoS attempts and other malicious behaviour. An application may implement mechanisms to statically or dynamically raise link request costs under certain conditions.
.. tip::
Remember here, though, that announce cadence should be preserved for such situations! If your destination is announcing too often in general, and wants to dynamically adjust link request costs at a critical moment, it may already have exhausted its announce rate limits on upstream nodes. So plan your application's announce cadence thoughtfully!
It is also possible for application code to directly get the destination value and link request cost for any known destination:
.. code:: python
# Get the value of a known destination
RNS.Identity.recall_stamp_value(destination_hash)
# Get the current link cost requirement
# of a known destination
RNS.Identity.recall_link_cost(destination_hash)
An ``Identity`` can be created with an embedded stamp value, by passing the target value at instantiation time:
.. code:: python
# Create a new, stamped identity
my_identity = RNS.Identity(value=24.0)
# Get the value of any known identity
another_identity.get_value()
As with destination stamps, this is a one-time generation procedure, that happens at Identity creation. Once an identity is created with an embedded stamp, its value *cannot* be upgraded at a later point as with detached stamps.
Filtering & QoS
===============
TODO: Section explaining the ``[filter]`` configuration options, for creating allow and blocklists for specific destination types.
Blackhole Management
====================
TODO: Section explaining the blackhole system conceptually (including distributed updates from other nodes), with a few terse examples for either locally - or across an entire managed network - blocking specific identities (and therefore any destination types created by such), as well as blocking incoming (identified) link requests from that identity at terminus.
Ingress & Burst Control
=======================
TODO: Section explaining the rate-limiting, ingress control and burst limiters conceptually, with a few, terse examples on how to configure them (linked references to other more extensive documentation sections of the options).

View file

@ -193,12 +193,14 @@ 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.
You can generate a much more verbose configuration example by running the command:
The example above does not document all the available options, only the basics.
To explore all the various configuration options available, you can generate a
much more verbose and complete configuration example by running the command:
``rnsd --exampleconfig``
The output includes examples for most interface types supported
by Reticulum, along with additional options and configuration parameters.
The output includes examples for most interface types supported by Reticulum,
along with additional options and configuration parameters.
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.
@ -644,7 +646,7 @@ Or fetch a file from the remote system:
$ rncp --fetch ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
The default identity file is stored in ``~/.reticulum/identities/rncp``, but you can use
The default identity file is stored in ``~/.reticulum/storage/identities/rncp``, but you can use
another one, which will be created if it does not already exist
.. code:: text
@ -731,7 +733,7 @@ Or enter the interactive mode pseudo-shell:
$ rnx 7a55144adf826958a9529a3bcf08b149 -x
The default identity file is stored in ``~/.reticulum/identities/rnx``, but you can use
The default identity file is stored in ``~/.reticulum/storage/identities/rnx``, but you can use
another one, which will be created if it does not already exist
.. code:: text
@ -950,9 +952,10 @@ When connecting to a remote listener, several options are available:
**Identity & Destination**
The default identity file for ``rnsh`` is stored at
``~/.reticulum/identities/rnsh``, but you can specify a different one with the
``-i`` option, which will be created if it does not already exist:
The default initiator identity file for ``rnsh`` is stored at
``~/.rns/identity`` (default listener identity is in ``~/.rns/identity.default``),
but you can specify a different one with the ``-i`` option, which will be created if
it does not already exist:
.. code:: text
@ -1470,6 +1473,7 @@ following content:
Restart=always
RestartSec=3
User=USERNAMEHERE
Environment=MALLOC_ARENA_MAX=2
ExecStart=rnsd --service
[Install]
@ -1511,6 +1515,7 @@ Create a user systemd service files ``~/.config/systemd/user/rnsd.service`` with
Type=simple
Restart=always
RestartSec=3
Environment=MALLOC_ARENA_MAX=2
ExecStart=RNS_BIN_DIR/rnsd --service
[Install]

View file

@ -1,5 +1,5 @@
const DOCUMENTATION_OPTIONS = {
VERSION: '1.5.7',
VERSION: '1.6.0',
LANGUAGE: 'en',
COLLAPSE_INDEX: false,
BUILDER: 'html',

View file

@ -7,7 +7,7 @@
<link rel="prefetch" href="_static/rns_logo_512.png" as="image">
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
<title>Brandolini’s Reference - Reticulum Network Stack 1.5.7 documentation</title>
<title>Brandolini’s Reference - Reticulum Network Stack 1.6.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@ -180,7 +180,7 @@
</label>
</div>
<div class="header-center">
<a href="index.html"><div class="brand">Reticulum Network Stack 1.5.7 documentation</div></a>
<a href="index.html"><div class="brand">Reticulum Network Stack 1.6.0 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
@ -204,7 +204,7 @@
<img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
</div>
<span class="sidebar-brand-text">Reticulum Network Stack 1.5.7 documentation</span>
<span class="sidebar-brand-text">Reticulum Network Stack 1.6.0 documentation</span>
</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@ -218,6 +218,7 @@
<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
<li class="toctree-l1"><a class="reference internal" href="stamps.html">Protecting Open Networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
@ -1601,7 +1602,7 @@ is where this project invested.</p></li>
</aside>
</div>
</div><script src="_static/documentation_options.js?v=2b2ec289"></script>
</div><script src="_static/documentation_options.js?v=72d88caf"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=46bd48cc"></script>

View file

@ -7,7 +7,7 @@
<link rel="prefetch" href="_static/rns_logo_512.png" as="image">
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
<title>Distributed Development - Reticulum Network Stack 1.5.7 documentation</title>
<title>Distributed Development - Reticulum Network Stack 1.6.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@ -180,7 +180,7 @@
</label>
</div>
<div class="header-center">
<a href="index.html"><div class="brand">Reticulum Network Stack 1.5.7 documentation</div></a>
<a href="index.html"><div class="brand">Reticulum Network Stack 1.6.0 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
@ -204,7 +204,7 @@
<img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
</div>
<span class="sidebar-brand-text">Reticulum Network Stack 1.5.7 documentation</span>
<span class="sidebar-brand-text">Reticulum Network Stack 1.6.0 documentation</span>
</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@ -218,6 +218,7 @@
<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
<li class="toctree-l1"><a class="reference internal" href="stamps.html">Protecting Open Networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
@ -432,7 +433,7 @@
</aside>
</div>
</div><script src="_static/documentation_options.js?v=2b2ec289"></script>
</div><script src="_static/documentation_options.js?v=72d88caf"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=46bd48cc"></script>

View file

@ -7,7 +7,7 @@
<link rel="prefetch" href="_static/rns_logo_512.png" as="image">
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
<title>Code Examples - Reticulum Network Stack 1.5.7 documentation</title>
<title>Code Examples - Reticulum Network Stack 1.6.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@ -180,7 +180,7 @@
</label>
</div>
<div class="header-center">
<a href="index.html"><div class="brand">Reticulum Network Stack 1.5.7 documentation</div></a>
<a href="index.html"><div class="brand">Reticulum Network Stack 1.6.0 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
@ -204,7 +204,7 @@
<img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
</div>
<span class="sidebar-brand-text">Reticulum Network Stack 1.5.7 documentation</span>
<span class="sidebar-brand-text">Reticulum Network Stack 1.6.0 documentation</span>
</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@ -218,6 +218,7 @@
<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
<li class="toctree-l1"><a class="reference internal" href="stamps.html">Protecting Open Networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
@ -1068,6 +1069,9 @@
<span class="s2">&quot;linkexample&quot;</span>
<span class="p">)</span>
<span class="c1"># We can optionally configure a link request stamp cost</span>
<span class="n">server_destination</span><span class="o">.</span><span class="n">set_link_cost</span><span class="p">(</span><span class="mf">14.2</span><span class="p">)</span>
<span class="c1"># We configure a function that will get called every time</span>
<span class="c1"># a new client creates a link to this destination.</span>
<span class="n">server_destination</span><span class="o">.</span><span class="n">set_link_established_callback</span><span class="p">(</span><span class="n">client_connected</span><span class="p">)</span>
@ -3649,7 +3653,7 @@
</aside>
</div>
</div><script src="_static/documentation_options.js?v=2b2ec289"></script>
</div><script src="_static/documentation_options.js?v=72d88caf"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=46bd48cc"></script>

View file

@ -7,7 +7,7 @@
<link rel="prefetch" href="_static/rns_logo_512.png" as="image">
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
<title>An Explanation of Reticulum for Human Beings - Reticulum Network Stack 1.5.7 documentation</title>
<title>An Explanation of Reticulum for Human Beings - Reticulum Network Stack 1.6.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@ -180,7 +180,7 @@
</label>
</div>
<div class="header-center">
<a href="index.html"><div class="brand">Reticulum Network Stack 1.5.7 documentation</div></a>
<a href="index.html"><div class="brand">Reticulum Network Stack 1.6.0 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
@ -204,7 +204,7 @@
<img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
</div>
<span class="sidebar-brand-text">Reticulum Network Stack 1.5.7 documentation</span>
<span class="sidebar-brand-text">Reticulum Network Stack 1.6.0 documentation</span>
</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@ -218,6 +218,7 @@
<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
<li class="toctree-l1"><a class="reference internal" href="stamps.html">Protecting Open Networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
@ -297,7 +298,7 @@
</aside>
</div>
</div><script src="_static/documentation_options.js?v=2b2ec289"></script>
</div><script src="_static/documentation_options.js?v=72d88caf"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=46bd48cc"></script>

View file

@ -5,7 +5,7 @@
<meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="#"><link rel="search" title="Search" href="search.html">
<link rel="prefetch" href="_static/rns_logo_512.png" as="image">
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 --><title>Index - Reticulum Network Stack 1.5.7 documentation</title>
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 --><title>Index - Reticulum Network Stack 1.6.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@ -178,7 +178,7 @@
</label>
</div>
<div class="header-center">
<a href="index.html"><div class="brand">Reticulum Network Stack 1.5.7 documentation</div></a>
<a href="index.html"><div class="brand">Reticulum Network Stack 1.6.0 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
@ -202,7 +202,7 @@
<img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
</div>
<span class="sidebar-brand-text">Reticulum Network Stack 1.5.7 documentation</span>
<span class="sidebar-brand-text">Reticulum Network Stack 1.6.0 documentation</span>
</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@ -216,6 +216,7 @@
<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
<li class="toctree-l1"><a class="reference internal" href="stamps.html">Protecting Open Networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
@ -443,6 +444,8 @@
<li><a href="reference.html#RNS.Resource.get_hash">get_hash() (RNS.Resource method)</a>
</li>
<li><a href="reference.html#RNS.Reticulum.get_instance">get_instance() (RNS.Reticulum static method)</a>
</li>
<li><a href="reference.html#RNS.Destination.get_link_cost">get_link_cost() (RNS.Destination method)</a>
</li>
<li><a href="reference.html#RNS.Reticulum.get_lowest_interface_bitrate">get_lowest_interface_bitrate() (RNS.Reticulum method)</a>
</li>
@ -511,6 +514,8 @@
</li>
</ul></li>
<li><a href="reference.html#RNS.Resource.get_transfer_size">get_transfer_size() (RNS.Resource method)</a>
</li>
<li><a href="reference.html#RNS.Identity.get_value">get_value() (RNS.Identity method)</a>
</li>
</ul></td>
</tr></table>
@ -680,12 +685,16 @@
</li>
<li><a href="reference.html#RNS.Identity.recall_app_data">recall_app_data() (RNS.Identity static method)</a>
</li>
<li><a href="reference.html#RNS.Transport.register_announce_handler">register_announce_handler() (RNS.Transport static method)</a>
<li><a href="reference.html#RNS.Identity.recall_link_cost">recall_link_cost() (RNS.Identity static method)</a>
</li>
<li><a href="reference.html#RNS.Channel.Channel.register_message_type">register_message_type() (RNS.Channel.Channel method)</a>
<li><a href="reference.html#RNS.Identity.recall_stamp_value">recall_stamp_value() (RNS.Identity static method)</a>
</li>
<li><a href="reference.html#RNS.Transport.register_announce_handler">register_announce_handler() (RNS.Transport static method)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="reference.html#RNS.Channel.Channel.register_message_type">register_message_type() (RNS.Channel.Channel method)</a>
</li>
<li><a href="reference.html#RNS.Destination.register_request_handler">register_request_handler() (RNS.Destination method)</a>
</li>
<li><a href="reference.html#RNS.Reticulum.remote_management_enabled">remote_management_enabled() (RNS.Reticulum static method)</a>
@ -727,6 +736,8 @@
<li><a href="reference.html#RNS.PacketReceipt.set_delivery_callback">set_delivery_callback() (RNS.PacketReceipt method)</a>
</li>
<li><a href="reference.html#RNS.Link.set_link_closed_callback">set_link_closed_callback() (RNS.Link method)</a>
</li>
<li><a href="reference.html#RNS.Destination.set_link_cost">set_link_cost() (RNS.Destination method)</a>
</li>
<li><a href="reference.html#RNS.Destination.set_link_established_callback">set_link_established_callback() (RNS.Destination method)</a>
</li>
@ -761,6 +772,8 @@
<li><a href="reference.html#RNS.PacketReceipt.set_timeout">set_timeout() (RNS.PacketReceipt method)</a>
</li>
<li><a href="reference.html#RNS.PacketReceipt.set_timeout_callback">set_timeout_callback() (RNS.PacketReceipt method)</a>
</li>
<li><a href="reference.html#RNS.Destination.set_value">set_value() (RNS.Destination method)</a>
</li>
<li><a href="reference.html#RNS.Reticulum.should_use_implicit_proof">should_use_implicit_proof() (RNS.Reticulum static method)</a>
</li>
@ -857,7 +870,7 @@
</aside>
</div>
</div><script src="_static/documentation_options.js?v=2b2ec289"></script>
</div><script src="_static/documentation_options.js?v=72d88caf"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=46bd48cc"></script>

View file

@ -7,7 +7,7 @@
<link rel="prefetch" href="_static/rns_logo_512.png" as="image">
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
<title>Getting Started Fast - Reticulum Network Stack 1.5.7 documentation</title>
<title>Getting Started Fast - Reticulum Network Stack 1.6.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@ -180,7 +180,7 @@
</label>
</div>
<div class="header-center">
<a href="index.html"><div class="brand">Reticulum Network Stack 1.5.7 documentation</div></a>
<a href="index.html"><div class="brand">Reticulum Network Stack 1.6.0 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
@ -204,7 +204,7 @@
<img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
</div>
<span class="sidebar-brand-text">Reticulum Network Stack 1.5.7 documentation</span>
<span class="sidebar-brand-text">Reticulum Network Stack 1.6.0 documentation</span>
</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@ -218,6 +218,7 @@
<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
<li class="toctree-l1"><a class="reference internal" href="stamps.html">Protecting Open Networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
@ -777,7 +778,7 @@ section of this manual.</p>
</aside>
</div>
</div><script src="_static/documentation_options.js?v=2b2ec289"></script>
</div><script src="_static/documentation_options.js?v=72d88caf"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=46bd48cc"></script>

View file

@ -7,7 +7,7 @@
<link rel="prefetch" href="_static/rns_logo_512.png" as="image">
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
<title>Git Over Reticulum - Reticulum Network Stack 1.5.7 documentation</title>
<title>Git Over Reticulum - Reticulum Network Stack 1.6.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@ -180,7 +180,7 @@
</label>
</div>
<div class="header-center">
<a href="index.html"><div class="brand">Reticulum Network Stack 1.5.7 documentation</div></a>
<a href="index.html"><div class="brand">Reticulum Network Stack 1.6.0 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
@ -204,7 +204,7 @@
<img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
</div>
<span class="sidebar-brand-text">Reticulum Network Stack 1.5.7 documentation</span>
<span class="sidebar-brand-text">Reticulum Network Stack 1.6.0 documentation</span>
</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@ -218,6 +218,7 @@
<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
<li class="toctree-l1"><a class="reference internal" href="stamps.html">Protecting Open Networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
@ -1601,7 +1602,7 @@ done
</aside>
</div>
</div><script src="_static/documentation_options.js?v=2b2ec289"></script>
</div><script src="_static/documentation_options.js?v=72d88caf"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=46bd48cc"></script>

View file

@ -7,7 +7,7 @@
<link rel="prefetch" href="_static/rns_logo_512.png" as="image">
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
<title>Communications Hardware - Reticulum Network Stack 1.5.7 documentation</title>
<title>Communications Hardware - Reticulum Network Stack 1.6.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@ -180,7 +180,7 @@
</label>
</div>
<div class="header-center">
<a href="index.html"><div class="brand">Reticulum Network Stack 1.5.7 documentation</div></a>
<a href="index.html"><div class="brand">Reticulum Network Stack 1.6.0 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
@ -204,7 +204,7 @@
<img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
</div>
<span class="sidebar-brand-text">Reticulum Network Stack 1.5.7 documentation</span>
<span class="sidebar-brand-text">Reticulum Network Stack 1.6.0 documentation</span>
</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@ -218,6 +218,7 @@
<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
<li class="toctree-l1"><a class="reference internal" href="stamps.html">Protecting Open Networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
@ -677,7 +678,7 @@ can be used with Reticulum. This includes virtual software modems such as
</aside>
</div>
</div><script src="_static/documentation_options.js?v=2b2ec289"></script>
</div><script src="_static/documentation_options.js?v=72d88caf"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=46bd48cc"></script>

View file

@ -7,7 +7,7 @@
<link rel="prefetch" href="_static/rns_logo_512.png" as="image">
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
<title>Reticulum Network Stack 1.5.7 documentation</title>
<title>Reticulum Network Stack 1.6.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@ -180,7 +180,7 @@
</label>
</div>
<div class="header-center">
<a href="#"><div class="brand">Reticulum Network Stack 1.5.7 documentation</div></a>
<a href="#"><div class="brand">Reticulum Network Stack 1.6.0 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
@ -204,7 +204,7 @@
<img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
</div>
<span class="sidebar-brand-text">Reticulum Network Stack 1.5.7 documentation</span>
<span class="sidebar-brand-text">Reticulum Network Stack 1.6.0 documentation</span>
</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@ -218,6 +218,7 @@
<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
<li class="toctree-l1"><a class="reference internal" href="stamps.html">Protecting Open Networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
@ -452,6 +453,18 @@ to participate in the development of Reticulum itself.</p>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="stamps.html">Protecting Open Networks</a><ul>
<li class="toctree-l2"><a class="reference internal" href="stamps.html#cryptographic-stamps">Cryptographic Stamps</a><ul>
<li class="toctree-l3"><a class="reference internal" href="stamps.html#base-primitives">Base Primitives</a></li>
<li class="toctree-l3"><a class="reference internal" href="stamps.html#on-network-types">On-Network Types</a></li>
<li class="toctree-l3"><a class="reference internal" href="stamps.html#configuring-stamps">Configuring Stamps</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="stamps.html#filtering-qos">Filtering &amp; QoS</a></li>
<li class="toctree-l2"><a class="reference internal" href="stamps.html#blackhole-management">Blackhole Management</a></li>
<li class="toctree-l2"><a class="reference internal" href="stamps.html#ingress-burst-control">Ingress &amp; Burst Control</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a><ul>
<li class="toctree-l2"><a class="reference internal" href="understanding.html#motivation">Motivation</a></li>
<li class="toctree-l2"><a class="reference internal" href="understanding.html#goals">Goals</a></li>
@ -830,7 +843,7 @@ to participate in the development of Reticulum itself.</p>
</aside>
</div>
</div><script src="_static/documentation_options.js?v=2b2ec289"></script>
</div><script src="_static/documentation_options.js?v=72d88caf"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=46bd48cc"></script>

View file

@ -7,7 +7,7 @@
<link rel="prefetch" href="_static/rns_logo_512.png" as="image">
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
<title>Configuring Interfaces - Reticulum Network Stack 1.5.7 documentation</title>
<title>Configuring Interfaces - Reticulum Network Stack 1.6.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@ -180,7 +180,7 @@
</label>
</div>
<div class="header-center">
<a href="index.html"><div class="brand">Reticulum Network Stack 1.5.7 documentation</div></a>
<a href="index.html"><div class="brand">Reticulum Network Stack 1.6.0 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
@ -204,7 +204,7 @@
<img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
</div>
<span class="sidebar-brand-text">Reticulum Network Stack 1.5.7 documentation</span>
<span class="sidebar-brand-text">Reticulum Network Stack 1.6.0 documentation</span>
</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@ -218,6 +218,7 @@
<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
<li class="toctree-l1"><a class="reference internal" href="stamps.html">Protecting Open Networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Configuring Interfaces</a></li>
@ -1127,13 +1128,6 @@ relevant regulation for your location, and to make decisions accordingly.</p>
<span id="interfaces-discoverable"></span><h2>Discoverable Interfaces<a class="headerlink" href="#discoverable-interfaces" title="Link to this heading"></a></h2>
<p>Reticulum includes a powerful system for publishing your local interfaces to the wider network, allowing other peers to <a class="reference internal" href="using.html#using-interface-discovery"><span class="std std-ref">discover, validate, and automatically connect to them</span></a>. This feature is particularly useful for creating decentralized networks where peers can dynamically find entrypoints, such as public Internet gateways or local radio access points, without relying on static configuration files or centralized directories.</p>
<p>When an interface is made <strong>discoverable</strong>, your Reticulum instance will periodically broadcast an announce packet containing the connection details and parameters required for other peers to establish a connection. These announces are propagated over the network using the standard Reticulum announce mechanism using the <code class="docutils literal notranslate"><span class="pre">rnstransport.discovery.interface</span></code> destination type.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>To use the interface discovery functionality, the <code class="docutils literal notranslate"><span class="pre">LXMF</span></code> module must be installed in your Python environment. You can install it using pip:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>lxmf
</pre></div>
</div>
</div>
<section id="enabling-discovery">
<h3>Enabling Discovery<a class="headerlink" href="#enabling-discovery" title="Link to this heading"></a></h3>
<p>Interface discovery is enabled on a per-interface basis. To make a specific interface discoverable, you must add the <code class="docutils literal notranslate"><span class="pre">discoverable</span></code> option to that interface’s configuration block and set it to <code class="docutils literal notranslate"><span class="pre">yes</span></code>.</p>
@ -1909,7 +1903,7 @@ queue. Defaults to <code class="docutils literal notranslate"><span class="pre">
</aside>
</div>
</div><script src="_static/documentation_options.js?v=2b2ec289"></script>
</div><script src="_static/documentation_options.js?v=72d88caf"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=46bd48cc"></script>

View file

@ -7,7 +7,7 @@
<link rel="prefetch" href="_static/rns_logo_512.png" as="image">
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
<title>Reticulum License - Reticulum Network Stack 1.5.7 documentation</title>
<title>Reticulum License - Reticulum Network Stack 1.6.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@ -180,7 +180,7 @@
</label>
</div>
<div class="header-center">
<a href="index.html"><div class="brand">Reticulum Network Stack 1.5.7 documentation</div></a>
<a href="index.html"><div class="brand">Reticulum Network Stack 1.6.0 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
@ -204,7 +204,7 @@
<img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
</div>
<span class="sidebar-brand-text">Reticulum Network Stack 1.5.7 documentation</span>
<span class="sidebar-brand-text">Reticulum Network Stack 1.6.0 documentation</span>
</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@ -218,6 +218,7 @@
<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
<li class="toctree-l1"><a class="reference internal" href="stamps.html">Protecting Open Networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
@ -346,7 +347,7 @@ SOFTWARE.
</aside>
</div>
</div><script src="_static/documentation_options.js?v=2b2ec289"></script>
</div><script src="_static/documentation_options.js?v=72d88caf"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=46bd48cc"></script>

View file

@ -7,7 +7,7 @@
<link rel="prefetch" href="_static/rns_logo_512.png" as="image">
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
<title>Building Networks - Reticulum Network Stack 1.5.7 documentation</title>
<title>Building Networks - Reticulum Network Stack 1.6.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@ -180,7 +180,7 @@
</label>
</div>
<div class="header-center">
<a href="index.html"><div class="brand">Reticulum Network Stack 1.5.7 documentation</div></a>
<a href="index.html"><div class="brand">Reticulum Network Stack 1.6.0 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
@ -204,7 +204,7 @@
<img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
</div>
<span class="sidebar-brand-text">Reticulum Network Stack 1.5.7 documentation</span>
<span class="sidebar-brand-text">Reticulum Network Stack 1.6.0 documentation</span>
</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@ -218,6 +218,7 @@
<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
<li class="toctree-l1"><a class="reference internal" href="stamps.html">Protecting Open Networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
@ -665,7 +666,7 @@ differently than a mobile device roaming between radio cells.</p>
</aside>
</div>
</div><script src="_static/documentation_options.js?v=2b2ec289"></script>
</div><script src="_static/documentation_options.js?v=72d88caf"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=46bd48cc"></script>

Binary file not shown.

View file

@ -7,7 +7,7 @@
<link rel="prefetch" href="_static/rns_logo_512.png" as="image">
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
<title>API Reference - Reticulum Network Stack 1.5.7 documentation</title>
<title>API Reference - Reticulum Network Stack 1.6.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@ -180,7 +180,7 @@
</label>
</div>
<div class="header-center">
<a href="index.html"><div class="brand">Reticulum Network Stack 1.5.7 documentation</div></a>
<a href="index.html"><div class="brand">Reticulum Network Stack 1.6.0 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
@ -204,7 +204,7 @@
<img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
</div>
<span class="sidebar-brand-text">Reticulum Network Stack 1.5.7 documentation</span>
<span class="sidebar-brand-text">Reticulum Network Stack 1.6.0 documentation</span>
</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@ -218,6 +218,7 @@
<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
<li class="toctree-l1"><a class="reference internal" href="stamps.html">Protecting Open Networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
@ -270,7 +271,7 @@ This chapter lists and explains all classes exposed by the Reticulum Network Sta
<p id="api-reticulum"><h3> Reticulum </h3></p>
<dl class="py class">
<dt class="sig sig-object py" id="RNS.Reticulum">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">RNS.</span></span><span class="sig-name descname"><span class="pre">Reticulum</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">configdir</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">loglevel</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">logdest</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">verbosity</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">require_shared_instance</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">shared_instance_type</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Reticulum" title="Link to this definition"></a></dt>
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">RNS.</span></span><span class="sig-name descname"><span class="pre">Reticulum</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">configdir</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">loglevel</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">logdest</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">verbosity</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">require_shared_instance</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">shared_instance_type</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">enable_stamping</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">enforce_stamps</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Reticulum" title="Link to this definition"></a></dt>
<dd><p>This class is used to initialise access to Reticulum within a
program. You must create exactly one instance of this class before
carrying out any other RNS operations, such as creating destinations
@ -453,7 +454,7 @@ can remotely query and manage this instance.</p>
to be considered valid and remembered.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>The required stamp value as an integer.</p>
<dd class="field-odd"><p>The required stamp value as a float.</p>
</dd>
</dl>
</dd></dl>
@ -510,7 +511,7 @@ interfaces are discovered.</p>
<p id="api-identity"><h3> Identity </h3></p>
<dl class="py class">
<dt class="sig sig-object py" id="RNS.Identity">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">RNS.</span></span><span class="sig-name descname"><span class="pre">Identity</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">create_keys</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Identity" title="Link to this definition"></a></dt>
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">RNS.</span></span><span class="sig-name descname"><span class="pre">Identity</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">create_keys</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Identity" title="Link to this definition"></a></dt>
<dd><p>This class is used to manage identities in Reticulum. It provides methods
for encryption, decryption, signatures and verification, and is the basis
for all encrypted communication over Reticulum networks.</p>
@ -588,6 +589,34 @@ search for an identity from a known <em>identity hash</em>, by setting the
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="RNS.Identity.recall_stamp_value">
<em class="property"><span class="k"><span class="pre">static</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">recall_stamp_value</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">destination_hash</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Identity.recall_stamp_value" title="Link to this definition"></a></dt>
<dd><p>Recall last heard announce stamp value for a destination hash.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>destination_hash</strong> – Destination hash as <em>bytes</em>.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><em>Float</em>, or <em>None</em> if the destination is unknown.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="RNS.Identity.recall_link_cost">
<em class="property"><span class="k"><span class="pre">static</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">recall_link_cost</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">destination_hash</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Identity.recall_link_cost" title="Link to this definition"></a></dt>
<dd><p>Recall the link request stamp cost announced by a destination.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>destination_hash</strong> – Destination hash as <em>bytes</em>.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><em>Float</em>, or <em>None</em> if the destination is unknown or has not announced a cost.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="RNS.Identity.full_hash">
<em class="property"><span class="k"><span class="pre">static</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">full_hash</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Identity.full_hash" title="Link to this definition"></a></dt>
@ -704,6 +733,16 @@ communication for the identity. Be very careful with this method.</p>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="RNS.Identity.get_value">
<span class="sig-name descname"><span class="pre">get_value</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Identity.get_value" title="Link to this definition"></a></dt>
<dd><dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>The stamp value of this identity as a <em>float</em></p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="RNS.Identity.get_private_key">
<span class="sig-name descname"><span class="pre">get_private_key</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Identity.get_private_key" title="Link to this definition"></a></dt>
@ -913,6 +952,41 @@ relevant interfaces. Application specific data can be added to the announce.</p>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="RNS.Destination.set_value">
<span class="sig-name descname"><span class="pre">set_value</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Destination.set_value" title="Link to this definition"></a></dt>
<dd><p>Sets the target stamp value for this destination.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>value</strong> – The target value as a <em>float</em>.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="RNS.Destination.set_link_cost">
<span class="sig-name descname"><span class="pre">set_link_cost</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">cost</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Destination.set_link_cost" title="Link to this definition"></a></dt>
<dd><p>Sets the required link establishment stamp cost for this destination. Set to 0 to disable.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>cost</strong> – The required cost as a <em>float</em>.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="RNS.Destination.get_link_cost">
<span class="sig-name descname"><span class="pre">get_link_cost</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Destination.get_link_cost" title="Link to this definition"></a></dt>
<dd><p>Returns the link request stamp cost to be announced for this
destination, as a float. If no destination-specific cost has
been set, the default link request cost is returned.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>The announced link request cost as a <em>float</em>.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="RNS.Destination.accepts_links">
<span class="sig-name descname"><span class="pre">accepts_links</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">accepts</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Destination.accepts_links" title="Link to this definition"></a></dt>
@ -2285,7 +2359,7 @@ blocks until the path is available, or the timeout is reached.</p>
<dl class="py method">
<dt class="sig sig-object py" id="RNS.Transport.request_path">
<em class="property"><span class="k"><span class="pre">static</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">request_path</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">destination_hash</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">on_interface</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tag</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">recursive</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Transport.request_path" title="Link to this definition"></a></dt>
<em class="property"><span class="k"><span class="pre">static</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">request_path</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">destination_hash</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">on_interface</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tag</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">recursive</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">ext_payload</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Transport.request_path" title="Link to this definition"></a></dt>
<dd><p>Requests a path to the destination from the network. If
another reachable peer on the network knows a path, it
will announce it.</p>
@ -2294,6 +2368,7 @@ will announce it.</p>
<dd class="field-odd"><ul class="simple">
<li><p><strong>destination_hash</strong> – A destination hash as <em>bytes</em>.</p></li>
<li><p><strong>on_interface</strong> – If specified, the path request will only be sent on this interface. In normal use, Reticulum handles this automatically, and this parameter should not be used.</p></li>
<li><p><strong>ext_payload</strong> – Internal use by <a class="reference internal" href="#api-transport"><span class="std std-ref">RNS.Transport</span></a>. Ignore.</p></li>
</ul>
</dd>
</dl>
@ -2411,6 +2486,8 @@ will announce it.</p>
<li><a class="reference internal" href="#RNS.Identity.TRUNCATED_HASHLENGTH"><code class="docutils literal notranslate"><span class="pre">TRUNCATED_HASHLENGTH</span></code></a></li>
<li><a class="reference internal" href="#RNS.Identity.recall"><code class="docutils literal notranslate"><span class="pre">recall()</span></code></a></li>
<li><a class="reference internal" href="#RNS.Identity.recall_app_data"><code class="docutils literal notranslate"><span class="pre">recall_app_data()</span></code></a></li>
<li><a class="reference internal" href="#RNS.Identity.recall_stamp_value"><code class="docutils literal notranslate"><span class="pre">recall_stamp_value()</span></code></a></li>
<li><a class="reference internal" href="#RNS.Identity.recall_link_cost"><code class="docutils literal notranslate"><span class="pre">recall_link_cost()</span></code></a></li>
<li><a class="reference internal" href="#RNS.Identity.full_hash"><code class="docutils literal notranslate"><span class="pre">full_hash()</span></code></a></li>
<li><a class="reference internal" href="#RNS.Identity.truncated_hash"><code class="docutils literal notranslate"><span class="pre">truncated_hash()</span></code></a></li>
<li><a class="reference internal" href="#RNS.Identity.get_random_hash"><code class="docutils literal notranslate"><span class="pre">get_random_hash()</span></code></a></li>
@ -2419,6 +2496,7 @@ will announce it.</p>
<li><a class="reference internal" href="#RNS.Identity.from_file"><code class="docutils literal notranslate"><span class="pre">from_file()</span></code></a></li>
<li><a class="reference internal" href="#RNS.Identity.to_file"><code class="docutils literal notranslate"><span class="pre">to_file()</span></code></a></li>
<li><a class="reference internal" href="#RNS.Identity.pub_to_file"><code class="docutils literal notranslate"><span class="pre">pub_to_file()</span></code></a></li>
<li><a class="reference internal" href="#RNS.Identity.get_value"><code class="docutils literal notranslate"><span class="pre">get_value()</span></code></a></li>
<li><a class="reference internal" href="#RNS.Identity.get_private_key"><code class="docutils literal notranslate"><span class="pre">get_private_key()</span></code></a></li>
<li><a class="reference internal" href="#RNS.Identity.get_public_key"><code class="docutils literal notranslate"><span class="pre">get_public_key()</span></code></a></li>
<li><a class="reference internal" href="#RNS.Identity.load_private_key"><code class="docutils literal notranslate"><span class="pre">load_private_key()</span></code></a></li>
@ -2437,6 +2515,9 @@ will announce it.</p>
<li><a class="reference internal" href="#RNS.Destination.hash_from_name_and_identity"><code class="docutils literal notranslate"><span class="pre">hash_from_name_and_identity()</span></code></a></li>
<li><a class="reference internal" href="#RNS.Destination.hash"><code class="docutils literal notranslate"><span class="pre">hash()</span></code></a></li>
<li><a class="reference internal" href="#RNS.Destination.announce"><code class="docutils literal notranslate"><span class="pre">announce()</span></code></a></li>
<li><a class="reference internal" href="#RNS.Destination.set_value"><code class="docutils literal notranslate"><span class="pre">set_value()</span></code></a></li>
<li><a class="reference internal" href="#RNS.Destination.set_link_cost"><code class="docutils literal notranslate"><span class="pre">set_link_cost()</span></code></a></li>
<li><a class="reference internal" href="#RNS.Destination.get_link_cost"><code class="docutils literal notranslate"><span class="pre">get_link_cost()</span></code></a></li>
<li><a class="reference internal" href="#RNS.Destination.accepts_links"><code class="docutils literal notranslate"><span class="pre">accepts_links()</span></code></a></li>
<li><a class="reference internal" href="#RNS.Destination.set_link_established_callback"><code class="docutils literal notranslate"><span class="pre">set_link_established_callback()</span></code></a></li>
<li><a class="reference internal" href="#RNS.Destination.set_packet_callback"><code class="docutils literal notranslate"><span class="pre">set_packet_callback()</span></code></a></li>
@ -2589,7 +2670,7 @@ will announce it.</p>
</aside>
</div>
</div><script src="_static/documentation_options.js?v=2b2ec289"></script>
</div><script src="_static/documentation_options.js?v=72d88caf"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=46bd48cc"></script>

View file

@ -8,7 +8,7 @@
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
<meta name="robots" content="noindex" />
<title>Search - Reticulum Network Stack 1.5.7 documentation</title><link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<title>Search - Reticulum Network Stack 1.6.0 documentation</title><link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo-extensions.css?v=8dab3a3b" />
@ -180,7 +180,7 @@
</label>
</div>
<div class="header-center">
<a href="index.html"><div class="brand">Reticulum Network Stack 1.5.7 documentation</div></a>
<a href="index.html"><div class="brand">Reticulum Network Stack 1.6.0 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
@ -204,7 +204,7 @@
<img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
</div>
<span class="sidebar-brand-text">Reticulum Network Stack 1.5.7 documentation</span>
<span class="sidebar-brand-text">Reticulum Network Stack 1.6.0 documentation</span>
</a><form class="sidebar-search-container" method="get" action="#" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@ -218,6 +218,7 @@
<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
<li class="toctree-l1"><a class="reference internal" href="stamps.html">Protecting Open Networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
@ -305,7 +306,7 @@
</aside>
</div>
</div><script src="_static/documentation_options.js?v=2b2ec289"></script>
</div><script src="_static/documentation_options.js?v=72d88caf"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=46bd48cc"></script>

File diff suppressed because one or more lines are too long

View file

@ -7,7 +7,7 @@
<link rel="prefetch" href="_static/rns_logo_512.png" as="image">
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
<title>Programs Using Reticulum - Reticulum Network Stack 1.5.7 documentation</title>
<title>Programs Using Reticulum - Reticulum Network Stack 1.6.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@ -180,7 +180,7 @@
</label>
</div>
<div class="header-center">
<a href="index.html"><div class="brand">Reticulum Network Stack 1.5.7 documentation</div></a>
<a href="index.html"><div class="brand">Reticulum Network Stack 1.6.0 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
@ -204,7 +204,7 @@
<img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
</div>
<span class="sidebar-brand-text">Reticulum Network Stack 1.5.7 documentation</span>
<span class="sidebar-brand-text">Reticulum Network Stack 1.6.0 documentation</span>
</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@ -218,6 +218,7 @@
<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Programs Using Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
<li class="toctree-l1"><a class="reference internal" href="stamps.html">Protecting Open Networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
@ -594,7 +595,7 @@ when link throughput is counted in a few hundreds of bits per second.</p>
</aside>
</div>
</div><script src="_static/documentation_options.js?v=2b2ec289"></script>
</div><script src="_static/documentation_options.js?v=72d88caf"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=46bd48cc"></script>

593
docs/manual/stamps.html Normal file
View file

@ -0,0 +1,593 @@
<!doctype html>
<html class="no-js" lang="en" data-content_root="./">
<head><meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="next" title="Understanding Reticulum" href="understanding.html"><link rel="prev" title="Using Reticulum on Your System" href="using.html">
<link rel="prefetch" href="_static/rns_logo_512.png" as="image">
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
<title>Protecting Open Networks - Reticulum Network Stack 1.6.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo-extensions.css?v=8dab3a3b" />
<link rel="stylesheet" type="text/css" href="_static/custom.css?v=e1715074" />
<style>
body {
--color-code-background: #f2f2f2;
--color-code-foreground: #1e1e1e;
}
@media not print {
body[data-theme="dark"] {
--color-code-background: #202020;
--color-code-foreground: #d0d0d0;
--color-background-primary: #202b38;
--color-background-secondary: #161f27;
--color-foreground-primary: #dbdbdb;
--color-foreground-secondary: #a9b1ba;
--color-brand-primary: #41adff;
--color-background-hover: #161f27;
--color-api-name: #ffbe85;
--color-api-pre-name: #efae75;
}
@media (prefers-color-scheme: dark) {
body:not([data-theme="light"]) {
--color-code-background: #202020;
--color-code-foreground: #d0d0d0;
--color-background-primary: #202b38;
--color-background-secondary: #161f27;
--color-foreground-primary: #dbdbdb;
--color-foreground-secondary: #a9b1ba;
--color-brand-primary: #41adff;
--color-background-hover: #161f27;
--color-api-name: #ffbe85;
--color-api-pre-name: #efae75;
}
}
}
</style></head>
<body>
<script>
document.body.dataset.theme = localStorage.getItem("theme") || "auto";
</script>
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
<symbol id="svg-toc" viewBox="0 0 24 24">
<title>Contents</title>
<svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024">
<path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/>
</svg>
</symbol>
<symbol id="svg-menu" viewBox="0 0 24 24">
<title>Menu</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu">
<line x1="3" y1="12" x2="21" y2="12"></line>
<line x1="3" y1="6" x2="21" y2="6"></line>
<line x1="3" y1="18" x2="21" y2="18"></line>
</svg>
</symbol>
<symbol id="svg-arrow-right" viewBox="0 0 24 24">
<title>Expand</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right">
<polyline points="9 18 15 12 9 6"></polyline>
</svg>
</symbol>
<symbol id="svg-sun" viewBox="0 0 24 24">
<title>Light mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="feather-sun">
<circle cx="12" cy="12" r="5"></circle>
<line x1="12" y1="1" x2="12" y2="3"></line>
<line x1="12" y1="21" x2="12" y2="23"></line>
<line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
<line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
<line x1="1" y1="12" x2="3" y2="12"></line>
<line x1="21" y1="12" x2="23" y2="12"></line>
<line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
<line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
</svg>
</symbol>
<symbol id="svg-moon" viewBox="0 0 24 24">
<title>Dark mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon">
<path stroke="none" d="M0 0h24v24H0z" fill="none" />
<path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" />
</svg>
</symbol>
<symbol id="svg-sun-with-moon" viewBox="0 0 24 24">
<title>Auto light/dark, in light mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1" stroke-linecap="round" stroke-linejoin="round"
class="icon-custom-derived-from-feather-sun-and-tabler-moon">
<path style="opacity: 50%" d="M 5.411 14.504 C 5.471 14.504 5.532 14.504 5.591 14.504 C 3.639 16.319 4.383 19.569 6.931 20.352 C 7.693 20.586 8.512 20.551 9.25 20.252 C 8.023 23.207 4.056 23.725 2.11 21.184 C 0.166 18.642 1.702 14.949 4.874 14.536 C 5.051 14.512 5.231 14.5 5.411 14.5 L 5.411 14.504 Z"/>
<line x1="14.5" y1="3.25" x2="14.5" y2="1.25"/>
<line x1="14.5" y1="15.85" x2="14.5" y2="17.85"/>
<line x1="10.044" y1="5.094" x2="8.63" y2="3.68"/>
<line x1="19" y1="14.05" x2="20.414" y2="15.464"/>
<line x1="8.2" y1="9.55" x2="6.2" y2="9.55"/>
<line x1="20.8" y1="9.55" x2="22.8" y2="9.55"/>
<line x1="10.044" y1="14.006" x2="8.63" y2="15.42"/>
<line x1="19" y1="5.05" x2="20.414" y2="3.636"/>
<circle cx="14.5" cy="9.55" r="3.6"/>
</svg>
</symbol>
<symbol id="svg-moon-with-sun" viewBox="0 0 24 24">
<title>Auto light/dark, in dark mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1" stroke-linecap="round" stroke-linejoin="round"
class="icon-custom-derived-from-feather-sun-and-tabler-moon">
<path d="M 8.282 7.007 C 8.385 7.007 8.494 7.007 8.595 7.007 C 5.18 10.184 6.481 15.869 10.942 17.24 C 12.275 17.648 13.706 17.589 15 17.066 C 12.851 22.236 5.91 23.143 2.505 18.696 C -0.897 14.249 1.791 7.786 7.342 7.063 C 7.652 7.021 7.965 7 8.282 7 L 8.282 7.007 Z"/>
<line style="opacity: 50%" x1="18" y1="3.705" x2="18" y2="2.5"/>
<line style="opacity: 50%" x1="18" y1="11.295" x2="18" y2="12.5"/>
<line style="opacity: 50%" x1="15.316" y1="4.816" x2="14.464" y2="3.964"/>
<line style="opacity: 50%" x1="20.711" y1="10.212" x2="21.563" y2="11.063"/>
<line style="opacity: 50%" x1="14.205" y1="7.5" x2="13.001" y2="7.5"/>
<line style="opacity: 50%" x1="21.795" y1="7.5" x2="23" y2="7.5"/>
<line style="opacity: 50%" x1="15.316" y1="10.184" x2="14.464" y2="11.036"/>
<line style="opacity: 50%" x1="20.711" y1="4.789" x2="21.563" y2="3.937"/>
<circle style="opacity: 50%" cx="18" cy="7.5" r="2.169"/>
</svg>
</symbol>
<symbol id="svg-pencil" viewBox="0 0 24 24">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-pencil-code">
<path d="M4 20h4l10.5 -10.5a2.828 2.828 0 1 0 -4 -4l-10.5 10.5v4" />
<path d="M13.5 6.5l4 4" />
<path d="M20 21l2 -2l-2 -2" />
<path d="M17 17l-2 2l2 2" />
</svg>
</symbol>
<symbol id="svg-eye" viewBox="0 0 24 24">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-eye-code">
<path stroke="none" d="M0 0h24v24H0z" fill="none" />
<path d="M10 12a2 2 0 1 0 4 0a2 2 0 0 0 -4 0" />
<path
d="M11.11 17.958c-3.209 -.307 -5.91 -2.293 -8.11 -5.958c2.4 -4 5.4 -6 9 -6c3.6 0 6.6 2 9 6c-.21 .352 -.427 .688 -.647 1.008" />
<path d="M20 21l2 -2l-2 -2" />
<path d="M17 17l-2 2l2 2" />
</svg>
</symbol>
</svg>
<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation" aria-label="Toggle site navigation sidebar">
<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc" aria-label="Toggle table of contents sidebar">
<label class="overlay sidebar-overlay" for="__navigation"></label>
<label class="overlay toc-overlay" for="__toc"></label>
<a class="skip-to-content muted-link" href="#furo-main-content">Skip to content</a>
<div class="page">
<header class="mobile-header">
<div class="header-left">
<label class="nav-overlay-icon" for="__navigation">
<span class="icon"><svg><use href="#svg-menu"></use></svg></span>
</label>
</div>
<div class="header-center">
<a href="index.html"><div class="brand">Reticulum Network Stack 1.6.0 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
<button class="theme-toggle" aria-label="Toggle Light / Dark / Auto color theme">
<svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg>
<svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg>
<svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
<svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
</button>
</div>
<label class="toc-overlay-icon toc-header-icon" for="__toc">
<span class="icon"><svg><use href="#svg-toc"></use></svg></span>
</label>
</div>
</header>
<aside class="sidebar-drawer">
<div class="sidebar-container">
<div class="sidebar-sticky"><a class="sidebar-brand" href="index.html">
<div class="sidebar-logo-container">
<img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
</div>
<span class="sidebar-brand-text">Reticulum Network Stack 1.6.0 documentation</span>
</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
<input type="hidden" name="check_keywords" value="yes">
<input type="hidden" name="area" value="default">
</form>
<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li>
<li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li>
<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Protecting Open Networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
<li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="distributed.html">Distributed Development</a></li>
<li class="toctree-l1"><a class="reference internal" href="git.html">Git Over Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li>
<li class="toctree-l1"><a class="reference internal" href="brandolinis.html">Brandolini’s Reference</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
</ul>
</div>
</div>
</div>
</div>
</aside>
<div class="main">
<div class="content">
<div class="article-container">
<a href="#" class="back-to-top muted-link">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
<path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path>
</svg>
<span>Back to top</span>
</a>
<div class="content-icon-container">
<div class="theme-toggle-container theme-toggle-content">
<button class="theme-toggle" aria-label="Toggle Light / Dark / Auto color theme">
<svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg>
<svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg>
<svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
<svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
</button>
</div>
<label class="toc-overlay-icon toc-content-icon" for="__toc">
<span class="icon"><svg><use href="#svg-toc"></use></svg></span>
</label>
</div>
<article role="main" id="furo-main-content">
<section id="protecting-open-networks">
<h1>Protecting Open Networks<a class="headerlink" href="#protecting-open-networks" title="Link to this heading"></a></h1>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>Reticulum is currently transitioning towards full, on-network stamp verification and enforcement via a phased transition:</p>
<ul class="simple">
<li><p>The <code class="docutils literal notranslate"><span class="pre">1.6.0</span></code> release completely implements the required mechanisms, and will start excercising the verification system in the transport backend. By default, <code class="docutils literal notranslate"><span class="pre">1.6.0</span></code> does not enable full stamp generation, emission and enforcement, but all of these options can be early-enabled in the configuration.</p></li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">1.6.1</span></code> release will enable full stamp generation and emission of all types by default, but will leave the <em>enforcement</em> a configurable option.</p></li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">1.6.2</span></code> release will complete the transition, activating full stamp enforcement across all the systems.</p></li>
</ul>
<p>The stated version numbers are the <em>intended</em> release sequence. If any issues or implementation problems are found during the initial network deployments, the transition points may be pushed later than this plan by interim releases.</p>
</div>
<p>While you can create entirely closed-off and private networks with Reticulum, the protocol itself is open and permissionless. On widely interconnected networks, anyone can create identities and globally reachable destinations without external permission or approval, and establish links anonymously over the network.</p>
<p>Such capabilities are powerful, and a required characteristic of a truly functional communications fabric, but also raise very large challenges, that have been almost impossible to solve in legacy networking technologies.</p>
<p>Reticulum approaches this particular problem, like most others, by employing cryptographic principles. This provides a comprehensive, multi-layered repertoire of defense mechanisms, which can be composed and employed in very effective ways.</p>
<p>In contrast to other networking paradigms, these mechanisms do not have to be bolted on to the application layer in hindsight, but are a core part of the protocol itself, which means that they can be applied universally and effectively:</p>
<blockquote>
<div><p>All nodes help combat spam and network abuse, according to the rules <em>set by the actual owners of supplied resources</em> - not by any bureaucracy or external authority.</p>
<p>Rules and requirements can be adjusted live, dynamically and directly, and by those that actually operate and run the infrastructure and services.</p>
</div></blockquote>
<p>The system has been designed so that it becomes very cheap computationally for resource-providing nodes to verify or reject traffic, and very expensive for malicious nodes to abuse the shared resources provided by the network’s operators.</p>
<section id="cryptographic-stamps">
<h2>Cryptographic Stamps<a class="headerlink" href="#cryptographic-stamps" title="Link to this heading"></a></h2>
<p>All networking primitives that consume shared network resources are gated by <em>stamps</em>. A stamp is compact, cryptographic token that proves that a certain amount of computation and energy has been expended in its creation.</p>
<p>The amount of such computation required for a stamp to be considered valid can be configured individually by the operator of the resource being made available, whether that is network transport, a node providing information for retrieval, a shared voice room, or something else entirely.</p>
<p>While the core functionality is completely automatic, and handled by Reticulum itself, the primitives are made available at the application layer API as well, so that developers can use them to implement further protections, if required by their usage scenarios. In most cases, however, simply setting the target <em>values</em> and required <em>costs</em> for the built-in mechanisms will be sufficient.</p>
<p>The <em>value</em> of a stamp is a decimal representation of how difficult a stamp was to create, on a scale from <code class="docutils literal notranslate"><span class="pre">0.0</span></code> to <code class="docutils literal notranslate"><span class="pre">100.0</span></code>. The scale is <strong>exponential</strong>. An increase of one point is equal to <em>doubling</em> the average compute time required. Fractional values are supported, such as <code class="docutils literal notranslate"><span class="pre">14.125</span></code>.</p>
<p>Internally, the fractional part is quantized to <code class="docutils literal notranslate"><span class="pre">256</span></code> different values, giving an approximately <code class="docutils literal notranslate"><span class="pre">0.4%</span></code> difficulty increase per step. You can use any decimal number when configuring stamps, such as <code class="docutils literal notranslate"><span class="pre">9.3691</span></code> and you do not have to worry about “landing on” the correct step values. Reticulum will automatically handle the quantization, wire-transport representation and value comparisons.</p>
<p>The term <em>cost</em> is used everywhere a stamp value <em>requirement</em> is configured or specified. In general, <em>value</em> refers to the actual, determined value of a given stamp, <em>cost</em> refers to a value requirement.</p>
<section id="base-primitives">
<h3>Base Primitives<a class="headerlink" href="#base-primitives" title="Link to this heading"></a></h3>
<p>Reticulum provides two types of base stamp primitives:</p>
<blockquote>
<div><ul>
<li><p><strong>Detached stamps</strong> can be tied to any external information, and are useful for stamping both static information and for one-time verification purposes. The stamp itself is a detached, short binary sequence, typically 14 to 32 bytes, that can be verified directly against the stamped material.</p>
<p>They can be configured from relatively easy to compute, even for embbedded systems and microcontrollers, all the way to something that is practically impossible, even with all the compute and memory on the planet.</p>
</li>
<li><p><strong>Embedded stamps</strong> are tied directly to a Reticulum Identity keyset, and embedded within it. The keyset itself <em>contains</em> the stamp, and there is no external, detached byte sequence for them.</p>
<p>Anyone can verify the value of an identity-embedded stamp simply from the public key material of the identity.</p>
</li>
</ul>
</div></blockquote>
</section>
<section id="on-network-types">
<h3>On-Network Types<a class="headerlink" href="#on-network-types" title="Link to this heading"></a></h3>
<p>The base primitives are used to implement scenario-specific network-level primitives that, if configured correctly, make spam and network abuse expensive, but validation and enforcement cheap and efficient.</p>
<blockquote>
<div><ul>
<li><p><strong>Destination Stamps</strong> are detached stamps associated with reticulum destinations. They are included in all announces sent by a destination, and by verifying that their value matches a transport node’s cost requirement, they can be either accepted for rebroadcast onto the network, or rejected and dropped.</p>
<p>Destination stamps are <em>one-time</em> generations, and are reusable across announces. They limit the number of <em>new</em> destinations that can be created, and makes it expensive to spam a network with destinations that do not provide anything meaningful. As such, these stamps will typically target relatively high values, and their cost requirements should be set accordingly.</p>
<p>A generation time for such stamps in <em>minutes</em> rather than seconds can very well be reasonable on large, open-access networks. Due to their detached nature, they can also be pre-generated off-device (and do not require the private key material for generation), so that even low-powered nodes, such as microcontrollers, can use high-value destination stamps, by having them generated and loaded externally as a one-time procedure.</p>
</li>
<li><p><strong>Path Request Stamps</strong> are also detached stamps, but generated <em>individually</em> for every path request emitted on the network. These will typically have a much lower cost requirement than destination stamps, but if a node is overwhelmed by path requests, it can be tuned higher.</p>
<p>The stamp is generated against the individually unique <em>emission</em>, so that unstamped or low-value path requests for a destination cannot disrupt the resolution of legitimate ones toward that same destination.</p>
</li>
<li><p><strong>Link Request Stamps</strong> embedded stamps, carried in the ephemeral link request keyset. They are therefore completely transparent to the network, but can still be verified extremely quickly by any node along the link request path, who can then make a decision on whether or not to transport it.</p>
<p>Link request cost targets are set by the <em>endpoint destinations individually</em>. Every destination that includes a stamp in its announces will also include link request cost signalling. This means that any node that hears an announce from the destination will also know what link request stamp value to target, when establishing links to that destination.</p>
<p>Furthermore, spam and link request abuse can be filtered before even reaching the destination, if at least one node along the path validates the link request stamp value and cost requirement.</p>
</li>
</ul>
</div></blockquote>
<p>All of the stamp primitives, functionality and on-wire signalling is <em>transparent and backwards-compatible</em> with older versions of Reticulum transport nodes. This means, that even if a node doesn’t itself understand stamp functionality, it will still transport all the required information. Stamped announces, path and link requests can cross older, non stamp-aware network segments transparently and unaffected.</p>
</section>
<section id="configuring-stamps">
<span id="stamps-configuring"></span><h3>Configuring Stamps<a class="headerlink" href="#configuring-stamps" title="Link to this heading"></a></h3>
<p>Reticulum, and its included utilities, provide sane default cost requirements and value targets for the different types of network stamps, but it is entirely up to the operator whether to follow the defaults. All of them are configurable on a per-node, per-application and per-destination basis.</p>
<section id="instance-configuration">
<h4>Instance Configuration<a class="headerlink" href="#instance-configuration" title="Link to this heading"></a></h4>
<p>In reality, different kinds of networks will want to configure different kinds of costs and value targets for their use. For instance-wide defaults and settings, you can configure these in the <code class="docutils literal notranslate"><span class="pre">[stamps]</span></code> section of the Reticulum configuration file:</p>
<blockquote>
<div><ul>
<li><div class="line-block">
<div class="line">The <code class="docutils literal notranslate"><span class="pre">stamp_destinations</span></code> option enables generation and emission
of destination stamps in announces. This is a transitory option.
It will become mandatory and enabled by default in RNS <code class="docutils literal notranslate"><span class="pre">1.6.1</span></code>.</div>
</div>
</li>
<li><div class="line-block">
<div class="line">The <code class="docutils literal notranslate"><span class="pre">stamp_prs</span></code> option enables stamping of path requests emitted
by this instance. This is a transitory option. It will become
mandatory and enabled by default in RNS <code class="docutils literal notranslate"><span class="pre">1.6.1</span></code>.</div>
</div>
</li>
<li><div class="line-block">
<div class="line">The <code class="docutils literal notranslate"><span class="pre">always_stamp_lrs</span></code> option will stamp <em>all</em> outgoing link
requests, even to destinations that have not announced a link
request cost (and will, in that case, use the configured or
default link request cost). This option is mostly useful for
testing and diagnostics. In general use, Reticulum will handle
link request stamping and cost targets automatically.</div>
</div>
</li>
<li><div class="line-block">
<div class="line">The <code class="docutils literal notranslate"><span class="pre">enforce_stamps</span></code> option allows early activation of stamp
enforcement. When enabled, announces and path requests that do
not meet the configured cost requirements are dropped, and link
requests with insufficient stamps are ignored. This is a transitory
option. It will become mandatory and enabled by default in RNS
<code class="docutils literal notranslate"><span class="pre">1.6.2</span></code>.</div>
</div>
</li>
<li><div class="line-block">
<div class="line">The <code class="docutils literal notranslate"><span class="pre">destination_cost</span></code> option sets the default required stamp
cost for announced destinations to be accepted, and have their
announces propagated by this node. Defaults to <code class="docutils literal notranslate"><span class="pre">23.5</span></code>.</div>
</div>
</li>
<li><div class="line-block">
<div class="line">The <code class="docutils literal notranslate"><span class="pre">destination_value</span></code> option sets the default stamp value that
this instance will target when generating new destination stamps.
An application can request higher targets for destinations that it
creates, but a requested lower value will always be clamped to the
configured default as a minimum. Defaults to <code class="docutils literal notranslate"><span class="pre">25.0</span></code>.</div>
</div>
<blockquote>
<div><p><em>Destination stamps are one-time generations per destination, so it
is generally a good idea to target a slightly higher value than the
minimum required cost of the networks you want the destination to
be reachable on.</em></p>
</div></blockquote>
</li>
<li><div class="line-block">
<div class="line">The <code class="docutils literal notranslate"><span class="pre">pr_cost</span></code> option sets the required stamp cost for incoming
path requests. Defaults to <code class="docutils literal notranslate"><span class="pre">15.8</span></code>.</div>
</div>
</li>
<li><div class="line-block">
<div class="line">The <code class="docutils literal notranslate"><span class="pre">pr_value</span></code> option sets the target stamp value for path
request stamps generated by this instance. Defaults to <code class="docutils literal notranslate"><span class="pre">15.8</span></code>.</div>
</div>
</li>
<li><div class="line-block">
<div class="line">The <code class="docutils literal notranslate"><span class="pre">lr_cost</span></code> option sets the default link request stamp cost,
that destinations created on this instance will require. This
value can be freely overridden by applications that specify their
own link request cost requirements, and is solely used as the
default if no such specification is provided. Defaults to <code class="docutils literal notranslate"><span class="pre">12.5</span></code>.</div>
</div>
</li>
<li><div class="line-block">
<div class="line">The <code class="docutils literal notranslate"><span class="pre">lr_stamp_timeout</span></code> and <code class="docutils literal notranslate"><span class="pre">pr_stamp_timeout</span></code> options set the
maximum amount of time, in seconds, to spend while attempting to
generate link and path request stamps respectively. If a stamp is
not generated within this timespan, the generation is cancelled,
and the link request or path request fails. Defaults to <code class="docutils literal notranslate"><span class="pre">15</span></code>
seconds for both options.</div>
</div>
</li>
</ul>
</div></blockquote>
<p>An example of customised stamp cost and value configuration follows below:</p>
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[stamps]</span>
<span class="w"> </span><span class="na">stamp_destinations</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span>
<span class="w"> </span><span class="na">stamp_prs</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span>
<span class="w"> </span><span class="na">destination_cost</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">24.8</span>
<span class="w"> </span><span class="na">destination_value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">26.25</span>
<span class="w"> </span><span class="na">pr_cost</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">15.8</span>
<span class="w"> </span><span class="na">pr_value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">16.45</span>
</pre></div>
</div>
<p>Stamp cost requirements can also be configured on a per-interface basis:</p>
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[[Public Gateway]]</span>
<span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">BackboneInterface</span>
<span class="w"> </span><span class="na">mode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">gateway</span>
<span class="w"> </span><span class="na">listen_on</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">0.0.0.0</span>
<span class="w"> </span><span class="na">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4242</span>
<span class="w"> </span><span class="na">destination_cost</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">25.0</span>
<span class="w"> </span><span class="na">pr_cost</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">17.2</span>
<span class="k">[[Local RNode]]</span>
<span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">RNodeInterface</span>
<span class="w"> </span><span class="na">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">/dev/ttyUSB0</span>
<span class="w"> </span><span class="c1"># Much lower requirements</span>
<span class="w"> </span><span class="c1"># for the local network.</span>
<span class="w"> </span><span class="na">destination_cost</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">11.2</span>
<span class="w"> </span><span class="na">pr_cost</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">5.0</span>
</pre></div>
</div>
</section>
<section id="for-developers">
<h4>For Developers<a class="headerlink" href="#for-developers" title="Link to this heading"></a></h4>
<p>Applications can dynamically set their own stamp values and required link requests costs at runtime. Whenever the values are adjusted, the destination will have to send an announce for the updated information to become known by the rest of the network.</p>
<p>If you are setting these values at destination creation time, ensure that they are set <em>immediately</em> after the destination is instantiated, as Reticulum may queue internal, instance-local announces for the destination shortly after creation, so that the local shared instance and its clients are aware of the newly created destination.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Create a new destination</span>
<span class="n">my_destination</span> <span class="o">=</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Destination</span><span class="p">(</span>
<span class="n">my_identity</span><span class="p">,</span>
<span class="n">RNS</span><span class="o">.</span><span class="n">Destination</span><span class="o">.</span><span class="n">IN</span><span class="p">,</span>
<span class="n">RNS</span><span class="o">.</span><span class="n">Destination</span><span class="o">.</span><span class="n">SINGLE</span><span class="p">,</span>
<span class="s2">&quot;myapp&quot;</span><span class="p">,</span> <span class="s2">&quot;service&quot;</span>
<span class="p">)</span>
<span class="c1"># Configure stamps</span>
<span class="n">my_destination</span><span class="o">.</span><span class="n">set_value</span><span class="p">(</span><span class="mf">30.0</span><span class="p">)</span>
<span class="n">my_destination</span><span class="o">.</span><span class="n">set_link_cost</span><span class="p">(</span><span class="mf">15.0</span><span class="p">)</span>
</pre></div>
</div>
<p>Dynamically adjusting link request costs is a viable and intended mechanism for mitigating resource abuse, scraping, DoS attempts and other malicious behaviour. An application may implement mechanisms to statically or dynamically raise link request costs under certain conditions.</p>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
<p>Remember here, though, that announce cadence should be preserved for such situations! If your destination is announcing too often in general, and wants to dynamically adjust link request costs at a critical moment, it may already have exhausted its announce rate limits on upstream nodes. So plan your application’s announce cadence thoughtfully!</p>
</div>
<p>It is also possible for application code to directly get the destination value and link request cost for any known destination:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Get the value of a known destination</span>
<span class="n">RNS</span><span class="o">.</span><span class="n">Identity</span><span class="o">.</span><span class="n">recall_stamp_value</span><span class="p">(</span><span class="n">destination_hash</span><span class="p">)</span>
<span class="c1"># Get the current link cost requirement</span>
<span class="c1"># of a known destination</span>
<span class="n">RNS</span><span class="o">.</span><span class="n">Identity</span><span class="o">.</span><span class="n">recall_link_cost</span><span class="p">(</span><span class="n">destination_hash</span><span class="p">)</span>
</pre></div>
</div>
<p>An <code class="docutils literal notranslate"><span class="pre">Identity</span></code> can be created with an embedded stamp value, by passing the target value at instantiation time:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Create a new, stamped identity</span>
<span class="n">my_identity</span> <span class="o">=</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Identity</span><span class="p">(</span><span class="n">value</span><span class="o">=</span><span class="mf">24.0</span><span class="p">)</span>
<span class="c1"># Get the value of any known identity</span>
<span class="n">another_identity</span><span class="o">.</span><span class="n">get_value</span><span class="p">()</span>
</pre></div>
</div>
<p>As with destination stamps, this is a one-time generation procedure, that happens at Identity creation. Once an identity is created with an embedded stamp, its value <em>cannot</em> be upgraded at a later point as with detached stamps.</p>
</section>
</section>
</section>
<section id="filtering-qos">
<h2>Filtering &amp; QoS<a class="headerlink" href="#filtering-qos" title="Link to this heading"></a></h2>
<p>TODO: Section explaining the <code class="docutils literal notranslate"><span class="pre">[filter]</span></code> configuration options, for creating allow and blocklists for specific destination types.</p>
</section>
<section id="blackhole-management">
<h2>Blackhole Management<a class="headerlink" href="#blackhole-management" title="Link to this heading"></a></h2>
<p>TODO: Section explaining the blackhole system conceptually (including distributed updates from other nodes), with a few terse examples for either locally - or across an entire managed network - blocking specific identities (and therefore any destination types created by such), as well as blocking incoming (identified) link requests from that identity at terminus.</p>
</section>
<section id="ingress-burst-control">
<h2>Ingress &amp; Burst Control<a class="headerlink" href="#ingress-burst-control" title="Link to this heading"></a></h2>
<p>TODO: Section explaining the rate-limiting, ingress control and burst limiters conceptually, with a few, terse examples on how to configure them (linked references to other more extensive documentation sections of the options).</p>
</section>
</section>
</article>
</div>
<footer>
<div class="related-pages">
<a class="next-page" href="understanding.html">
<div class="page-info">
<div class="context">
<span>Next</span>
</div>
<div class="title">Understanding Reticulum</div>
</div>
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
</a>
<a class="prev-page" href="using.html">
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
<div class="page-info">
<div class="context">
<span>Previous</span>
</div>
<div class="title">Using Reticulum on Your System</div>
</div>
</a>
</div>
<div class="bottom-of-page">
<div class="left-details">
<div class="copyright">
Copyright &#169; 2025, Mark Qvist
</div>
Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and
<a href="https://github.com/pradyunsg/furo">Furo</a>
</div>
<div class="right-details">
</div>
</div>
</footer>
</div>
<aside class="toc-drawer">
<div class="toc-sticky toc-scroll">
<div class="toc-title-container">
<span class="toc-title">
On this page
</span>
</div>
<div class="toc-tree-container">
<div class="toc-tree">
<ul>
<li><a class="reference internal" href="#">Protecting Open Networks</a><ul>
<li><a class="reference internal" href="#cryptographic-stamps">Cryptographic Stamps</a><ul>
<li><a class="reference internal" href="#base-primitives">Base Primitives</a></li>
<li><a class="reference internal" href="#on-network-types">On-Network Types</a></li>
<li><a class="reference internal" href="#configuring-stamps">Configuring Stamps</a><ul>
<li><a class="reference internal" href="#instance-configuration">Instance Configuration</a></li>
<li><a class="reference internal" href="#for-developers">For Developers</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#filtering-qos">Filtering &amp; QoS</a></li>
<li><a class="reference internal" href="#blackhole-management">Blackhole Management</a></li>
<li><a class="reference internal" href="#ingress-burst-control">Ingress &amp; Burst Control</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</aside>
</div>
</div><script src="_static/documentation_options.js?v=72d88caf"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=46bd48cc"></script>
<script src="_static/clipboard.min.js?v=a7894cd8"></script>
<script src="_static/copybutton.js?v=f281be69"></script>
</body>
</html>

View file

@ -7,7 +7,7 @@
<link rel="prefetch" href="_static/rns_logo_512.png" as="image">
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
<title>Support Reticulum - Reticulum Network Stack 1.5.7 documentation</title>
<title>Support Reticulum - Reticulum Network Stack 1.6.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@ -180,7 +180,7 @@
</label>
</div>
<div class="header-center">
<a href="index.html"><div class="brand">Reticulum Network Stack 1.5.7 documentation</div></a>
<a href="index.html"><div class="brand">Reticulum Network Stack 1.6.0 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
@ -204,7 +204,7 @@
<img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
</div>
<span class="sidebar-brand-text">Reticulum Network Stack 1.5.7 documentation</span>
<span class="sidebar-brand-text">Reticulum Network Stack 1.6.0 documentation</span>
</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@ -218,6 +218,7 @@
<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
<li class="toctree-l1"><a class="reference internal" href="stamps.html">Protecting Open Networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
@ -382,7 +383,7 @@ circumstances, so we rely on old-fashioned human feedback.</p>
</aside>
</div>
</div><script src="_static/documentation_options.js?v=2b2ec289"></script>
</div><script src="_static/documentation_options.js?v=72d88caf"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=46bd48cc"></script>

View file

@ -3,11 +3,11 @@
<head><meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="next" title="Communications Hardware" href="hardware.html"><link rel="prev" title="Using Reticulum on Your System" href="using.html">
<link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="next" title="Communications Hardware" href="hardware.html"><link rel="prev" title="Protecting Open Networks" href="stamps.html">
<link rel="prefetch" href="_static/rns_logo_512.png" as="image">
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
<title>Understanding Reticulum - Reticulum Network Stack 1.5.7 documentation</title>
<title>Understanding Reticulum - Reticulum Network Stack 1.6.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@ -180,7 +180,7 @@
</label>
</div>
<div class="header-center">
<a href="index.html"><div class="brand">Reticulum Network Stack 1.5.7 documentation</div></a>
<a href="index.html"><div class="brand">Reticulum Network Stack 1.6.0 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
@ -204,7 +204,7 @@
<img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
</div>
<span class="sidebar-brand-text">Reticulum Network Stack 1.5.7 documentation</span>
<span class="sidebar-brand-text">Reticulum Network Stack 1.6.0 documentation</span>
</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@ -218,6 +218,7 @@
<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
<li class="toctree-l1"><a class="reference internal" href="stamps.html">Protecting Open Networks</a></li>
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Understanding Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
@ -1030,14 +1031,14 @@ those risks are acceptable to you.</p>
</div>
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
</a>
<a class="prev-page" href="using.html">
<a class="prev-page" href="stamps.html">
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
<div class="page-info">
<div class="context">
<span>Previous</span>
</div>
<div class="title">Using Reticulum on Your System</div>
<div class="title">Protecting Open Networks</div>
</div>
</a>
@ -1120,7 +1121,7 @@ those risks are acceptable to you.</p>
</aside>
</div>
</div><script src="_static/documentation_options.js?v=2b2ec289"></script>
</div><script src="_static/documentation_options.js?v=72d88caf"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=46bd48cc"></script>

View file

@ -3,11 +3,11 @@
<head><meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="next" title="Understanding Reticulum" href="understanding.html"><link rel="prev" title="Programs Using Reticulum" href="software.html">
<link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="next" title="Protecting Open Networks" href="stamps.html"><link rel="prev" title="Programs Using Reticulum" href="software.html">
<link rel="prefetch" href="_static/rns_logo_512.png" as="image">
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
<title>Using Reticulum on Your System - Reticulum Network Stack 1.5.7 documentation</title>
<title>Using Reticulum on Your System - Reticulum Network Stack 1.6.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@ -180,7 +180,7 @@
</label>
</div>
<div class="header-center">
<a href="index.html"><div class="brand">Reticulum Network Stack 1.5.7 documentation</div></a>
<a href="index.html"><div class="brand">Reticulum Network Stack 1.6.0 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
@ -204,7 +204,7 @@
<img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
</div>
<span class="sidebar-brand-text">Reticulum Network Stack 1.5.7 documentation</span>
<span class="sidebar-brand-text">Reticulum Network Stack 1.6.0 documentation</span>
</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@ -218,6 +218,7 @@
<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Using Reticulum on Your System</a></li>
<li class="toctree-l1"><a class="reference internal" href="stamps.html">Protecting Open Networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
@ -443,10 +444,12 @@ configuration file is created. The default configuration looks like this:</p>
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.</p>
<p>You can generate a much more verbose configuration example by running the command:</p>
<p>The example above does not document all the available options, only the basics.
To explore all the various configuration options available, you can generate a
much more verbose and complete configuration example by running the command:</p>
<p><code class="docutils literal notranslate"><span class="pre">rnsd</span> <span class="pre">--exampleconfig</span></code></p>
<p>The output includes examples for most interface types supported
by Reticulum, along with additional options and configuration parameters.</p>
<p>The output includes examples for most interface types supported by Reticulum,
along with additional options and configuration parameters.</p>
<p>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
@ -821,7 +824,7 @@ and simply running the program in listener mode:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rncp --fetch ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
</pre></div>
</div>
<p>The default identity file is stored in <code class="docutils literal notranslate"><span class="pre">~/.reticulum/identities/rncp</span></code>, but you can use
<p>The default identity file is stored in <code class="docutils literal notranslate"><span class="pre">~/.reticulum/storage/identities/rncp</span></code>, but you can use
another one, which will be created if it does not already exist</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rncp ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e -i /path/to/identity
</pre></div>
@ -891,7 +894,7 @@ at the <a class="reference internal" href="#using-rnsh"><span class="std std-ref
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnx 7a55144adf826958a9529a3bcf08b149 -x
</pre></div>
</div>
<p>The default identity file is stored in <code class="docutils literal notranslate"><span class="pre">~/.reticulum/identities/rnx</span></code>, but you can use
<p>The default identity file is stored in <code class="docutils literal notranslate"><span class="pre">~/.reticulum/storage/identities/rnx</span></code>, but you can use
another one, which will be created if it does not already exist</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnx 7a55144adf826958a9529a3bcf08b149 -i /path/to/identity -x
</pre></div>
@ -1065,9 +1068,10 @@ the remote process, rather than always returning <code class="docutils literal n
seconds. By default, the timeout matches the Reticulum path request timeout.</p></li>
</ul>
<p><strong>Identity &amp; Destination</strong></p>
<p>The default identity file for <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> is stored at
<code class="docutils literal notranslate"><span class="pre">~/.reticulum/identities/rnsh</span></code>, but you can specify a different one with the
<code class="docutils literal notranslate"><span class="pre">-i</span></code> option, which will be created if it does not already exist:</p>
<p>The default initiator identity file for <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> is stored at
<code class="docutils literal notranslate"><span class="pre">~/.rns/identity</span></code> (default listener identity is in <code class="docutils literal notranslate"><span class="pre">~/.rns/identity.default</span></code>),
but you can specify a different one with the <code class="docutils literal notranslate"><span class="pre">-i</span></code> option, which will be created if
it does not already exist:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l -i /path/to/identity
</pre></div>
</div>
@ -1497,6 +1501,7 @@ Type=simple
Restart=always
RestartSec=3
User=USERNAMEHERE
Environment=MALLOC_ARENA_MAX=2
ExecStart=rnsd --service
[Install]
@ -1531,6 +1536,7 @@ After=default.target
Type=simple
Restart=always
RestartSec=3
Environment=MALLOC_ARENA_MAX=2
ExecStart=RNS_BIN_DIR/rnsd --service
[Install]
@ -1558,12 +1564,12 @@ systemctl --user enable rnsd.service
<footer>
<div class="related-pages">
<a class="next-page" href="understanding.html">
<a class="next-page" href="stamps.html">
<div class="page-info">
<div class="context">
<span>Next</span>
</div>
<div class="title">Understanding Reticulum</div>
<div class="title">Protecting Open Networks</div>
</div>
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
</a>
@ -1650,7 +1656,7 @@ systemctl --user enable rnsd.service
</aside>
</div>
</div><script src="_static/documentation_options.js?v=2b2ec289"></script>
</div><script src="_static/documentation_options.js?v=72d88caf"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=46bd48cc"></script>

View file

@ -7,7 +7,7 @@
<link rel="prefetch" href="_static/rns_logo_512.png" as="image">
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
<title>What is Reticulum? - Reticulum Network Stack 1.5.7 documentation</title>
<title>What is Reticulum? - Reticulum Network Stack 1.6.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@ -180,7 +180,7 @@
</label>
</div>
<div class="header-center">
<a href="index.html"><div class="brand">Reticulum Network Stack 1.5.7 documentation</div></a>
<a href="index.html"><div class="brand">Reticulum Network Stack 1.6.0 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
@ -204,7 +204,7 @@
<img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
</div>
<span class="sidebar-brand-text">Reticulum Network Stack 1.5.7 documentation</span>
<span class="sidebar-brand-text">Reticulum Network Stack 1.6.0 documentation</span>
</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@ -218,6 +218,7 @@
<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
<li class="toctree-l1"><a class="reference internal" href="stamps.html">Protecting Open Networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
@ -506,7 +507,7 @@ network, and vice versa.</p>
</aside>
</div>
</div><script src="_static/documentation_options.js?v=2b2ec289"></script>
</div><script src="_static/documentation_options.js?v=72d88caf"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=46bd48cc"></script>

View file

@ -7,7 +7,7 @@
<link rel="prefetch" href="_static/rns_logo_512.png" as="image">
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
<title>Zen of Reticulum - Reticulum Network Stack 1.5.7 documentation</title>
<title>Zen of Reticulum - Reticulum Network Stack 1.6.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@ -180,7 +180,7 @@
</label>
</div>
<div class="header-center">
<a href="index.html"><div class="brand">Reticulum Network Stack 1.5.7 documentation</div></a>
<a href="index.html"><div class="brand">Reticulum Network Stack 1.6.0 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
@ -204,7 +204,7 @@
<img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
</div>
<span class="sidebar-brand-text">Reticulum Network Stack 1.5.7 documentation</span>
<span class="sidebar-brand-text">Reticulum Network Stack 1.6.0 documentation</span>
</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@ -218,6 +218,7 @@
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Zen of Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
<li class="toctree-l1"><a class="reference internal" href="stamps.html">Protecting Open Networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
@ -678,7 +679,7 @@ Imagine a messaging app. You write it once. It works on a laptop connected to fi
</aside>
</div>
</div><script src="_static/documentation_options.js?v=2b2ec289"></script>
</div><script src="_static/documentation_options.js?v=72d88caf"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=46bd48cc"></script>

View file

@ -805,6 +805,9 @@ def server(configpath):
"linkexample"
)
# We can optionally configure a link request stamp cost
server_destination.set_link_cost(14.2)
# We configure a function that will get called every time
# a new client creates a link to this destination.
server_destination.set_link_established_callback(client_connected)

View file

@ -130,6 +130,14 @@ to participate in the development of Reticulum itself.
* [Improving System Configuration](using.md#improving-system-configuration)
* [Fixed Serial Port Names](using.md#fixed-serial-port-names)
* [Reticulum as a System Service](using.md#reticulum-as-a-system-service)
* [Protecting Open Networks](stamps.md)
* [Cryptographic Stamps](stamps.md#cryptographic-stamps)
* [Base Primitives](stamps.md#base-primitives)
* [On-Network Types](stamps.md#on-network-types)
* [Configuring Stamps](stamps.md#configuring-stamps)
* [Filtering & QoS](stamps.md#filtering-qos)
* [Blackhole Management](stamps.md#blackhole-management)
* [Ingress & Burst Control](stamps.md#ingress-burst-control)
* [Understanding Reticulum](understanding.md)
* [Motivation](understanding.md#motivation)
* [Goals](understanding.md#goals)

View file

@ -910,13 +910,6 @@ Reticulum includes a powerful system for publishing your local interfaces to the
When an interface is made **discoverable**, your Reticulum instance will periodically broadcast an announce packet containing the connection details and parameters required for other peers to establish a connection. These announces are propagated over the network using the standard Reticulum announce mechanism using the `rnstransport.discovery.interface` destination type.
#### NOTE
To use the interface discovery functionality, the `LXMF` module must be installed in your Python environment. You can install it using pip:
```sh
pip install lxmf
```
### Enabling Discovery
Interface discovery is enabled on a per-interface basis. To make a specific interface discoverable, you must add the `discoverable` option to that interface’s configuration block and set it to `yes`.

View file

@ -3,7 +3,7 @@
Communication over Reticulum networks is achieved by using a simple set of classes exposed by the RNS API.
This chapter lists and explains all classes exposed by the Reticulum Network Stack API, along with their method signatures and usage. It can be used as a reference while writing applications that utilise Reticulum, or it can be read in entirity to gain an understanding of the complete functionality of RNS from a developers perspective.
### `class RNS.Reticulum(configdir=None, loglevel=None, logdest=None, verbosity=None, require_shared_instance=False, shared_instance_type=None)`
### `class RNS.Reticulum(configdir=None, loglevel=None, logdest=None, verbosity=None, require_shared_instance=False, shared_instance_type=None, enable_stamping=False, enforce_stamps=False)`
This class is used to initialise access to Reticulum within a
program. You must create exactly one instance of this class before
@ -156,7 +156,7 @@ Returns the required stamp value for a discovered interface
to be considered valid and remembered.
* **Returns:**
The required stamp value as an integer.
The required stamp value as a float.
#### `static publish_blackhole_enabled()`
@ -189,7 +189,7 @@ interfaces are discovered.
* **Returns:**
A list of identity hashes.
### `class RNS.Identity(create_keys=True)`
### `class RNS.Identity(create_keys=True, value=None)`
This class is used to manage identities in Reticulum. It provides methods
for encryption, decryption, signatures and verification, and is the basis
@ -247,6 +247,26 @@ Recall last heard app_data for a destination hash.
* **Returns:**
*Bytes* containing app_data, or *None* if the destination is unknown.
#### `static recall_stamp_value(destination_hash)`
Recall last heard announce stamp value for a destination hash.
* **Parameters:**
**destination_hash** – Destination hash as *bytes*.
* **Returns:**
*Float*, or *None* if the destination is unknown.
#### `static recall_link_cost(destination_hash)`
Recall the link request stamp cost announced by a destination.
* **Parameters:**
**destination_hash** – Destination hash as *bytes*.
* **Returns:**
*Float*, or *None* if the destination is unknown or has not announced a cost.
#### `static full_hash(data)`
Get a SHA-256 hash of passed data.
@ -331,6 +351,11 @@ Saves the public identity to a file.
* **Returns:**
True if the file was saved, otherwise False.
#### `get_value()`
* **Returns:**
The stamp value of this identity as a *float*
#### `get_private_key()`
* **Returns:**
@ -467,6 +492,29 @@ relevant interfaces. Application specific data can be added to the announce.
* **app_data** – *bytes* containing the app_data.
* **path_response** – Internal flag used by [RNS.Transport](#api-transport). Ignore.
#### `set_value(value)`
Sets the target stamp value for this destination.
* **Parameters:**
**value** – The target value as a *float*.
#### `set_link_cost(cost)`
Sets the required link establishment stamp cost for this destination. Set to 0 to disable.
* **Parameters:**
**cost** – The required cost as a *float*.
#### `get_link_cost()`
Returns the link request stamp cost to be announced for this
destination, as a float. If no destination-specific cost has
been set, the default link request cost is returned.
* **Returns:**
The announced link request cost as a *float*.
#### `accepts_links(accepts=None)`
Set or query whether the destination accepts incoming link requests.
@ -1373,7 +1421,7 @@ blocks until the path is available, or the timeout is reached.
* **Returns:**
*True* if a path to the destination is found, otherwise *False*.
#### `static request_path(destination_hash, on_interface=None, tag=None, recursive=False)`
#### `static request_path(destination_hash, on_interface=None, tag=None, recursive=False, ext_payload=None)`
Requests a path to the destination from the network. If
another reachable peer on the network knows a path, it
@ -1382,6 +1430,7 @@ will announce it.
* **Parameters:**
* **destination_hash** – A destination hash as *bytes*.
* **on_interface** – If specified, the path request will only be sent on this interface. In normal use, Reticulum handles this automatically, and this parameter should not be used.
* **ext_payload** – Internal use by [RNS.Transport](#api-transport). Ignore.
#### `static blackhole_identity(identity_hash, until=None, reason=None)`

226
docs/markdown/stamps.md Normal file
View file

@ -0,0 +1,226 @@
# Protecting Open Networks
#### IMPORTANT
Reticulum is currently transitioning towards full, on-network stamp verification and enforcement via a phased transition:
- The `1.6.0` release completely implements the required mechanisms, and will start excercising the verification system in the transport backend. By default, `1.6.0` does not enable full stamp generation, emission and enforcement, but all of these options can be early-enabled in the configuration.
- The `1.6.1` release will enable full stamp generation and emission of all types by default, but will leave the *enforcement* a configurable option.
- The `1.6.2` release will complete the transition, activating full stamp enforcement across all the systems.
The stated version numbers are the *intended* release sequence. If any issues or implementation problems are found during the initial network deployments, the transition points may be pushed later than this plan by interim releases.
While you can create entirely closed-off and private networks with Reticulum, the protocol itself is open and permissionless. On widely interconnected networks, anyone can create identities and globally reachable destinations without external permission or approval, and establish links anonymously over the network.
Such capabilities are powerful, and a required characteristic of a truly functional communications fabric, but also raise very large challenges, that have been almost impossible to solve in legacy networking technologies.
Reticulum approaches this particular problem, like most others, by employing cryptographic principles. This provides a comprehensive, multi-layered repertoire of defense mechanisms, which can be composed and employed in very effective ways.
In contrast to other networking paradigms, these mechanisms do not have to be bolted on to the application layer in hindsight, but are a core part of the protocol itself, which means that they can be applied universally and effectively:
> All nodes help combat spam and network abuse, according to the rules *set by the actual owners of supplied resources* - not by any bureaucracy or external authority.
> Rules and requirements can be adjusted live, dynamically and directly, and by those that actually operate and run the infrastructure and services.
The system has been designed so that it becomes very cheap computationally for resource-providing nodes to verify or reject traffic, and very expensive for malicious nodes to abuse the shared resources provided by the network’s operators.
## Cryptographic Stamps
All networking primitives that consume shared network resources are gated by *stamps*. A stamp is compact, cryptographic token that proves that a certain amount of computation and energy has been expended in its creation.
The amount of such computation required for a stamp to be considered valid can be configured individually by the operator of the resource being made available, whether that is network transport, a node providing information for retrieval, a shared voice room, or something else entirely.
While the core functionality is completely automatic, and handled by Reticulum itself, the primitives are made available at the application layer API as well, so that developers can use them to implement further protections, if required by their usage scenarios. In most cases, however, simply setting the target *values* and required *costs* for the built-in mechanisms will be sufficient.
The *value* of a stamp is a decimal representation of how difficult a stamp was to create, on a scale from `0.0` to `100.0`. The scale is **exponential**. An increase of one point is equal to *doubling* the average compute time required. Fractional values are supported, such as `14.125`.
Internally, the fractional part is quantized to `256` different values, giving an approximately `0.4%` difficulty increase per step. You can use any decimal number when configuring stamps, such as `9.3691` and you do not have to worry about “landing on” the correct step values. Reticulum will automatically handle the quantization, wire-transport representation and value comparisons.
The term *cost* is used everywhere a stamp value *requirement* is configured or specified. In general, *value* refers to the actual, determined value of a given stamp, *cost* refers to a value requirement.
### Base Primitives
Reticulum provides two types of base stamp primitives:
> * **Detached stamps** can be tied to any external information, and are useful for stamping both static information and for one-time verification purposes. The stamp itself is a detached, short binary sequence, typically 14 to 32 bytes, that can be verified directly against the stamped material.
> They can be configured from relatively easy to compute, even for embbedded systems and microcontrollers, all the way to something that is practically impossible, even with all the compute and memory on the planet.
> * **Embedded stamps** are tied directly to a Reticulum Identity keyset, and embedded within it. The keyset itself *contains* the stamp, and there is no external, detached byte sequence for them.
> Anyone can verify the value of an identity-embedded stamp simply from the public key material of the identity.
### On-Network Types
The base primitives are used to implement scenario-specific network-level primitives that, if configured correctly, make spam and network abuse expensive, but validation and enforcement cheap and efficient.
> * **Destination Stamps** are detached stamps associated with reticulum destinations. They are included in all announces sent by a destination, and by verifying that their value matches a transport node’s cost requirement, they can be either accepted for rebroadcast onto the network, or rejected and dropped.
> Destination stamps are *one-time* generations, and are reusable across announces. They limit the number of *new* destinations that can be created, and makes it expensive to spam a network with destinations that do not provide anything meaningful. As such, these stamps will typically target relatively high values, and their cost requirements should be set accordingly.
> A generation time for such stamps in *minutes* rather than seconds can very well be reasonable on large, open-access networks. Due to their detached nature, they can also be pre-generated off-device (and do not require the private key material for generation), so that even low-powered nodes, such as microcontrollers, can use high-value destination stamps, by having them generated and loaded externally as a one-time procedure.
> * **Path Request Stamps** are also detached stamps, but generated *individually* for every path request emitted on the network. These will typically have a much lower cost requirement than destination stamps, but if a node is overwhelmed by path requests, it can be tuned higher.
> The stamp is generated against the individually unique *emission*, so that unstamped or low-value path requests for a destination cannot disrupt the resolution of legitimate ones toward that same destination.
> * **Link Request Stamps** embedded stamps, carried in the ephemeral link request keyset. They are therefore completely transparent to the network, but can still be verified extremely quickly by any node along the link request path, who can then make a decision on whether or not to transport it.
> Link request cost targets are set by the *endpoint destinations individually*. Every destination that includes a stamp in its announces will also include link request cost signalling. This means that any node that hears an announce from the destination will also know what link request stamp value to target, when establishing links to that destination.
> Furthermore, spam and link request abuse can be filtered before even reaching the destination, if at least one node along the path validates the link request stamp value and cost requirement.
All of the stamp primitives, functionality and on-wire signalling is *transparent and backwards-compatible* with older versions of Reticulum transport nodes. This means, that even if a node doesn’t itself understand stamp functionality, it will still transport all the required information. Stamped announces, path and link requests can cross older, non stamp-aware network segments transparently and unaffected.
### Configuring Stamps
Reticulum, and its included utilities, provide sane default cost requirements and value targets for the different types of network stamps, but it is entirely up to the operator whether to follow the defaults. All of them are configurable on a per-node, per-application and per-destination basis.
#### Instance Configuration
In reality, different kinds of networks will want to configure different kinds of costs and value targets for their use. For instance-wide defaults and settings, you can configure these in the `[stamps]` section of the Reticulum configuration file:
> * The `stamp_destinations` option enables generation and emission
> of destination stamps in announces. This is a transitory option.
> It will become mandatory and enabled by default in RNS `1.6.1`.
>
> * The `stamp_prs` option enables stamping of path requests emitted
> by this instance. This is a transitory option. It will become
> mandatory and enabled by default in RNS `1.6.1`.
>
> * The `always_stamp_lrs` option will stamp *all* outgoing link
> requests, even to destinations that have not announced a link
> request cost (and will, in that case, use the configured or
> default link request cost). This option is mostly useful for
> testing and diagnostics. In general use, Reticulum will handle
> link request stamping and cost targets automatically.
>
> * The `enforce_stamps` option allows early activation of stamp
> enforcement. When enabled, announces and path requests that do
> not meet the configured cost requirements are dropped, and link
> requests with insufficient stamps are ignored. This is a transitory
> option. It will become mandatory and enabled by default in RNS
> `1.6.2`.
>
> * The `destination_cost` option sets the default required stamp
> cost for announced destinations to be accepted, and have their
> announces propagated by this node. Defaults to `23.5`.
>
> * The `destination_value` option sets the default stamp value that
> this instance will target when generating new destination stamps.
> An application can request higher targets for destinations that it
> creates, but a requested lower value will always be clamped to the
> configured default as a minimum. Defaults to `25.0`.
>
> > *Destination stamps are one-time generations per destination, so it
> > is generally a good idea to target a slightly higher value than the
> > minimum required cost of the networks you want the destination to
> > be reachable on.*
> * The `pr_cost` option sets the required stamp cost for incoming
> path requests. Defaults to `15.8`.
>
> * The `pr_value` option sets the target stamp value for path
> request stamps generated by this instance. Defaults to `15.8`.
>
> * The `lr_cost` option sets the default link request stamp cost,
> that destinations created on this instance will require. This
> value can be freely overridden by applications that specify their
> own link request cost requirements, and is solely used as the
> default if no such specification is provided. Defaults to `12.5`.
>
> * The `lr_stamp_timeout` and `pr_stamp_timeout` options set the
> maximum amount of time, in seconds, to spend while attempting to
> generate link and path request stamps respectively. If a stamp is
> not generated within this timespan, the generation is cancelled,
> and the link request or path request fails. Defaults to `15`
> seconds for both options.
>
An example of customised stamp cost and value configuration follows below:
```ini
[stamps]
stamp_destinations = yes
stamp_prs = yes
destination_cost = 24.8
destination_value = 26.25
pr_cost = 15.8
pr_value = 16.45
```
Stamp cost requirements can also be configured on a per-interface basis:
```ini
[[Public Gateway]]
type = BackboneInterface
mode = gateway
listen_on = 0.0.0.0
port = 4242
destination_cost = 25.0
pr_cost = 17.2
[[Local RNode]]
type = RNodeInterface
port = /dev/ttyUSB0
# Much lower requirements
# for the local network.
destination_cost = 11.2
pr_cost = 5.0
```
#### For Developers
Applications can dynamically set their own stamp values and required link requests costs at runtime. Whenever the values are adjusted, the destination will have to send an announce for the updated information to become known by the rest of the network.
If you are setting these values at destination creation time, ensure that they are set *immediately* after the destination is instantiated, as Reticulum may queue internal, instance-local announces for the destination shortly after creation, so that the local shared instance and its clients are aware of the newly created destination.
```python
# Create a new destination
my_destination = RNS.Destination(
my_identity,
RNS.Destination.IN,
RNS.Destination.SINGLE,
"myapp", "service"
)
# Configure stamps
my_destination.set_value(30.0)
my_destination.set_link_cost(15.0)
```
Dynamically adjusting link request costs is a viable and intended mechanism for mitigating resource abuse, scraping, DoS attempts and other malicious behaviour. An application may implement mechanisms to statically or dynamically raise link request costs under certain conditions.
It is also possible for application code to directly get the destination value and link request cost for any known destination:
```python
# Get the value of a known destination
RNS.Identity.recall_stamp_value(destination_hash)
# Get the current link cost requirement
# of a known destination
RNS.Identity.recall_link_cost(destination_hash)
```
An `Identity` can be created with an embedded stamp value, by passing the target value at instantiation time:
```python
# Create a new, stamped identity
my_identity = RNS.Identity(value=24.0)
# Get the value of any known identity
another_identity.get_value()
```
As with destination stamps, this is a one-time generation procedure, that happens at Identity creation. Once an identity is created with an embedded stamp, its value *cannot* be upgraded at a later point as with detached stamps.
## Filtering & QoS
TODO: Section explaining the `[filter]` configuration options, for creating allow and blocklists for specific destination types.
## Blackhole Management
TODO: Section explaining the blackhole system conceptually (including distributed updates from other nodes), with a few terse examples for either locally - or across an entire managed network - blocking specific identities (and therefore any destination types created by such), as well as blocking incoming (identified) link requests from that identity at terminus.
## Ingress & Burst Control
TODO: Section explaining the rate-limiting, ingress control and burst limiters conceptually, with a few, terse examples on how to configure them (linked references to other more extensive documentation sections of the options).

View file

@ -178,12 +178,14 @@ 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.
You can generate a much more verbose configuration example by running the command:
The example above does not document all the available options, only the basics.
To explore all the various configuration options available, you can generate a
much more verbose and complete configuration example by running the command:
`rnsd --exampleconfig`
The output includes examples for most interface types supported
by Reticulum, along with additional options and configuration parameters.
The output includes examples for most interface types supported by Reticulum,
along with additional options and configuration parameters.
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.
@ -617,7 +619,7 @@ Or fetch a file from the remote system:
$ rncp --fetch ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
```
The default identity file is stored in `~/.reticulum/identities/rncp`, but you can use
The default identity file is stored in `~/.reticulum/storage/identities/rncp`, but you can use
another one, which will be created if it does not already exist
```text
@ -700,7 +702,7 @@ Or enter the interactive mode pseudo-shell:
$ rnx 7a55144adf826958a9529a3bcf08b149 -x
```
The default identity file is stored in `~/.reticulum/identities/rnx`, but you can use
The default identity file is stored in `~/.reticulum/storage/identities/rnx`, but you can use
another one, which will be created if it does not already exist
```text
@ -912,9 +914,10 @@ When connecting to a remote listener, several options are available:
**Identity & Destination**
The default identity file for `rnsh` is stored at
`~/.reticulum/identities/rnsh`, but you can specify a different one with the
`-i` option, which will be created if it does not already exist:
The default initiator identity file for `rnsh` is stored at
`~/.rns/identity` (default listener identity is in `~/.rns/identity.default`),
but you can specify a different one with the `-i` option, which will be created if
it does not already exist:
```text
$ rnsh -l -i /path/to/identity
@ -1402,6 +1405,7 @@ Type=simple
Restart=always
RestartSec=3
User=USERNAMEHERE
Environment=MALLOC_ARENA_MAX=2
ExecStart=rnsd --service
[Install]
@ -1442,6 +1446,7 @@ After=default.target
Type=simple
Restart=always
RestartSec=3
Environment=MALLOC_ARENA_MAX=2
ExecStart=RNS_BIN_DIR/rnsd --service
[Install]

View file

@ -23,6 +23,7 @@ to participate in the development of Reticulum itself.
zen
software
using
stamps
understanding
hardware
interfaces

251
docs/source/stamps.rst Normal file
View file

@ -0,0 +1,251 @@
************************
Protecting Open Networks
************************
.. important::
Reticulum is currently transitioning towards full, on-network stamp verification and enforcement via a phased transition:
- The ``1.6.0`` release completely implements the required mechanisms, and will start excercising the verification system in the transport backend. By default, ``1.6.0`` does not enable full stamp generation, emission and enforcement, but all of these options can be early-enabled in the configuration.
- The ``1.6.1`` release will enable full stamp generation and emission of all types by default, but will leave the *enforcement* a configurable option.
- The ``1.6.2`` release will complete the transition, activating full stamp enforcement across all the systems.
The stated version numbers are the *intended* release sequence. If any issues or implementation problems are found during the initial network deployments, the transition points may be pushed later than this plan by interim releases.
While you can create entirely closed-off and private networks with Reticulum, the protocol itself is open and permissionless. On widely interconnected networks, anyone can create identities and globally reachable destinations without external permission or approval, and establish links anonymously over the network.
Such capabilities are powerful, and a required characteristic of a truly functional communications fabric, but also raise very large challenges, that have been almost impossible to solve in legacy networking technologies.
Reticulum approaches this particular problem, like most others, by employing cryptographic principles. This provides a comprehensive, multi-layered repertoire of defense mechanisms, which can be composed and employed in very effective ways.
In contrast to other networking paradigms, these mechanisms do not have to be bolted on to the application layer in hindsight, but are a core part of the protocol itself, which means that they can be applied universally and effectively:
All nodes help combat spam and network abuse, according to the rules *set by the actual owners of supplied resources* - not by any bureaucracy or external authority.
Rules and requirements can be adjusted live, dynamically and directly, and by those that actually operate and run the infrastructure and services.
The system has been designed so that it becomes very cheap computationally for resource-providing nodes to verify or reject traffic, and very expensive for malicious nodes to abuse the shared resources provided by the network's operators.
Cryptographic Stamps
====================
All networking primitives that consume shared network resources are gated by *stamps*. A stamp is compact, cryptographic token that proves that a certain amount of computation and energy has been expended in its creation.
The amount of such computation required for a stamp to be considered valid can be configured individually by the operator of the resource being made available, whether that is network transport, a node providing information for retrieval, a shared voice room, or something else entirely.
While the core functionality is completely automatic, and handled by Reticulum itself, the primitives are made available at the application layer API as well, so that developers can use them to implement further protections, if required by their usage scenarios. In most cases, however, simply setting the target *values* and required *costs* for the built-in mechanisms will be sufficient.
The *value* of a stamp is a decimal representation of how difficult a stamp was to create, on a scale from ``0.0`` to ``100.0``. The scale is **exponential**. An increase of one point is equal to *doubling* the average compute time required. Fractional values are supported, such as ``14.125``.
Internally, the fractional part is quantized to ``256`` different values, giving an approximately ``0.4%`` difficulty increase per step. You can use any decimal number when configuring stamps, such as ``9.3691`` and you do not have to worry about "landing on" the correct step values. Reticulum will automatically handle the quantization, wire-transport representation and value comparisons.
The term *cost* is used everywhere a stamp value *requirement* is configured or specified. In general, *value* refers to the actual, determined value of a given stamp, *cost* refers to a value requirement.
Base Primitives
---------------
Reticulum provides two types of base stamp primitives:
* **Detached stamps** can be tied to any external information, and are useful for stamping both static information and for one-time verification purposes. The stamp itself is a detached, short binary sequence, typically 14 to 32 bytes, that can be verified directly against the stamped material.
They can be configured from relatively easy to compute, even for embbedded systems and microcontrollers, all the way to something that is practically impossible, even with all the compute and memory on the planet.
* **Embedded stamps** are tied directly to a Reticulum Identity keyset, and embedded within it. The keyset itself *contains* the stamp, and there is no external, detached byte sequence for them.
Anyone can verify the value of an identity-embedded stamp simply from the public key material of the identity.
On-Network Types
----------------
The base primitives are used to implement scenario-specific network-level primitives that, if configured correctly, make spam and network abuse expensive, but validation and enforcement cheap and efficient.
* **Destination Stamps** are detached stamps associated with reticulum destinations. They are included in all announces sent by a destination, and by verifying that their value matches a transport node's cost requirement, they can be either accepted for rebroadcast onto the network, or rejected and dropped.
Destination stamps are *one-time* generations, and are reusable across announces. They limit the number of *new* destinations that can be created, and makes it expensive to spam a network with destinations that do not provide anything meaningful. As such, these stamps will typically target relatively high values, and their cost requirements should be set accordingly.
A generation time for such stamps in *minutes* rather than seconds can very well be reasonable on large, open-access networks. Due to their detached nature, they can also be pre-generated off-device (and do not require the private key material for generation), so that even low-powered nodes, such as microcontrollers, can use high-value destination stamps, by having them generated and loaded externally as a one-time procedure.
* **Path Request Stamps** are also detached stamps, but generated *individually* for every path request emitted on the network. These will typically have a much lower cost requirement than destination stamps, but if a node is overwhelmed by path requests, it can be tuned higher.
The stamp is generated against the individually unique *emission*, so that unstamped or low-value path requests for a destination cannot disrupt the resolution of legitimate ones toward that same destination.
* **Link Request Stamps** embedded stamps, carried in the ephemeral link request keyset. They are therefore completely transparent to the network, but can still be verified extremely quickly by any node along the link request path, who can then make a decision on whether or not to transport it.
Link request cost targets are set by the *endpoint destinations individually*. Every destination that includes a stamp in its announces will also include link request cost signalling. This means that any node that hears an announce from the destination will also know what link request stamp value to target, when establishing links to that destination.
Furthermore, spam and link request abuse can be filtered before even reaching the destination, if at least one node along the path validates the link request stamp value and cost requirement.
All of the stamp primitives, functionality and on-wire signalling is *transparent and backwards-compatible* with older versions of Reticulum transport nodes. This means, that even if a node doesn't itself understand stamp functionality, it will still transport all the required information. Stamped announces, path and link requests can cross older, non stamp-aware network segments transparently and unaffected.
.. _stamps-configuring:
Configuring Stamps
------------------
Reticulum, and its included utilities, provide sane default cost requirements and value targets for the different types of network stamps, but it is entirely up to the operator whether to follow the defaults. All of them are configurable on a per-node, per-application and per-destination basis.
Instance Configuration
^^^^^^^^^^^^^^^^^^^^^^
In reality, different kinds of networks will want to configure different kinds of costs and value targets for their use. For instance-wide defaults and settings, you can configure these in the ``[stamps]`` section of the Reticulum configuration file:
* | The ``stamp_destinations`` option enables generation and emission
of destination stamps in announces. This is a transitory option.
It will become mandatory and enabled by default in RNS ``1.6.1``.
* | The ``stamp_prs`` option enables stamping of path requests emitted
by this instance. This is a transitory option. It will become
mandatory and enabled by default in RNS ``1.6.1``.
* | The ``always_stamp_lrs`` option will stamp *all* outgoing link
requests, even to destinations that have not announced a link
request cost (and will, in that case, use the configured or
default link request cost). This option is mostly useful for
testing and diagnostics. In general use, Reticulum will handle
link request stamping and cost targets automatically.
* | The ``enforce_stamps`` option allows early activation of stamp
enforcement. When enabled, announces and path requests that do
not meet the configured cost requirements are dropped, and link
requests with insufficient stamps are ignored. This is a transitory
option. It will become mandatory and enabled by default in RNS
``1.6.2``.
* | The ``destination_cost`` option sets the default required stamp
cost for announced destinations to be accepted, and have their
announces propagated by this node. Defaults to ``23.5``.
* | The ``destination_value`` option sets the default stamp value that
this instance will target when generating new destination stamps.
An application can request higher targets for destinations that it
creates, but a requested lower value will always be clamped to the
configured default as a minimum. Defaults to ``25.0``.
*Destination stamps are one-time generations per destination, so it
is generally a good idea to target a slightly higher value than the
minimum required cost of the networks you want the destination to
be reachable on.*
* | The ``pr_cost`` option sets the required stamp cost for incoming
path requests. Defaults to ``15.8``.
* | The ``pr_value`` option sets the target stamp value for path
request stamps generated by this instance. Defaults to ``15.8``.
* | The ``lr_cost`` option sets the default link request stamp cost,
that destinations created on this instance will require. This
value can be freely overridden by applications that specify their
own link request cost requirements, and is solely used as the
default if no such specification is provided. Defaults to ``12.5``.
* | The ``lr_stamp_timeout`` and ``pr_stamp_timeout`` options set the
maximum amount of time, in seconds, to spend while attempting to
generate link and path request stamps respectively. If a stamp is
not generated within this timespan, the generation is cancelled,
and the link request or path request fails. Defaults to ``15``
seconds for both options.
An example of customised stamp cost and value configuration follows below:
.. code:: ini
[stamps]
stamp_destinations = yes
stamp_prs = yes
destination_cost = 24.8
destination_value = 26.25
pr_cost = 15.8
pr_value = 16.45
Stamp cost requirements can also be configured on a per-interface basis:
.. code:: ini
[[Public Gateway]]
type = BackboneInterface
mode = gateway
listen_on = 0.0.0.0
port = 4242
destination_cost = 25.0
pr_cost = 17.2
[[Local RNode]]
type = RNodeInterface
port = /dev/ttyUSB0
# Much lower requirements
# for the local network.
destination_cost = 11.2
pr_cost = 5.0
For Developers
^^^^^^^^^^^^^^
Applications can dynamically set their own stamp values and required link requests costs at runtime. Whenever the values are adjusted, the destination will have to send an announce for the updated information to become known by the rest of the network.
If you are setting these values at destination creation time, ensure that they are set *immediately* after the destination is instantiated, as Reticulum may queue internal, instance-local announces for the destination shortly after creation, so that the local shared instance and its clients are aware of the newly created destination.
.. code:: python
# Create a new destination
my_destination = RNS.Destination(
my_identity,
RNS.Destination.IN,
RNS.Destination.SINGLE,
"myapp", "service"
)
# Configure stamps
my_destination.set_value(30.0)
my_destination.set_link_cost(15.0)
Dynamically adjusting link request costs is a viable and intended mechanism for mitigating resource abuse, scraping, DoS attempts and other malicious behaviour. An application may implement mechanisms to statically or dynamically raise link request costs under certain conditions.
.. tip::
Remember here, though, that announce cadence should be preserved for such situations! If your destination is announcing too often in general, and wants to dynamically adjust link request costs at a critical moment, it may already have exhausted its announce rate limits on upstream nodes. So plan your application's announce cadence thoughtfully!
It is also possible for application code to directly get the destination value and link request cost for any known destination:
.. code:: python
# Get the value of a known destination
RNS.Identity.recall_stamp_value(destination_hash)
# Get the current link cost requirement
# of a known destination
RNS.Identity.recall_link_cost(destination_hash)
An ``Identity`` can be created with an embedded stamp value, by passing the target value at instantiation time:
.. code:: python
# Create a new, stamped identity
my_identity = RNS.Identity(value=24.0)
# Get the value of any known identity
another_identity.get_value()
As with destination stamps, this is a one-time generation procedure, that happens at Identity creation. Once an identity is created with an embedded stamp, its value *cannot* be upgraded at a later point as with detached stamps.
Filtering & QoS
===============
TODO: Section explaining the ``[filter]`` configuration options, for creating allow and blocklists for specific destination types.
Blackhole Management
====================
TODO: Section explaining the blackhole system conceptually (including distributed updates from other nodes), with a few terse examples for either locally - or across an entire managed network - blocking specific identities (and therefore any destination types created by such), as well as blocking incoming (identified) link requests from that identity at terminus.
Ingress & Burst Control
=======================
TODO: Section explaining the rate-limiting, ingress control and burst limiters conceptually, with a few, terse examples on how to configure them (linked references to other more extensive documentation sections of the options).