diff --git a/docs/manual/_sources/interfaces.rst.txt b/docs/manual/_sources/interfaces.rst.txt index 4c15e2f..67f6dae 100644 --- a/docs/manual/_sources/interfaces.rst.txt +++ b/docs/manual/_sources/interfaces.rst.txt @@ -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: diff --git a/docs/manual/_sources/support.rst.txt b/docs/manual/_sources/support.rst.txt index 006ec2a..5683d78 100644 --- a/docs/manual/_sources/support.rst.txt +++ b/docs/manual/_sources/support.rst.txt @@ -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 `_ to -report issues, suggest functionality and contribute code to Reticulum. diff --git a/docs/manual/_sources/understanding.rst.txt b/docs/manual/_sources/understanding.rst.txt index f7402b3..b1e45d2 100644 --- a/docs/manual/_sources/understanding.rst.txt +++ b/docs/manual/_sources/understanding.rst.txt @@ -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. diff --git a/docs/manual/_sources/using.rst.txt b/docs/manual/_sources/using.rst.txt index b0ec654..bfb7d47 100644 --- a/docs/manual/_sources/using.rst.txt +++ b/docs/manual/_sources/using.rst.txt @@ -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 ------------------------------ diff --git a/docs/manual/index.html b/docs/manual/index.html index 15192b4..a713fc8 100644 --- a/docs/manual/index.html +++ b/docs/manual/index.html @@ -443,7 +443,6 @@ to participate in the development of Reticulum itself.

  • Support Reticulum
  • Code Examples diff --git a/docs/manual/understanding.html b/docs/manual/understanding.html index 981deb5..9adea13 100644 --- a/docs/manual/understanding.html +++ b/docs/manual/understanding.html @@ -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.

    -

    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.

    diff --git a/docs/manual/using.html b/docs/manual/using.html index 6f683aa..3071788 100644 --- a/docs/manual/using.html +++ b/docs/manual/using.html @@ -1091,8 +1091,8 @@ remote_management_allowed = 9fb6d773498fb3feda407ed8ef2c3229, 2d882c5586e548d79b

    Blackhole Management

    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.

    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.

    This provides users and operators with control over what they want to allow on their own network segments, but there is no way to globally censor or remove an identity, as long as someone is willing to provide transport for it.

    @@ -1135,8 +1135,7 @@ remote_management_allowed = 9fb6d773498fb3feda407ed8ef2c3229, 2d882c5586e548d79b

    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.

    +

    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.

    Configuration

    @@ -1150,9 +1149,9 @@ Subscribing to a blackhole source is a powerful action that grants that source t

    How It Works

      -

    1. The BlackholeUpdater service runs in the background.

      2. -

    2. For every identity hash listed in blackhole_sources, it attempts to establish a temporary link to the destination rnstransport.info.blackhole.

      3. -

    3. It requests the /list path, which returns a dictionary of blocked identities and their associated metadata.

      4. +

    4. When enabled, the BlackholeUpdater service runs in the background.

      5. +

    5. For every identity hash listed in blackhole_sources, it attempts to establish a temporary link to its associated``rnstransport.info.blackhole`` destination.

      6. +

    6. It requests the /list path, which returns a dictionary of blackholed identities and their associated metadata.

    7. The received list is merged with your local blackholed_identities database.

    8. The lists are persisted to disk, ensuring they survive restarts.

    @@ -1163,7 +1162,7 @@ Subscribing to a blackhole source is a powerful action that grants that source t

    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

    To publish your local blackhole list, enable the publish_blackhole option in the [reticulum] section:

    [reticulum]
@@ -1176,7 +1175,7 @@ Subscribing to a blackhole source is a powerful action that grants that source t
 
    Federation and Trust
    
 
    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.
    
 
    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.
    diff --git a/docs/source/support.rst b/docs/source/support.rst index 006ec2a..5683d78 100644 --- a/docs/source/support.rst +++ b/docs/source/support.rst @@ -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 `_ to -report issues, suggest functionality and contribute code to Reticulum. diff --git a/docs/source/understanding.rst b/docs/source/understanding.rst index f7402b3..b1e45d2 100644 --- a/docs/source/understanding.rst +++ b/docs/source/understanding.rst @@ -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. diff --git a/docs/source/using.rst b/docs/source/using.rst index b0ec654..bfb7d47 100644 --- a/docs/source/using.rst +++ b/docs/source/using.rst @@ -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 ------------------------------