mirror of
https://github.com/markqvist/Reticulum.git
synced 2026-05-24 16:54:47 -07:00
Updated docs
This commit is contained in:
Mark Qvist
@@ -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.0.5 documentation</title>
|
||||
<title>Getting Started Fast - Reticulum Network Stack 1.1.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.0.5 documentation</div></a>
|
||||
<a href="index.html"><div class="brand">Reticulum Network Stack 1.1.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.0.5 documentation</span>
|
||||
<span class="sidebar-brand-text">Reticulum Network Stack 1.1.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">
|
||||
@@ -451,34 +451,79 @@ deep-packet-inspection much more difficult.</p>
|
||||
instance, while preserving anonymity. If you care more about performance, and a slightly
|
||||
easier setup, use TCP.</p>
|
||||
</section>
|
||||
<section id="bootstrapping-connectivity">
|
||||
<span id="id4"></span><h2>Bootstrapping Connectivity<a class="headerlink" href="#bootstrapping-connectivity" title="Link to this heading">¶</a></h2>
|
||||
<p>Reticulum is not a service you subscribe to, nor is it a single global network you “join”. It is a <em>networking stack</em>; a toolkit for building communications systems that align with your specific values, requirements, and operational environment. The way you choose to connect to other Reticulum peers is entirely your own choice.</p>
|
||||
<p>One of the most powerful aspects of Reticulum is that it provides a multitude of tools to establish, maintain, and optimize connectivity. You can use these tools in isolation or combine them in complex configurations to achieve a vast array of goals.</p>
|
||||
<p>Whether your aim is to create a completely private, air-gapped network for your family; to build a resilient community mesh that survives infrastructure collapse; to connect far and wide to as many nodes as possible; or simply to maintain a reliable, encrypted link to a specific organization you care about, Reticulum provides the mechanisms to make it happen.</p>
|
||||
<p>There is no “right” or “wrong” way to build a Reticulum network, and you don’t need to be a network engineer just to get started. If the information flows in the way you intend, and your privacy and security requirements are met, your configuration is a success. Reticulum is designed to make the most challenging and difficult scenarios attainable, even when other networking technologies fail.</p>
|
||||
<section id="finding-your-way">
|
||||
<h3>Finding Your Way<a class="headerlink" href="#finding-your-way" title="Link to this heading">¶</a></h3>
|
||||
<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>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">
|
||||
<h3>Building Personal Infrastructure<a class="headerlink" href="#building-personal-infrastructure" title="Link to this heading">¶</a></h3>
|
||||
<p>You do not need a datacenter to be a meaningful part of the Reticulum ecosystem. In fact, the most important nodes in the network are often the smallest ones.</p>
|
||||
<p>We strongly encourage everyone, even home users, to think in terms of building <strong>personal infrastructure</strong>. Don’t connect every phone, tablet, and computer in your house directly to a public internet gateway. Instead, repurpose an old computer, a Raspberry Pi, or a supported router to act as your own, personal <strong>Transport Node</strong>:</p>
|
||||
<ul class="simple">
|
||||
<li><p>Your local Transport Node sits in your home, connected to your WiFi and perhaps a radio interface (like an RNode).</p></li>
|
||||
<li><p>You configure this node with a <code class="docutils literal notranslate"><span class="pre">bootstrap_only</span></code> interface (perhaps a TCP tunnel to a wider network) and enable interface discovery.</p></li>
|
||||
<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>
|
||||
</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>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>
|
||||
</section>
|
||||
<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>
|
||||
</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>
|
||||
<p>If you have the means to host a stable node with a public IP address, consider becoming a <a class="reference internal" href="#hosting-entrypoints"><span class="std std-ref">Public Entrypoint</span></a>. By <a class="reference internal" href="interfaces.html#interfaces-discoverable"><span class="std std-ref">publishing your interface as discoverable</span></a>, you provide a potential connection point for others, helping the network grow and reach new areas.</p>
|
||||
<p>For guidelines on how to properly configure and secure a public gateway, refer to the <a class="reference internal" href="#hosting-entrypoints"><span class="std std-ref">Hosting Public Entrypoints</span></a> section.</p>
|
||||
</section>
|
||||
</section>
|
||||
<section id="connect-to-the-public-testnet">
|
||||
<h2>Connect to the Public Testnet<a class="headerlink" href="#connect-to-the-public-testnet" title="Link to this heading">¶</a></h2>
|
||||
<p>An experimental public testnet has been made accessible by volunteers in the community. You
|
||||
can find interface definitions for adding to your <code class="docutils literal notranslate"><span class="pre">.reticulum/config</span></code> file on the
|
||||
<a class="reference external" href="https://reticulum.network/connect.html">Reticulum Website</a> or the
|
||||
<a class="reference external" href="https://github.com/markqvist/Reticulum/wiki/Community-Node-List">Community Wiki</a></p>
|
||||
<a class="reference external" href="https://reticulum.network/connect.html">Reticulum Website</a>, or the
|
||||
<a class="reference external" href="https://github.com/markqvist/Reticulum/wiki/Community-Node-List">Community Wiki</a>.</p>
|
||||
<p>As development of Reticulum has transitioned away from the public Internet, and is now happening exclusively over Reticulum itself, the lists on the <a class="reference external" href="https://reticulum.network/connect.html">Reticulum Website</a> and the
|
||||
<a class="reference external" href="https://github.com/markqvist/Reticulum/wiki/Community-Node-List">Community Wiki</a> are no longer actively maintained, and any up-to-date connectivity information will have to be found elsewhere.</p>
|
||||
<p>For a while, these resources will likely still be a usable way to find bootstrap connections, that will allow you to discover other entrypoints to connect to, but it is highly recommended to also check community run projects like <a class="reference external" href="https://rmap.world/">rmap.world</a>.</p>
|
||||
<p>You can connect your devices or instances to one or more of these to gain access to any
|
||||
Reticulum networks they are physically connected to. Simply add one or more interface
|
||||
snippets to your config file in the <code class="docutils literal notranslate"><span class="pre">[interface]</span></code> section, like in the example below:</p>
|
||||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="c1"># TCP/IP interface to the BetweenTheBorders Hub (community-provided)</span>
|
||||
<span class="k">[[RNS Testnet BetweenTheBorders]]</span>
|
||||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="c1"># TCP/IP interface to the RNS Amsterdam Hub</span>
|
||||
<span class="k">[[RNS Testnet Amsterdam]]</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">TCPClientInterface</span>
|
||||
<span class="w"> </span><span class="na">enabled</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">target_host</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">reticulum.betweentheborders.com</span>
|
||||
<span class="w"> </span><span class="na">target_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">target_host</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">amsterdam.connect.reticulum.network</span>
|
||||
<span class="w"> </span><span class="na">target_port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4965</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="admonition tip">
|
||||
<p class="admonition-title">Tip</p>
|
||||
<p>Ideally, set up a Reticulum Transport Node that your own devices can reach locally, and then
|
||||
connect that transport node to a couple of public entrypoints. This will provide efficient
|
||||
connections and redundancy in case any of them go down.</p>
|
||||
<p>Don’t rely on a single connection to a testnet entrypoint for everyday use. The testnet is often used for development and failure testing scenarios. Instead, read the <a class="reference internal" href="#bootstrapping-connectivity"><span class="std std-ref">Bootstrapping Connectivity</span></a> section.</p>
|
||||
</div>
|
||||
<p>Many other Reticulum instances are connecting to this testnet, and you can also join it
|
||||
via other entry points if you know them. There is absolutely no control over the network
|
||||
topography, usage or what types of instances connect. It will also occasionally be used
|
||||
to test various failure scenarios, and there are no availability or service guarantees.
|
||||
Expect weird things to happen on this network, as people experiment and try out things.</p>
|
||||
<p>As the amount of global Reticulum nodes and entrypoints have grown to a substantial quantity, the public Amsterdam Testnet entrypoint is slated for de-commisioning in the first quarter of 2026. If your own instances rely on this entrypoint for connectivity, it is high time to start configuring alternatives. Read the <a class="reference internal" href="#bootstrapping-connectivity"><span class="std std-ref">Bootstrapping Connectivity</span></a> section for pointers.</p>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<p>It probably goes without saying, but <em>don’t use the testnet entry-points as
|
||||
@@ -489,9 +534,10 @@ leave it up to the user which networks to connect to, and how.</p>
|
||||
</div>
|
||||
</section>
|
||||
<section id="hosting-public-entrypoints">
|
||||
<h2>Hosting Public Entrypoints<a class="headerlink" href="#hosting-public-entrypoints" title="Link to this heading">¶</a></h2>
|
||||
<span id="hosting-entrypoints"></span><h2>Hosting Public Entrypoints<a class="headerlink" href="#hosting-public-entrypoints" title="Link to this heading">¶</a></h2>
|
||||
<p>If you want to host a public (or private) entry-point to a Reticulum network over the
|
||||
Internet, this section offers some helpful pointers. You will need a machine, physical or
|
||||
Internet, this section offers some helpful pointers. Once you have set up your public entrypoint, it is a great idea to <a class="reference internal" href="interfaces.html#interfaces-discoverable"><span class="std std-ref">make it discoverable over Reticulum</span></a>.</p>
|
||||
<p>You will need a machine, physical or
|
||||
virtual with a public IP address, that can be reached by other devices on the Internet.</p>
|
||||
<p>The most efficient and performant way to host a connectable entry-point supporting many
|
||||
users is to use the <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code>. This interface type is fully compatible with
|
||||
@@ -579,50 +625,8 @@ started is to install the latest release of Reticulum via pip:</p>
|
||||
ready to import and use RNS in your own programs. The next step will most
|
||||
likely be to look at some <a class="reference internal" href="examples.html#examples-main"><span class="std std-ref">Example Programs</span></a>.</p>
|
||||
<p>The entire Reticulum API is documented in the <a class="reference internal" href="reference.html#api-main"><span class="std std-ref">API Reference</span></a>
|
||||
chapter of this manual.</p>
|
||||
</section>
|
||||
<section id="participate-in-reticulum-development">
|
||||
<h2>Participate in Reticulum Development<a class="headerlink" href="#participate-in-reticulum-development" title="Link to this heading">¶</a></h2>
|
||||
<p>If you want to participate in the development of Reticulum and associated
|
||||
utilities, you’ll want to get the latest source from GitHub. In that case,
|
||||
don’t use pip, but try this recipe:</p>
|
||||
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install dependencies</span>
|
||||
pip<span class="w"> </span>install<span class="w"> </span>cryptography<span class="w"> </span>pyserial
|
||||
|
||||
<span class="c1"># Clone repository</span>
|
||||
git<span class="w"> </span>clone<span class="w"> </span>https://github.com/markqvist/Reticulum.git
|
||||
|
||||
<span class="c1"># Move into Reticulum folder and symlink library to examples folder</span>
|
||||
<span class="nb">cd</span><span class="w"> </span>Reticulum
|
||||
ln<span class="w"> </span>-s<span class="w"> </span>../RNS<span class="w"> </span>./Examples/
|
||||
|
||||
<span class="c1"># Run an example</span>
|
||||
python<span class="w"> </span>Examples/Echo.py<span class="w"> </span>-s
|
||||
|
||||
<span class="c1"># Unless you've manually created a config file, Reticulum will do so now,</span>
|
||||
<span class="c1"># and immediately exit. Make any necessary changes to the file:</span>
|
||||
nano<span class="w"> </span>~/.reticulum/config
|
||||
|
||||
<span class="c1"># ... and launch the example again.</span>
|
||||
python<span class="w"> </span>Examples/Echo.py<span class="w"> </span>-s
|
||||
|
||||
<span class="c1"># You can now repeat the process on another computer,</span>
|
||||
<span class="c1"># and run the same example with -h to get command line options.</span>
|
||||
python<span class="w"> </span>Examples/Echo.py<span class="w"> </span>-h
|
||||
|
||||
<span class="c1"># Run the example in client mode to "ping" the server.</span>
|
||||
<span class="c1"># Replace the hash below with the actual destination hash of your server.</span>
|
||||
python<span class="w"> </span>Examples/Echo.py<span class="w"> </span>174a64852a75682259ad8b921b8bf416
|
||||
|
||||
<span class="c1"># Have a look at another example</span>
|
||||
python<span class="w"> </span>Examples/Filetransfer.py<span class="w"> </span>-h
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>When you have experimented with the basic examples, it’s time to go read the
|
||||
<a class="reference internal" href="understanding.html#understanding-main"><span class="std std-ref">Understanding Reticulum</span></a> chapter. Before submitting
|
||||
your first pull request, it is probably a good idea to introduce yourself on
|
||||
the <a class="reference external" href="https://github.com/markqvist/Reticulum/discussions">disucssion forum on GitHub</a>,
|
||||
or ask one of the developers or maintainers for a good place to start.</p>
|
||||
chapter of this manual. Before diving in, it’s probably a good idea to read
|
||||
this manual in full, but at least start with the <a class="reference internal" href="understanding.html#understanding-main"><span class="std std-ref">Understanding Reticulum</span></a> chapter.</p>
|
||||
</section>
|
||||
<section id="platform-specific-install-notes">
|
||||
<span id="install-guides"></span><h2>Platform-Specific Install Notes<a class="headerlink" href="#platform-specific-install-notes" title="Link to this heading">¶</a></h2>
|
||||
@@ -1010,12 +1014,19 @@ All other available modules will still be loaded when needed.</p>
|
||||
<li><a class="reference internal" href="#using-the-included-utilities">Using the Included Utilities</a></li>
|
||||
<li><a class="reference internal" href="#creating-a-network-with-reticulum">Creating a Network With Reticulum</a></li>
|
||||
<li><a class="reference internal" href="#connecting-reticulum-instances-over-the-internet">Connecting Reticulum Instances Over the Internet</a></li>
|
||||
<li><a class="reference internal" href="#bootstrapping-connectivity">Bootstrapping Connectivity</a><ul>
|
||||
<li><a class="reference internal" href="#finding-your-way">Finding Your Way</a></li>
|
||||
<li><a class="reference internal" href="#building-personal-infrastructure">Building Personal Infrastructure</a></li>
|
||||
<li><a class="reference internal" href="#mixing-strategies">Mixing Strategies</a></li>
|
||||
<li><a class="reference internal" href="#network-health-responsibility">Network Health & Responsibility</a></li>
|
||||
<li><a class="reference internal" href="#contributing-to-the-global-ret">Contributing to the Global Ret</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#connect-to-the-public-testnet">Connect to the Public Testnet</a></li>
|
||||
<li><a class="reference internal" href="#hosting-public-entrypoints">Hosting Public Entrypoints</a></li>
|
||||
<li><a class="reference internal" href="#adding-radio-interfaces">Adding Radio Interfaces</a></li>
|
||||
<li><a class="reference internal" href="#creating-and-using-custom-interfaces">Creating and Using Custom Interfaces</a></li>
|
||||
<li><a class="reference internal" href="#develop-a-program-with-reticulum">Develop a Program with Reticulum</a></li>
|
||||
<li><a class="reference internal" href="#participate-in-reticulum-development">Participate in Reticulum Development</a></li>
|
||||
<li><a class="reference internal" href="#platform-specific-install-notes">Platform-Specific Install Notes</a><ul>
|
||||
<li><a class="reference internal" href="#android">Android</a></li>
|
||||
<li><a class="reference internal" href="#arm64">ARM64</a></li>
|
||||
@@ -1040,7 +1051,7 @@ All other available modules will still be loaded when needed.</p>
|
||||
|
||||
</aside>
|
||||
</div>
|
||||
</div><script src="_static/documentation_options.js?v=d55fa986"></script>
|
||||
</div><script src="_static/documentation_options.js?v=fc837d61"></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>
|
||||
|
||||
Reference in New Issue
Block a user