Updated docs

This commit is contained in:
Mark Qvist 2026-01-04 12:22:08 +01:00
commit a1e6ce2357
13 changed files with 91 additions and 61 deletions

View file

@ -966,7 +966,7 @@ When ``discoverable`` is enabled, a variety of additional options become availab
**Dynamic Resolution:** This option also accepts a path to an external executable script or binary. If a path is provided, Reticulum will execute the script and use its ``stdout`` as the reachability address. This is useful for devices behind dynamic DNS, NATs, or complex cloud environments where the external IP is not known locally. The script must simply print the address to stdout and exit.
.. note:: **Script Execution Requirements:**
.. note::
When using an executable script for ``reachable_on``, Reticulum expects the script to output only the IP address or hostname to ``stdout``, followed by a newline character. Any additional output or errors may cause the resolution to fail. Ensure the script has executable permissions and is robust against temporary network failures.
A minimal example of a script that resolves the externally available, public IP of an internet-connected system could look like this:

View file

@ -33,15 +33,28 @@ organisation? Make them a reality quickly by sponsoring their implementation.
Provide Feedback
================
All feedback on the usage, functioning and potential dysfunctioning of any and
Feedback on the usage, functioning and potential dysfunctioning of any and
all components of the system is very valuable to the continued development and
improvement of Reticulum.
improvement of Reticulum. But...
.. warning::
**Think before you speak**. As time has shown, over 80% of the "feedback",
"bug reports" and "advice" the Reticulum project has received has been
irrelevant noise, stemming from erroneous assumptions, misunderstanding the
foundational functionality or philosophy behind the system, or simply
the malinformed (but overly opinionated) personal preferences of individual
drive-by architects. This wastes the time of everyone involved.
The Reticulum project is not a public teahouse for serving the attention
needs of random bypassers, but a highly complex system engineered and
refined over more than a decade, designed to provide communication and
connectivity guarantees in highly adversarial environments.
If you want to voice your opinion, it better be well-informed, and we
expect you to have a comprehensive and solid foundation for your points
of view. Everything else will be ignored.
Absolutely no automated analytics, telemetry, error
reporting or statistics is collected and reported by Reticulum under any
circumstances, so we rely on old-fashioned human feedback.
Contribute Code
===============
Join us on `the GitHub repository <https://github.com/markqvist/reticulum>`_ to
report issues, suggest functionality and contribute code to Reticulum.

View file

@ -13,9 +13,8 @@ reference implementation and API reference. That being said, this chapter is an
understanding how Reticulum works from a high-level perspective, along with the general principles of
Reticulum, and how to apply them when creating your own networks or software.
After reading this document, you should be well-equipped to understand how a Reticulum network
operates, what it can achieve, and how you can use it yourself. If you want to help out with the
development, this is also the place to start, since it will provide a pretty clear overview of the
After reading this chapter, you should be well-equipped to understand how a Reticulum network
operates, what it can achieve, and how you can use it yourself. This chapter also seeks to provide an overview of the
sentiments and the philosophy behind Reticulum, what problems it seeks to solve, and how it
approaches those solutions.

View file

@ -967,7 +967,7 @@ Reticulum networks are fundamentally permissionless and open, allowing anyone wi
The **Blackhole** system provides tools to help manage this problem. It allows operators and individual users to block specific identities at the Transport layer, preventing them from propagating announces through your node, and for other nodes to reach them through your network.
.. note::
.. important::
There is fundamentally **no way** to *globally* block or censor any identity or destination in Reticulum networks. The blackhole functionality will prevent announces from (and traffic to) all destinations associated with the blackholed identity *on your own network segments only*.
@ -1027,8 +1027,8 @@ Automated List Sourcing
Manually blocking identities is effective for immediate threats, but maintaining an up-to-date blocklist for a large network is impractical. Reticulum supports **automated list sourcing**, allowing your node to subscribe to blackhole lists maintained by trusted peers, or a central authority you manage yourself.
.. warning:: **Verify Before Subscribing!**
Subscribing to a blackhole source is a powerful action that grants that source the ability to dictate who you can communicate with. Before adding a source to your configuration, verify that the maintainer aligns with your usage policy and values. Blindly subscribing to untrusted lists could inadvertently block legitimate peers or essential services.
.. warning::
**Verify Before Subscribing!** Subscribing to a blackhole source is a powerful action that grants that source the ability to dictate who you can communicate with. Before adding a source to your configuration, verify that the maintainer aligns with your usage policy and values. Blindly subscribing to untrusted lists could inadvertently block legitimate peers or essential services.
When enabled, your Transport Instance will periodically (approximately once per hour) connect to configured sources, retrieve their latest blackhole lists, and automatically merge them into your local blocklist. This provides "set-and-forget" protection for both individual users and large networks.
@ -1046,9 +1046,9 @@ To enable automated sourcing, add the ``blackhole_sources`` option to the ``[ret
**How It Works**
1. The ``BlackholeUpdater`` service runs in the background.
2. For every identity hash listed in ``blackhole_sources``, it attempts to establish a temporary link to the destination ``rnstransport.info.blackhole``.
3. It requests the ``/list`` path, which returns a dictionary of blocked identities and their associated metadata.
1. When enabled, the ``BlackholeUpdater`` service runs in the background.
2. For every identity hash listed in ``blackhole_sources``, it attempts to establish a temporary link to its associated``rnstransport.info.blackhole`` destination.
3. It requests the ``/list`` path, which returns a dictionary of blackholed identities and their associated metadata.
4. The received list is merged with your local ``blackholed_identities`` database.
5. The lists are persisted to disk, ensuring they survive restarts.
@ -1059,7 +1059,7 @@ To enable automated sourcing, add the ``blackhole_sources`` option to the ``[ret
Publishing Blackhole Lists
==========================
If you are operating a public gateway, a community hub, or simply wish to share your blocklist with others, you can configure your instance to act as a blackhole list publisher. This allows other nodes to subscribe to *your* definitions of unwanted traffic.
If you are operating a public gateway, a community hub, or simply wish to share your blackhole list with others, you can configure your instance to act as a blackhole list publisher. This allows other nodes to subscribe to *your* definitions of unwanted traffic.
**Enabling Publishing**
@ -1080,7 +1080,7 @@ The blackhole system relies on the trust relationship between the subscriber and
As the ecosystem matures, this system is designed to integrate with **Network Identities**. This allows communities to verify that a published blackhole list is actually provided by a specific network or organization with a certain level of reputation and trustworthiness, adding a layer of cryptographic trust to the federation process. This prevents malicious actors from publishing fake lists intended to censor legitimate traffic.
For operators, this creates a scalable model where maintaining a single high-quality blocklist can protect thousands of downstream peers, drastically reducing the administrative overhead of network hygiene.
For operators, this creates a scalable model where maintaining a single high-quality blocklist can protect thousands of downstream peers, drastically reducing the administrative.
Improving System Configuration
------------------------------

View file

@ -443,7 +443,6 @@ to participate in the development of Reticulum itself.</p>
<li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a><ul>
<li class="toctree-l2"><a class="reference internal" href="support.html#donations">Donations</a></li>
<li class="toctree-l2"><a class="reference internal" href="support.html#provide-feedback">Provide Feedback</a></li>
<li class="toctree-l2"><a class="reference internal" href="support.html#contribute-code">Contribute Code</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a><ul>

View file

@ -1120,8 +1120,7 @@ relevant regulation for your location, and to make decisions accordingly.</p>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p><strong>Script Execution Requirements:</strong>
When using an executable script for <code class="docutils literal notranslate"><span class="pre">reachable_on</span></code>, Reticulum expects the script to output only the IP address or hostname to <code class="docutils literal notranslate"><span class="pre">stdout</span></code>, followed by a newline character. Any additional output or errors may cause the resolution to fail. Ensure the script has executable permissions and is robust against temporary network failures.</p>
<p>When using an executable script for <code class="docutils literal notranslate"><span class="pre">reachable_on</span></code>, Reticulum expects the script to output only the IP address or hostname to <code class="docutils literal notranslate"><span class="pre">stdout</span></code>, followed by a newline character. Any additional output or errors may cause the resolution to fail. Ensure the script has executable permissions and is robust against temporary network failures.</p>
</div>
<p>A minimal example of a script that resolves the externally available, public IP of an internet-connected system could look like this:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/bin/bash</span>

File diff suppressed because one or more lines are too long

View file

@ -285,18 +285,29 @@ organisation? Make them a reality quickly by sponsoring their implementation.</p
</section>
<section id="provide-feedback">
<h2>Provide Feedback<a class="headerlink" href="#provide-feedback" title="Link to this heading"></a></h2>
<p>All feedback on the usage, functioning and potential dysfunctioning of any and
<p>Feedback on the usage, functioning and potential dysfunctioning of any and
all components of the system is very valuable to the continued development and
improvement of Reticulum.</p>
improvement of Reticulum. But…</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p><strong>Think before you speak</strong>. As time has shown, over 80% of the “feedback”,
“bug reports” and “advice” the Reticulum project has received has been
irrelevant noise, stemming from erroneous assumptions, misunderstanding the
foundational functionality or philosophy behind the system, or simply
the malinformed (but overly opinionated) personal preferences of individual
drive-by architects. This wastes the time of everyone involved.</p>
<p>The Reticulum project is not a public teahouse for serving the attention
needs of random bypassers, but a highly complex system engineered and
refined over more than a decade, designed to provide communication and
connectivity guarantees in highly adversarial environments.</p>
<p>If you want to voice your opinion, it better be well-informed, and we
expect you to have a comprehensive and solid foundation for your points
of view. Everything else will be ignored.</p>
</div>
<p>Absolutely no automated analytics, telemetry, error
reporting or statistics is collected and reported by Reticulum under any
circumstances, so we rely on old-fashioned human feedback.</p>
</section>
<section id="contribute-code">
<h2>Contribute Code<a class="headerlink" href="#contribute-code" title="Link to this heading"></a></h2>
<p>Join us on <a class="reference external" href="https://github.com/markqvist/reticulum">the GitHub repository</a> to
report issues, suggest functionality and contribute code to Reticulum.</p>
</section>
</section>
</article>
@ -356,7 +367,6 @@ report issues, suggest functionality and contribute code to Reticulum.</p>
<li><a class="reference internal" href="#">Support Reticulum</a><ul>
<li><a class="reference internal" href="#donations">Donations</a></li>
<li><a class="reference internal" href="#provide-feedback">Provide Feedback</a></li>
<li><a class="reference internal" href="#contribute-code">Contribute Code</a></li>
</ul>
</li>
</ul>

View file

@ -267,9 +267,8 @@ the only complete repository, and final authority on how Reticulum actually func
reference implementation and API reference. That being said, this chapter is an essential resource in
understanding how Reticulum works from a high-level perspective, along with the general principles of
Reticulum, and how to apply them when creating your own networks or software.</p>
<p>After reading this document, you should be well-equipped to understand how a Reticulum network
operates, what it can achieve, and how you can use it yourself. If you want to help out with the
development, this is also the place to start, since it will provide a pretty clear overview of the
<p>After reading this chapter, you should be well-equipped to understand how a Reticulum network
operates, what it can achieve, and how you can use it yourself. This chapter also seeks to provide an overview of the
sentiments and the philosophy behind Reticulum, what problems it seeks to solve, and how it
approaches those solutions.</p>
<section id="motivation">

View file

@ -1091,8 +1091,8 @@ remote_management_allowed = 9fb6d773498fb3feda407ed8ef2c3229, 2d882c5586e548d79b
<span id="using-blackhole-management"></span><h2>Blackhole Management<a class="headerlink" href="#blackhole-management" title="Link to this heading"></a></h2>
<p>Reticulum networks are fundamentally permissionless and open, allowing anyone with a compatible interface to participate. While this openness is essential for a resilient and decentralized network, it also exposes the network to potential abuse, such as peers flooding the network with excessive announce broadcasts or other forms of resource exhaustion.</p>
<p>The <strong>Blackhole</strong> system provides tools to help manage this problem. It allows operators and individual users to block specific identities at the Transport layer, preventing them from propagating announces through your node, and for other nodes to reach them through your network.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>There is fundamentally <strong>no way</strong> to <em>globally</em> block or censor any identity or destination in Reticulum networks. The blackhole functionality will prevent announces from (and traffic to) all destinations associated with the blackholed identity <em>on your own network segments only</em>.</p>
<p>This provides users and operators with control over what they want to allow <em>on their own network segments</em>, but there is no way to globally censor or remove an identity, as long as <em>someone</em> is willing to provide transport for it.</p>
</div>
@ -1135,8 +1135,7 @@ remote_management_allowed = 9fb6d773498fb3feda407ed8ef2c3229, 2d882c5586e548d79b
<p>Manually blocking identities is effective for immediate threats, but maintaining an up-to-date blocklist for a large network is impractical. Reticulum supports <strong>automated list sourcing</strong>, allowing your node to subscribe to blackhole lists maintained by trusted peers, or a central authority you manage yourself.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p><strong>Verify Before Subscribing!</strong>
Subscribing to a blackhole source is a powerful action that grants that source the ability to dictate who you can communicate with. Before adding a source to your configuration, verify that the maintainer aligns with your usage policy and values. Blindly subscribing to untrusted lists could inadvertently block legitimate peers or essential services.</p>
<p><strong>Verify Before Subscribing!</strong> Subscribing to a blackhole source is a powerful action that grants that source the ability to dictate who you can communicate with. Before adding a source to your configuration, verify that the maintainer aligns with your usage policy and values. Blindly subscribing to untrusted lists could inadvertently block legitimate peers or essential services.</p>
</div>
<p>When enabled, your Transport Instance will periodically (approximately once per hour) connect to configured sources, retrieve their latest blackhole lists, and automatically merge them into your local blocklist. This provides “set-and-forget” protection for both individual users and large networks.</p>
<p><strong>Configuration</strong></p>
@ -1150,9 +1149,9 @@ Subscribing to a blackhole source is a powerful action that grants that source t
</div>
<p><strong>How It Works</strong></p>
<ol class="arabic simple">
<li><p>The <code class="docutils literal notranslate"><span class="pre">BlackholeUpdater</span></code> service runs in the background.</p></li>
<li><p>For every identity hash listed in <code class="docutils literal notranslate"><span class="pre">blackhole_sources</span></code>, it attempts to establish a temporary link to the destination <code class="docutils literal notranslate"><span class="pre">rnstransport.info.blackhole</span></code>.</p></li>
<li><p>It requests the <code class="docutils literal notranslate"><span class="pre">/list</span></code> path, which returns a dictionary of blocked identities and their associated metadata.</p></li>
<li><p>When enabled, the <code class="docutils literal notranslate"><span class="pre">BlackholeUpdater</span></code> service runs in the background.</p></li>
<li><p>For every identity hash listed in <code class="docutils literal notranslate"><span class="pre">blackhole_sources</span></code>, it attempts to establish a temporary link to its associated``rnstransport.info.blackhole`` destination.</p></li>
<li><p>It requests the <code class="docutils literal notranslate"><span class="pre">/list</span></code> path, which returns a dictionary of blackholed identities and their associated metadata.</p></li>
<li><p>The received list is merged with your local <code class="docutils literal notranslate"><span class="pre">blackholed_identities</span></code> database.</p></li>
<li><p>The lists are persisted to disk, ensuring they survive restarts.</p></li>
</ol>
@ -1163,7 +1162,7 @@ Subscribing to a blackhole source is a powerful action that grants that source t
</section>
<section id="publishing-blackhole-lists">
<h3>Publishing Blackhole Lists<a class="headerlink" href="#publishing-blackhole-lists" title="Link to this heading"></a></h3>
<p>If you are operating a public gateway, a community hub, or simply wish to share your blocklist with others, you can configure your instance to act as a blackhole list publisher. This allows other nodes to subscribe to <em>your</em> definitions of unwanted traffic.</p>
<p>If you are operating a public gateway, a community hub, or simply wish to share your blackhole list with others, you can configure your instance to act as a blackhole list publisher. This allows other nodes to subscribe to <em>your</em> definitions of unwanted traffic.</p>
<p><strong>Enabling Publishing</strong></p>
<p>To publish your local blackhole list, enable the <code class="docutils literal notranslate"><span class="pre">publish_blackhole</span></code> option in the <code class="docutils literal notranslate"><span class="pre">[reticulum]</span></code> section:</p>
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[reticulum]</span>
@ -1176,7 +1175,7 @@ Subscribing to a blackhole source is a powerful action that grants that source t
<p><strong>Federation and Trust</strong></p>
<p>The blackhole system relies on the trust relationship between the subscriber and the publisher. By subscribing to a source, you are implicitly trusting that source to only block identities that are genuinely detrimental to the network.</p>
<p>As the ecosystem matures, this system is designed to integrate with <strong>Network Identities</strong>. This allows communities to verify that a published blackhole list is actually provided by a specific network or organization with a certain level of reputation and trustworthiness, adding a layer of cryptographic trust to the federation process. This prevents malicious actors from publishing fake lists intended to censor legitimate traffic.</p>
<p>For operators, this creates a scalable model where maintaining a single high-quality blocklist can protect thousands of downstream peers, drastically reducing the administrative overhead of network hygiene.</p>
<p>For operators, this creates a scalable model where maintaining a single high-quality blocklist can protect thousands of downstream peers, drastically reducing the administrative.</p>
</section>
</section>
<section id="improving-system-configuration">

View file

@ -33,15 +33,28 @@ organisation? Make them a reality quickly by sponsoring their implementation.
Provide Feedback
================
All feedback on the usage, functioning and potential dysfunctioning of any and
Feedback on the usage, functioning and potential dysfunctioning of any and
all components of the system is very valuable to the continued development and
improvement of Reticulum.
improvement of Reticulum. But...
.. warning::
**Think before you speak**. As time has shown, over 80% of the "feedback",
"bug reports" and "advice" the Reticulum project has received has been
irrelevant noise, stemming from erroneous assumptions, misunderstanding the
foundational functionality or philosophy behind the system, or simply
the malinformed (but overly opinionated) personal preferences of individual
drive-by architects. This wastes the time of everyone involved.
The Reticulum project is not a public teahouse for serving the attention
needs of random bypassers, but a highly complex system engineered and
refined over more than a decade, designed to provide communication and
connectivity guarantees in highly adversarial environments.
If you want to voice your opinion, it better be well-informed, and we
expect you to have a comprehensive and solid foundation for your points
of view. Everything else will be ignored.
Absolutely no automated analytics, telemetry, error
reporting or statistics is collected and reported by Reticulum under any
circumstances, so we rely on old-fashioned human feedback.
Contribute Code
===============
Join us on `the GitHub repository <https://github.com/markqvist/reticulum>`_ to
report issues, suggest functionality and contribute code to Reticulum.

View file

@ -13,9 +13,8 @@ reference implementation and API reference. That being said, this chapter is an
understanding how Reticulum works from a high-level perspective, along with the general principles of
Reticulum, and how to apply them when creating your own networks or software.
After reading this document, you should be well-equipped to understand how a Reticulum network
operates, what it can achieve, and how you can use it yourself. If you want to help out with the
development, this is also the place to start, since it will provide a pretty clear overview of the
After reading this chapter, you should be well-equipped to understand how a Reticulum network
operates, what it can achieve, and how you can use it yourself. This chapter also seeks to provide an overview of the
sentiments and the philosophy behind Reticulum, what problems it seeks to solve, and how it
approaches those solutions.

View file

@ -967,7 +967,7 @@ Reticulum networks are fundamentally permissionless and open, allowing anyone wi
The **Blackhole** system provides tools to help manage this problem. It allows operators and individual users to block specific identities at the Transport layer, preventing them from propagating announces through your node, and for other nodes to reach them through your network.
.. note::
.. important::
There is fundamentally **no way** to *globally* block or censor any identity or destination in Reticulum networks. The blackhole functionality will prevent announces from (and traffic to) all destinations associated with the blackholed identity *on your own network segments only*.
@ -1027,8 +1027,8 @@ Automated List Sourcing
Manually blocking identities is effective for immediate threats, but maintaining an up-to-date blocklist for a large network is impractical. Reticulum supports **automated list sourcing**, allowing your node to subscribe to blackhole lists maintained by trusted peers, or a central authority you manage yourself.
.. warning:: **Verify Before Subscribing!**
Subscribing to a blackhole source is a powerful action that grants that source the ability to dictate who you can communicate with. Before adding a source to your configuration, verify that the maintainer aligns with your usage policy and values. Blindly subscribing to untrusted lists could inadvertently block legitimate peers or essential services.
.. warning::
**Verify Before Subscribing!** Subscribing to a blackhole source is a powerful action that grants that source the ability to dictate who you can communicate with. Before adding a source to your configuration, verify that the maintainer aligns with your usage policy and values. Blindly subscribing to untrusted lists could inadvertently block legitimate peers or essential services.
When enabled, your Transport Instance will periodically (approximately once per hour) connect to configured sources, retrieve their latest blackhole lists, and automatically merge them into your local blocklist. This provides "set-and-forget" protection for both individual users and large networks.
@ -1046,9 +1046,9 @@ To enable automated sourcing, add the ``blackhole_sources`` option to the ``[ret
**How It Works**
1. The ``BlackholeUpdater`` service runs in the background.
2. For every identity hash listed in ``blackhole_sources``, it attempts to establish a temporary link to the destination ``rnstransport.info.blackhole``.
3. It requests the ``/list`` path, which returns a dictionary of blocked identities and their associated metadata.
1. When enabled, the ``BlackholeUpdater`` service runs in the background.
2. For every identity hash listed in ``blackhole_sources``, it attempts to establish a temporary link to its associated``rnstransport.info.blackhole`` destination.
3. It requests the ``/list`` path, which returns a dictionary of blackholed identities and their associated metadata.
4. The received list is merged with your local ``blackholed_identities`` database.
5. The lists are persisted to disk, ensuring they survive restarts.
@ -1059,7 +1059,7 @@ To enable automated sourcing, add the ``blackhole_sources`` option to the ``[ret
Publishing Blackhole Lists
==========================
If you are operating a public gateway, a community hub, or simply wish to share your blocklist with others, you can configure your instance to act as a blackhole list publisher. This allows other nodes to subscribe to *your* definitions of unwanted traffic.
If you are operating a public gateway, a community hub, or simply wish to share your blackhole list with others, you can configure your instance to act as a blackhole list publisher. This allows other nodes to subscribe to *your* definitions of unwanted traffic.
**Enabling Publishing**
@ -1080,7 +1080,7 @@ The blackhole system relies on the trust relationship between the subscriber and
As the ecosystem matures, this system is designed to integrate with **Network Identities**. This allows communities to verify that a published blackhole list is actually provided by a specific network or organization with a certain level of reputation and trustworthiness, adding a layer of cryptographic trust to the federation process. This prevents malicious actors from publishing fake lists intended to censor legitimate traffic.
For operators, this creates a scalable model where maintaining a single high-quality blocklist can protect thousands of downstream peers, drastically reducing the administrative overhead of network hygiene.
For operators, this creates a scalable model where maintaining a single high-quality blocklist can protect thousands of downstream peers, drastically reducing the administrative.
Improving System Configuration
------------------------------