<linkrel="index"title="Index"href="genindex.html"><linkrel="search"title="Search"href="search.html"><linkrel="next"title="Understanding Reticulum"href="understanding.html"><linkrel="prev"title="Programs Using Reticulum"href="software.html">
<spanid="using-main"></span><h1>Using Reticulum on Your System<aclass="headerlink"href="#using-reticulum-on-your-system"title="Link to this heading">¶</a></h1>
<p>If no existing configuration directory is found, the directory <codeclass="docutils literal notranslate"><spanclass="pre">~/.reticulum</span></code>
is created, and the default configuration will be automatically created here.
You can move it to one of the other locations if you wish.</p>
<p>It is also possible to use completely arbitrary configuration directories by
specifying the relevant command-line parameters when running Reticulum-based
programs. You can also run multiple separate Reticulum instances on the same
physical system, either in isolation from each other, or connected together.</p>
<p>In most cases, a single physical system will only need to run one Reticulum
instance. This can either be launched at boot, as a system service, or simply
be brought up when a program needs it. In either case, any number of programs
running on the same system will automatically share the same Reticulum instance,
if the configuration allows for it, which it does by default.</p>
<p>The entire configuration of Reticulum is found in the <codeclass="docutils literal notranslate"><spanclass="pre">~/.reticulum/config</span></code>
file. When Reticulum is first started on a new system, a basic, but fully functional
configuration file is created. The default configuration looks like this:</p>
<p>The output includes examples for most interface types supported
by Reticulum, along with additional options and configuration parameters.</p>
<p>It is a good idea to read the comments and explanations in the above default config.
It will teach you the basic concepts you need to understand to configure your network.
Once you have done that, take a look at the <aclass="reference internal"href="interfaces.html#interfaces-main"><spanclass="std std-ref">Interfaces</span></a> chapter
<p>It is very easy to run Reticulum as a service. Simply run the included <codeclass="docutils literal notranslate"><spanclass="pre">rnsd</span></code> command.
When <codeclass="docutils literal notranslate"><spanclass="pre">rnsd</span></code> is running, it will keep all configured interfaces open, handle transport if
it is enabled, and allow any other programs to immediately utilise the
Reticulum network it is configured for.</p>
<p>You can even run multiple instances of <codeclass="docutils literal notranslate"><spanclass="pre">rnsd</span></code> with different configurations on
[2023-08-18 17:59:56] [Notice] Started rnsd version 0.5.8
</pre></div>
</div>
<p>Run <codeclass="docutils literal notranslate"><spanclass="pre">rnsd</span></code> in service mode, ensuring all logging output is sent directly to file:</p>
<p>You can easily add <codeclass="docutils literal notranslate"><spanclass="pre">rnsd</span></code> as an always-on service by <aclass="reference internal"href="#using-systemd"><spanclass="std std-ref">configuring a service</span></a>.</p>
<p>Using the <codeclass="docutils literal notranslate"><spanclass="pre">rnstatus</span></code> utility, you can view the status of configured Reticulum
interfaces, similar to the <codeclass="docutils literal notranslate"><spanclass="pre">ifconfig</span></code> program.</p>
<p>When using <codeclass="docutils literal notranslate"><spanclass="pre">-R</span></code> to query a remote transport instance, you must also specify <codeclass="docutils literal notranslate"><spanclass="pre">-i</span></code> with the path to a management identity file that is authorized for remote management on the target system.</p>
<p>With the <codeclass="docutils literal notranslate"><spanclass="pre">rnid</span></code> utility, you can generate, manage and view Reticulum Identities.
The program can also calculate Destination hashes, and perform encryption and
decryption of files.</p>
<p>Using <codeclass="docutils literal notranslate"><spanclass="pre">rnid</span></code>, it is possible to asymmetrically encrypt files and information for
any Reticulum destination hash, and also to create and verify cryptographic signatures.</p>
Recalled Identity <bc7291552be7a58f361522990465165c> for destination <8dd57a738226809646089335a6b03695>
Encrypting my_file.txt
File my_file.txt encrypted for <bc7291552be7a58f361522990465165c> to my_file.txt.rfe
</pre></div>
</div>
<p>If the Identity for the destination is not already known, you can fetch it from the network by using the <codeclass="docutils literal notranslate"><spanclass="pre">-R</span></code> command-line option:</p>
Path found, destination <c89b4da064bf66d280f0e4d8abfd9806> is 4 hops away via <f53a1c4278e0726bb73fcc623d6ce763> on TCPInterface[Testnet/dublin.connect.reticulum.network:4965]
Sent 16 byte probe to <2d03725b327348980d570f739a3a5708>
Valid reply received from <2d03725b327348980d570f739a3a5708>
Round-trip time is 38.781 milliseconds over 2 hops
</pre></div>
</div>
<p>If the interface that receives the probe replies supports reporting radio
parameters such as <strong>RSSI</strong> and <strong>SNR</strong>, the <codeclass="docutils literal notranslate"><spanclass="pre">rnprobe</span></code> utility will print
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">rncp</span></code> utility is a simple file transfer tool. Using it, you can transfer
files through Reticulum.</p>
<p><strong>Usage Examples</strong></p>
<p>Run rncp on the receiving system, specifying which identities are allowed to send files:</p>
<divclass="highlight-text notranslate"><divclass="highlight"><pre><span></span>$ rncp --listen -a 1726dbad538775b5bf9b0ea25a4079c8 -a c50cc4e4f7838b6c31f60ab9032cbc62
</pre></div>
</div>
<p>You can also specify allowed identity hashes (one per line) in the file ~/.rncp/allowed_identities
and simply running the program in listener mode:</p>
<p>The default identity file is stored in <codeclass="docutils literal notranslate"><spanclass="pre">~/.reticulum/identities/rncp</span></code>, but you can use
another one, which will be created if it does not already exist</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">rnx</span></code> utility is a basic remote command execution program. It allows you to
execute commands on remote systems over Reticulum, and to view returned command
output. For a fully interactive remote shell solution, be sure to also take a look
at the <aclass="reference external"href="https://github.com/acehoss/rnsh">rnsh</a> program.</p>
<p><strong>Usage Examples</strong></p>
<p>Run rnx on the listening system, specifying which identities are allowed to execute commands:</p>
<divclass="highlight-text notranslate"><divclass="highlight"><pre><span></span>$ rnx --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
</pre></div>
</div>
<p>From another system, run a command on the remote:</p>
<p>The default identity file is stored in <codeclass="docutils literal notranslate"><spanclass="pre">~/.reticulum/identities/rnx</span></code>, but you can use
another one, which will be created if it does not already exist</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">rnodeconf</span></code> utility allows you to inspect and configure existing <aclass="reference internal"href="hardware.html#rnode-main"><spanclass="std std-ref">RNodes</span></a>, and
to create and provision new <aclass="reference internal"href="hardware.html#rnode-main"><spanclass="std std-ref">RNodes</span></a> from any supported hardware devices.</p>
--platform platform Platform specification for device bootstrap
--product product Product specification for device bootstrap
--model model Model code for device bootstrap
--hwrev revision Hardware revision for device bootstrap
</pre></div>
</div>
<p>For more information on how to create your own RNodes, please read the <aclass="reference internal"href="hardware.html#rnode-creating"><spanclass="std std-ref">Creating RNodes</span></a>
<spanid="using-interface-discovery"></span><h2>Discovering Interfaces<aclass="headerlink"href="#discovering-interfaces"title="Link to this heading">¶</a></h2>
<p>Reticulum includes built-in functionality for discovering connectable interfaces over Reticulum itself. This is particularly useful in situations where you want to do one or more of the following:</p>
<ulclass="simple">
<li><p>Discover connectable entrypoints available on the Internet</p></li>
<li><p>Find connectable radio access points in the physical world</p></li>
<li><p>Maintain connectivity to RNS instances with unknown or changing IP addresses</p></li>
</ul>
<p>Discovered interfaces can be <strong>auto-connected</strong> by Reticulum, which makes it possible to create setups where an arbitrary interface can act simply as a bootstrap connection, that can be torn down again once more suitable interfaces have been discovered and connected.</p>
<p>The interface discovery mechanism uses announces sent over Reticulum itself, and supports both publicly readable interfaces and private, encrypted discovery, that can only be decoded by specified <em>network identities</em>. It is also possible to specify which network identities should be considered valid sources for discovered interfaces, so that interfaces published by unknown entities are ignored.</p>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>A <em>network identity</em> is a normal Reticulum identity keyset that can be used by
one or more transport nodes to identify them as belonging to the same overall
network. In the context of interface discovery, this makes it easy to manage
connecting to only the particular networks you care about, even if those networks
utilize many individual physical transport node.</p>
<p>This also makes it convenient to auto-connect discovered interfaces only for networks you have some level of trust in.</p>
</div>
<p>For information on how to make your interfaces discoverable, see the <aclass="reference internal"href="interfaces.html#interfaces-discoverable"><spanclass="std std-ref">Discoverable Interfaces</span></a> chapter of this manual. The current section will focus on how to actually <em>discover and connect to</em> interfaces available on the network.</p>
<p>In its most basic form, enabling interface discovery is as simple as setting <codeclass="docutils literal notranslate"><spanclass="pre">discover_interfaces</span></code> to <codeclass="docutils literal notranslate"><spanclass="pre">true</span></code> in your Reticulum config:</p>
<p>Once this option is enabled, your RNS instance will start listening for interface discovery announces, and store them for later use or inspection. You can list discovered interfaces with the <codeclass="docutils literal notranslate"><spanclass="pre">rnstatus</span></code> utility:</p>
Sideband Hub Backbone ✓ Available 1h ago 16 46.2316, 6.0536
RNS Amsterdam Backbone ✓ Available 32m ago 16 52.3865, 4.9037
</pre></div>
</div>
<p>You can view more detailed information about discovered interfaces, including configuration snippets for pasting directly into your <codeclass="docutils literal notranslate"><spanclass="pre">[interfaces]</span></code> config, by using the <codeclass="docutils literal notranslate"><spanclass="pre">rnstatus</span><spanclass="pre">-D</span></code> option:</p>
<p>In addition to providing local interface discovery information and control, the <codeclass="docutils literal notranslate"><spanclass="pre">rnstatus</span></code> utility can export discovered interface data in machine-readable JSON format using the <codeclass="docutils literal notranslate"><spanclass="pre">rnstatus</span><spanclass="pre">-d</span><spanclass="pre">--json</span></code> option. This can be useful for exporting the data to external applications such as status pages, access point maps and similar.</p>
<p>To control what sources are considered valid for discovered sources, additional
configuration options can be specified for the interface discovery system.</p>
<ulclass="simple">
<li><p>The <codeclass="docutils literal notranslate"><spanclass="pre">interface_discovery_sources</span></code> option is a list of the network or transport identities from which interfaces will be accepted. If this option is set, all others will be ignored. If this option is not set, discovered interfaces will be accepted from any source, but are still subject to stamp value requirements.</p></li>
<li><p>The <codeclass="docutils literal notranslate"><spanclass="pre">required_discovery_value</span></code> options specifies the minimum stamp value required for the interface announce to be considered valid. To make it computationally difficult to spam the network with a large number of defunct or malicious interfaces, each announced interface requires a valid cryptographical stamp, of configurable difficulty value.</p></li>
<li><p>The <codeclass="docutils literal notranslate"><spanclass="pre">autoconnect_discovered_interfaces</span></code> value defaults to <codeclass="docutils literal notranslate"><spanclass="pre">0</span></code>, and specifies the maximum number of discovered interfaces that should be auto-connected at any given time. If set to a number greater than <codeclass="docutils literal notranslate"><spanclass="pre">0</span></code>, Reticulum automatically manages discovered interface connections, and will bring discovered interfaces up and down based on availability. You can at any time add discovered interfaces to your configuration manually, to persistently keep them available.</p></li>
<li><p>The <codeclass="docutils literal notranslate"><spanclass="pre">network_identity</span></code> option specifies the <em>network identity</em> for this RNS instance. This identity is used both to sign (and potentially encrypt) <em>outgoing</em> interface discovery announces, and to decrypt incoming discovery information.</p></li>
</ul>
<p>The configuration snippet below contains an example of setting these additional configuration options:</p>
<p>It is possible to allow remote management of Reticulum
systems using the various built-in utilities, such as
<codeclass="docutils literal notranslate"><spanclass="pre">rnstatus</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">rnpath</span></code>. To do so, you will need to set
the <codeclass="docutils literal notranslate"><spanclass="pre">enable_remote_management</span></code> directive in the <codeclass="docutils literal notranslate"><spanclass="pre">[reticulum]</span></code>
section of the configuration file. You will also need to specify
one or more Reticulum Identity hashes for authenticating the
queries from client programs. For this purpose, you can use
existing identity files, or generate new ones with the rnid utility.</p>
<p>The following is a truncated example of enabling remote management
<p>For a complete example configuration, you can run <codeclass="docutils literal notranslate"><spanclass="pre">rnsd</span><spanclass="pre">--exampleconfig</span></code>.</p>
<spanid="using-blackhole-management"></span><h2>Blackhole Management<aclass="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>
<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>
<p>This functionality serves a dual purpose:</p>
<ulclass="simple">
<li><p><strong>For Individual Users:</strong> It offers a simple way to maintain a quiet and efficient local network by manually blocking spammy or unwanted peers.</p></li>
<li><p><strong>For Network Operators:</strong> It enables the creation of federated, community-wide security standards. By publishing and sharing blackhole lists, operators can protect large infrastructures and distribute spam filtering rules across the mesh without manual intervention.</p></li>
</ul>
<sectionid="local-blackhole-management">
<h3>Local Blackhole Management<aclass="headerlink"href="#local-blackhole-management"title="Link to this heading">¶</a></h3>
<p>The most immediate way to manage unwanted identities is through manual configuration using the <codeclass="docutils literal notranslate"><spanclass="pre">rnpath</span></code> utility. This allows you to instantly block or unblock specific identities on your local Transport Instance.</p>
<p><strong>Blackholing an Identity</strong></p>
<p>To block an identity, use the <codeclass="docutils literal notranslate"><spanclass="pre">-B</span></code> (or <codeclass="docutils literal notranslate"><spanclass="pre">--blackhole</span></code>) flag followed by the identity hash. You can optionally specify a duration and a reason, which are useful for logging and future reference.</p>
<p>To remove an identity from the blackhole, use the <codeclass="docutils literal notranslate"><spanclass="pre">-U</span></code> (or <codeclass="docutils literal notranslate"><spanclass="pre">--unblackhole</span></code>) flag:</p>
<p><strong>Viewing the Blackhole List</strong></p>
<p>To see all identities currently blackholed on your local instance, use the <codeclass="docutils literal notranslate"><spanclass="pre">-b</span></code> (or <codeclass="docutils literal notranslate"><spanclass="pre">--blackholed</span></code>) flag:</p>
<h3>Automated List Sourcing<aclass="headerlink"href="#automated-list-sourcing"title="Link to this heading">¶</a></h3>
<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>
<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>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>
<p>To enable automated sourcing, add the <codeclass="docutils literal notranslate"><spanclass="pre">blackhole_sources</span></code> option to the <codeclass="docutils literal notranslate"><spanclass="pre">[reticulum]</span></code> section of your configuration file. This option accepts a comma-separated list of Transport Identity hashes that you trust to provide valid blackhole lists.</p>
<li><p>When enabled, the <codeclass="docutils literal notranslate"><spanclass="pre">BlackholeUpdater</span></code> service runs in the background.</p></li>
<li><p>For every identity hash listed in <codeclass="docutils literal notranslate"><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">blackholed_identities</span></code> database.</p></li>
<li><p>The lists are persisted to disk, ensuring they survive restarts.</p></li>
</ol>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>You can verify the external lists you are subscribed to, and their contents, without importing them by using <codeclass="docutils literal notranslate"><spanclass="pre">rnpath</span><spanclass="pre">-p</span></code>. See the <aclass="reference internal"href="#utility-rnpath"><spanclass="std std-ref">rnpath utility documentation</span></a> for details on querying remote blackhole lists.</p>
</div>
</section>
<sectionid="publishing-blackhole-lists">
<h3>Publishing Blackhole Lists<aclass="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 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>To publish your local blackhole list, enable the <codeclass="docutils literal notranslate"><spanclass="pre">publish_blackhole</span></code> option in the <codeclass="docutils literal notranslate"><spanclass="pre">[reticulum]</span></code> section:</p>
<p>When this is enabled, your Transport Instance will register a request handler at <codeclass="docutils literal notranslate"><spanclass="pre">rnstransport.info.blackhole</span></code>. Any peer that connects to this destination and requests <codeclass="docutils literal notranslate"><spanclass="pre">/list</span></code> will receive the complete set of identities currently present in your local blackhole database.</p>
<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.</p>
<spanid="using-systemd"></span><h3>Reticulum as a System Service<aclass="headerlink"href="#reticulum-as-a-system-service"title="Link to this heading">¶</a></h3>
<p>If you installed Reticulum with <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code>, the <codeclass="docutils literal notranslate"><spanclass="pre">rnsd</span></code> program will most likely
be located in a user-local installation path only, which means <codeclass="docutils literal notranslate"><spanclass="pre">systemd</span></code> will not
be able to execute it. In this case, you can simply symlink the <codeclass="docutils literal notranslate"><spanclass="pre">rnsd</span></code> program
<p>You can then create the service file <codeclass="docutils literal notranslate"><spanclass="pre">/etc/systemd/system/rnsd.service</span></code> with the
<p>Be sure to replace <codeclass="docutils literal notranslate"><spanclass="pre">USERNAMEHERE</span></code> with the user you want to run <codeclass="docutils literal notranslate"><spanclass="pre">rnsd</span></code> as.</p>
<p>Alternatively you can use a user systemd service instead of a system wide one. This way the whole setup can be done as a regular user.
Create a user systemd service files <codeclass="docutils literal notranslate"><spanclass="pre">~/.config/systemd/user/rnsd.service</span></code> with the following content:</p>
<p>Replace <codeclass="docutils literal notranslate"><spanclass="pre">RNS_BIN_DIR</span></code> with the path to your Reticulum binary directory (eg. /home/USERNAMEHERE/rns/bin).</p>
<p>If you want to automatically start <codeclass="docutils literal notranslate"><spanclass="pre">rnsd</span></code> without having to log in as the USERNAMEHERE, do:</p>
