mirror of
https://github.com/markqvist/Reticulum.git
synced 2026-04-23 22:29:59 -07:00
Updated docs
This commit is contained in:
Mark Qvist
1
.gitignore
vendored
1
.gitignore
vendored
@@ -13,3 +13,4 @@ tests/rnsconfig/storage
|
||||
tests/rnsconfig/logfile*
|
||||
*.data
|
||||
*.result
|
||||
.buildinfo.bak
|
||||
|
||||
@@ -277,9 +277,9 @@ A common mistake in modern networking is the reliance on a few centralized, hard
|
||||
|
||||
Reticulum encourages the approach of *organic growth*. Instead of relying on permanent static connections to distant servers, you can use temporary bootstrap connections to *discover* better, more relevant or local infrastructure. Once discovered, your system can automatically form stronger, more direct links to these peers, and discard the temporary bootstrap links. This results in a web of connections that are geographically relevant, resilient and efficient.
|
||||
|
||||
It is possible to simply add a few public entrypoints to the ``[interfaces]`` section of your Reticulum configuration and be connected, but a better option is to enable :ref:`interface discovery<using-interface_discovery>` and either manually select relevant, local interfaces, or enable discovered interface auto-connection.
|
||||
It *is* possible to simply add a few public entrypoints to the ``[interfaces]`` section of your Reticulum configuration and be connected, but a better option is to enable :ref:`interface discovery<using-interface_discovery>` and either manually select relevant, local interfaces, or enable discovered interface auto-connection.
|
||||
|
||||
A relevant option in this context is the :ref:`bootstrap only<interfaces-options>` interface option. This is an automated tool for better distributing connectivity. By marking an interface as ``bootstrap_only``, you tell Reticulum: *"Use this connection to find connectivity options, and prefer discovered interfaces once they are available"*. This helps create a network topology that favors locality and resilience over the simple centralization caused by using only a few static entrypoints.
|
||||
A relevant option in this context is the :ref:`bootstrap only<interfaces-options>` interface option. This is an automated tool for better distributing connectivity. By enabling interface discovery and auto-connection, and marking an interface as ``bootstrap_only``, you tell Reticulum to use that interface primarliy to find connectivity options, and then disconnect it once sufficient entrypoints have been discovered. This helps create a network topology that favors locality and resilience over the simple centralization caused by using only a few static entrypoints.
|
||||
|
||||
A good place to find interface definitions for bootstrapping connectivity is `rmap.world <https://rmap.world/>`_.
|
||||
|
||||
@@ -296,7 +296,7 @@ We strongly encourage everyone, even home users, to think in terms of building *
|
||||
* While you sleep, work, or cook, your node listens to the network. It discovers other local community members, validates their Network Identities, and automatically establishes direct links.
|
||||
* Your personal devices now connect to your *local* node, which is integrated into a living, breathing local mesh. Your traffic flows through local paths provided by other real people in the community rather than bouncing off a distant server.
|
||||
|
||||
**Don't wait for others to build the networks you want to see**. Every network is important, perhaps even most so those that support individual families and persons. Once enough of this personal, local infrastructure exist, connecting them directly to each other, without traversing the public Internet, becomes not just possible, but inevitable.
|
||||
**Don't wait for others to build the networks you want to see**. Every network is important, perhaps even most so those that support individual families and persons. Once enough of this personal, local infrastructure exist, connecting them directly to each other, without traversing the public Internet, becomes inevitable.
|
||||
|
||||
|
||||
Mixing Strategies
|
||||
@@ -305,7 +305,7 @@ Mixing Strategies
|
||||
There is no requirement to commit to a single strategy. The most robust setups often mix static, dynamic, and discovered interfaces.
|
||||
|
||||
* **Static Interfaces:** You maintain a permanent interface to a trusted friend or organization using a static configuration.
|
||||
* **Bootstrap Links:** You run a ``bootstrap_only`` TCP interface to a public gateway to scan for new connectable peers or to regain connectivity if your other interfaces fail.
|
||||
* **Bootstrap Links:** You connect a ``bootstrap_only`` interface to a public gateway on the Internet to scan for new connectable peers or to regain connectivity if your other interfaces fail.
|
||||
* **Local Wide-Area Connectivity:** You run a ``RNodeInterface`` on a shared frequency, giving you completely self-sovereign and private wide-area access to both your own network and other Reticulum peers globally, without any "service providers" being able to control or monitor how you interact with people.
|
||||
|
||||
By combining these methods, you create a system that is secure against single points of failure, adaptable to changing network conditions, and better integrated into your physical and social reality.
|
||||
@@ -316,7 +316,7 @@ Network Health & Responsibility
|
||||
|
||||
As you participate in the wider networks you discover and build, you will inevitably encounter peers that are misconfigured, malicious, or simply broken. To protect your resources and those of your local peers, you can utilize the :ref:`Blackhole Management<using-blackhole_management>` system.
|
||||
|
||||
Whether you manually block a spamming identity or subscribe to a blackhole list maintained by a trusted Network Identity, these tools help ensure that your transport capacity is used for legitimate communication. This keeps your local segment efficient and contributes to the health of the wider network.
|
||||
Whether you manually block a spamming identity or subscribe to a blackhole list maintained by a trusted Network Identity, these tools help ensure that *your* transport capacity is used for what *you* consider legitimate communication. This keeps your local segment efficient and contributes to the health of the wider network.
|
||||
|
||||
|
||||
Contributing to the Global Ret
|
||||
|
||||
@@ -916,7 +916,7 @@ beaconing functionality described above.
|
||||
Discoverable Interfaces
|
||||
=======================
|
||||
|
||||
Reticulum includes a powerful system for publishing your local interfaces to the wider network, allowing other peers to discover, validate, and automatically connect to them. 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.
|
||||
Reticulum includes a powerful system for publishing your local interfaces to the wider network, allowing other peers to :ref:`discover, validate, and automatically connect to them<using-interface_discovery>`. 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.
|
||||
|
||||
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.
|
||||
|
||||
@@ -979,7 +979,7 @@ When ``discoverable`` is enabled, a variety of additional options become availab
|
||||
``discovery_encrypt``
|
||||
If set to ``yes``, the discovery announce payload will be encrypted. To decrypt the announce, remote peers must possess the *network identity* configured for your instance (see ``network_identity`` in the ``[reticulum]`` section). This allows you to publish private interfaces that are only discoverable to specific trusted networks.
|
||||
|
||||
.. warning::
|
||||
.. important::
|
||||
If you enable ``discovery_encrypt`` but do not configure a valid ``network_identity`` in the ``[reticulum]`` section of your configuration, Reticulum will abort the interface discovery announce. Encryption requires a valid network identity key to function.
|
||||
|
||||
``publish_ifac``
|
||||
|
||||
@@ -462,8 +462,8 @@ easier setup, use TCP.</p>
|
||||
<p>When you first start using Reticulum, you need a way to obtain connectivity with the peers you want to communicate with. This is the process of <strong>bootstrapping</strong>.</p>
|
||||
<p>A common mistake in modern networking is the reliance on a few centralized, hard-coded entrypoints. If every user simply connects to the same list of public IP addresses found on a website, the network becomes brittle, centralized, and ultimately fails to deliver on the promise of decentralization.</p>
|
||||
<p>Reticulum encourages the approach of <em>organic growth</em>. Instead of relying on permanent static connections to distant servers, you can use temporary bootstrap connections to <em>discover</em> better, more relevant or local infrastructure. Once discovered, your system can automatically form stronger, more direct links to these peers, and discard the temporary bootstrap links. This results in a web of connections that are geographically relevant, resilient and efficient.</p>
|
||||
<p>It is possible to simply add a few public entrypoints to the <code class="docutils literal notranslate"><span class="pre">[interfaces]</span></code> section of your Reticulum configuration and be connected, but a better option is to enable <a class="reference internal" href="using.html#using-interface-discovery"><span class="std std-ref">interface discovery</span></a> and either manually select relevant, local interfaces, or enable discovered interface auto-connection.</p>
|
||||
<p>A relevant option in this context is the <a class="reference internal" href="interfaces.html#interfaces-options"><span class="std std-ref">bootstrap only</span></a> interface option. This is an automated tool for better distributing connectivity. By marking an interface as <code class="docutils literal notranslate"><span class="pre">bootstrap_only</span></code>, you tell Reticulum: <em>“Use this connection to find connectivity options, and prefer discovered interfaces once they are available”</em>. This helps create a network topology that favors locality and resilience over the simple centralization caused by using only a few static entrypoints.</p>
|
||||
<p>It <em>is</em> possible to simply add a few public entrypoints to the <code class="docutils literal notranslate"><span class="pre">[interfaces]</span></code> section of your Reticulum configuration and be connected, but a better option is to enable <a class="reference internal" href="using.html#using-interface-discovery"><span class="std std-ref">interface discovery</span></a> and either manually select relevant, local interfaces, or enable discovered interface auto-connection.</p>
|
||||
<p>A relevant option in this context is the <a class="reference internal" href="interfaces.html#interfaces-options"><span class="std std-ref">bootstrap only</span></a> interface option. This is an automated tool for better distributing connectivity. By enabling interface discovery and auto-connection, and marking an interface as <code class="docutils literal notranslate"><span class="pre">bootstrap_only</span></code>, you tell Reticulum to use that interface primarliy to find connectivity options, and then disconnect it once sufficient entrypoints have been discovered. This helps create a network topology that favors locality and resilience over the simple centralization caused by using only a few static entrypoints.</p>
|
||||
<p>A good place to find interface definitions for bootstrapping connectivity is <a class="reference external" href="https://rmap.world/">rmap.world</a>.</p>
|
||||
</section>
|
||||
<section id="building-personal-infrastructure">
|
||||
@@ -476,14 +476,14 @@ easier setup, use TCP.</p>
|
||||
<li><p>While you sleep, work, or cook, your node listens to the network. It discovers other local community members, validates their Network Identities, and automatically establishes direct links.</p></li>
|
||||
<li><p>Your personal devices now connect to your <em>local</em> node, which is integrated into a living, breathing local mesh. Your traffic flows through local paths provided by other real people in the community rather than bouncing off a distant server.</p></li>
|
||||
</ul>
|
||||
<p><strong>Don’t wait for others to build the networks you want to see</strong>. Every network is important, perhaps even most so those that support individual families and persons. Once enough of this personal, local infrastructure exist, connecting them directly to each other, without traversing the public Internet, becomes not just possible, but inevitable.</p>
|
||||
<p><strong>Don’t wait for others to build the networks you want to see</strong>. Every network is important, perhaps even most so those that support individual families and persons. Once enough of this personal, local infrastructure exist, connecting them directly to each other, without traversing the public Internet, becomes inevitable.</p>
|
||||
</section>
|
||||
<section id="mixing-strategies">
|
||||
<h3>Mixing Strategies<a class="headerlink" href="#mixing-strategies" title="Link to this heading">¶</a></h3>
|
||||
<p>There is no requirement to commit to a single strategy. The most robust setups often mix static, dynamic, and discovered interfaces.</p>
|
||||
<ul class="simple">
|
||||
<li><p><strong>Static Interfaces:</strong> You maintain a permanent interface to a trusted friend or organization using a static configuration.</p></li>
|
||||
<li><p><strong>Bootstrap Links:</strong> You run a <code class="docutils literal notranslate"><span class="pre">bootstrap_only</span></code> TCP interface to a public gateway to scan for new connectable peers or to regain connectivity if your other interfaces fail.</p></li>
|
||||
<li><p><strong>Bootstrap Links:</strong> You connect a <code class="docutils literal notranslate"><span class="pre">bootstrap_only</span></code> interface to a public gateway on the Internet to scan for new connectable peers or to regain connectivity if your other interfaces fail.</p></li>
|
||||
<li><p><strong>Local Wide-Area Connectivity:</strong> You run a <code class="docutils literal notranslate"><span class="pre">RNodeInterface</span></code> on a shared frequency, giving you completely self-sovereign and private wide-area access to both your own network and other Reticulum peers globally, without any “service providers” being able to control or monitor how you interact with people.</p></li>
|
||||
</ul>
|
||||
<p>By combining these methods, you create a system that is secure against single points of failure, adaptable to changing network conditions, and better integrated into your physical and social reality.</p>
|
||||
@@ -491,7 +491,7 @@ easier setup, use TCP.</p>
|
||||
<section id="network-health-responsibility">
|
||||
<h3>Network Health & Responsibility<a class="headerlink" href="#network-health-responsibility" title="Link to this heading">¶</a></h3>
|
||||
<p>As you participate in the wider networks you discover and build, you will inevitably encounter peers that are misconfigured, malicious, or simply broken. To protect your resources and those of your local peers, you can utilize the <a class="reference internal" href="using.html#using-blackhole-management"><span class="std std-ref">Blackhole Management</span></a> system.</p>
|
||||
<p>Whether you manually block a spamming identity or subscribe to a blackhole list maintained by a trusted Network Identity, these tools help ensure that your transport capacity is used for legitimate communication. This keeps your local segment efficient and contributes to the health of the wider network.</p>
|
||||
<p>Whether you manually block a spamming identity or subscribe to a blackhole list maintained by a trusted Network Identity, these tools help ensure that <em>your</em> transport capacity is used for what <em>you</em> consider legitimate communication. This keeps your local segment efficient and contributes to the health of the wider network.</p>
|
||||
</section>
|
||||
<section id="contributing-to-the-global-ret">
|
||||
<h3>Contributing to the Global Ret<a class="headerlink" href="#contributing-to-the-global-ret" title="Link to this heading">¶</a></h3>
|
||||
|
||||
@@ -1078,7 +1078,7 @@ relevant regulation for your location, and to make decisions accordingly.</p>
|
||||
</section>
|
||||
<section id="discoverable-interfaces">
|
||||
<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 discover, validate, and automatically connect to them. 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>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>
|
||||
@@ -1133,8 +1133,8 @@ When using an executable script for <code class="docutils literal notranslate"><
|
||||
<dt><code class="docutils literal notranslate"><span class="pre">discovery_encrypt</span></code></dt><dd><p>If set to <code class="docutils literal notranslate"><span class="pre">yes</span></code>, the discovery announce payload will be encrypted. To decrypt the announce, remote peers must possess the <em>network identity</em> configured for your instance (see <code class="docutils literal notranslate"><span class="pre">network_identity</span></code> in the <code class="docutils literal notranslate"><span class="pre">[reticulum]</span></code> section). This allows you to publish private interfaces that are only discoverable to specific trusted networks.</p>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<div class="admonition important">
|
||||
<p class="admonition-title">Important</p>
|
||||
<p>If you enable <code class="docutils literal notranslate"><span class="pre">discovery_encrypt</span></code> but do not configure a valid <code class="docutils literal notranslate"><span class="pre">network_identity</span></code> in the <code class="docutils literal notranslate"><span class="pre">[reticulum]</span></code> section of your configuration, Reticulum will abort the interface discovery announce. Encryption requires a valid network identity key to function.</p>
|
||||
</div>
|
||||
<dl class="simple">
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -277,9 +277,9 @@ A common mistake in modern networking is the reliance on a few centralized, hard
|
||||
|
||||
Reticulum encourages the approach of *organic growth*. Instead of relying on permanent static connections to distant servers, you can use temporary bootstrap connections to *discover* better, more relevant or local infrastructure. Once discovered, your system can automatically form stronger, more direct links to these peers, and discard the temporary bootstrap links. This results in a web of connections that are geographically relevant, resilient and efficient.
|
||||
|
||||
It is possible to simply add a few public entrypoints to the ``[interfaces]`` section of your Reticulum configuration and be connected, but a better option is to enable :ref:`interface discovery<using-interface_discovery>` and either manually select relevant, local interfaces, or enable discovered interface auto-connection.
|
||||
It *is* possible to simply add a few public entrypoints to the ``[interfaces]`` section of your Reticulum configuration and be connected, but a better option is to enable :ref:`interface discovery<using-interface_discovery>` and either manually select relevant, local interfaces, or enable discovered interface auto-connection.
|
||||
|
||||
A relevant option in this context is the :ref:`bootstrap only<interfaces-options>` interface option. This is an automated tool for better distributing connectivity. By marking an interface as ``bootstrap_only``, you tell Reticulum: *"Use this connection to find connectivity options, and prefer discovered interfaces once they are available"*. This helps create a network topology that favors locality and resilience over the simple centralization caused by using only a few static entrypoints.
|
||||
A relevant option in this context is the :ref:`bootstrap only<interfaces-options>` interface option. This is an automated tool for better distributing connectivity. By enabling interface discovery and auto-connection, and marking an interface as ``bootstrap_only``, you tell Reticulum to use that interface primarliy to find connectivity options, and then disconnect it once sufficient entrypoints have been discovered. This helps create a network topology that favors locality and resilience over the simple centralization caused by using only a few static entrypoints.
|
||||
|
||||
A good place to find interface definitions for bootstrapping connectivity is `rmap.world <https://rmap.world/>`_.
|
||||
|
||||
@@ -296,7 +296,7 @@ We strongly encourage everyone, even home users, to think in terms of building *
|
||||
* While you sleep, work, or cook, your node listens to the network. It discovers other local community members, validates their Network Identities, and automatically establishes direct links.
|
||||
* Your personal devices now connect to your *local* node, which is integrated into a living, breathing local mesh. Your traffic flows through local paths provided by other real people in the community rather than bouncing off a distant server.
|
||||
|
||||
**Don't wait for others to build the networks you want to see**. Every network is important, perhaps even most so those that support individual families and persons. Once enough of this personal, local infrastructure exist, connecting them directly to each other, without traversing the public Internet, becomes not just possible, but inevitable.
|
||||
**Don't wait for others to build the networks you want to see**. Every network is important, perhaps even most so those that support individual families and persons. Once enough of this personal, local infrastructure exist, connecting them directly to each other, without traversing the public Internet, becomes inevitable.
|
||||
|
||||
|
||||
Mixing Strategies
|
||||
@@ -305,7 +305,7 @@ Mixing Strategies
|
||||
There is no requirement to commit to a single strategy. The most robust setups often mix static, dynamic, and discovered interfaces.
|
||||
|
||||
* **Static Interfaces:** You maintain a permanent interface to a trusted friend or organization using a static configuration.
|
||||
* **Bootstrap Links:** You run a ``bootstrap_only`` TCP interface to a public gateway to scan for new connectable peers or to regain connectivity if your other interfaces fail.
|
||||
* **Bootstrap Links:** You connect a ``bootstrap_only`` interface to a public gateway on the Internet to scan for new connectable peers or to regain connectivity if your other interfaces fail.
|
||||
* **Local Wide-Area Connectivity:** You run a ``RNodeInterface`` on a shared frequency, giving you completely self-sovereign and private wide-area access to both your own network and other Reticulum peers globally, without any "service providers" being able to control or monitor how you interact with people.
|
||||
|
||||
By combining these methods, you create a system that is secure against single points of failure, adaptable to changing network conditions, and better integrated into your physical and social reality.
|
||||
@@ -316,7 +316,7 @@ Network Health & Responsibility
|
||||
|
||||
As you participate in the wider networks you discover and build, you will inevitably encounter peers that are misconfigured, malicious, or simply broken. To protect your resources and those of your local peers, you can utilize the :ref:`Blackhole Management<using-blackhole_management>` system.
|
||||
|
||||
Whether you manually block a spamming identity or subscribe to a blackhole list maintained by a trusted Network Identity, these tools help ensure that your transport capacity is used for legitimate communication. This keeps your local segment efficient and contributes to the health of the wider network.
|
||||
Whether you manually block a spamming identity or subscribe to a blackhole list maintained by a trusted Network Identity, these tools help ensure that *your* transport capacity is used for what *you* consider legitimate communication. This keeps your local segment efficient and contributes to the health of the wider network.
|
||||
|
||||
|
||||
Contributing to the Global Ret
|
||||
|
||||
@@ -916,7 +916,7 @@ beaconing functionality described above.
|
||||
Discoverable Interfaces
|
||||
=======================
|
||||
|
||||
Reticulum includes a powerful system for publishing your local interfaces to the wider network, allowing other peers to discover, validate, and automatically connect to them. 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.
|
||||
Reticulum includes a powerful system for publishing your local interfaces to the wider network, allowing other peers to :ref:`discover, validate, and automatically connect to them<using-interface_discovery>`. 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.
|
||||
|
||||
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.
|
||||
|
||||
@@ -979,7 +979,7 @@ When ``discoverable`` is enabled, a variety of additional options become availab
|
||||
``discovery_encrypt``
|
||||
If set to ``yes``, the discovery announce payload will be encrypted. To decrypt the announce, remote peers must possess the *network identity* configured for your instance (see ``network_identity`` in the ``[reticulum]`` section). This allows you to publish private interfaces that are only discoverable to specific trusted networks.
|
||||
|
||||
.. warning::
|
||||
.. important::
|
||||
If you enable ``discovery_encrypt`` but do not configure a valid ``network_identity`` in the ``[reticulum]`` section of your configuration, Reticulum will abort the interface discovery announce. Encryption requires a valid network identity key to function.
|
||||
|
||||
``publish_ifac``
|
||||
|
||||
Reference in New Issue
Block a user