<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>Reticulum is not installed as a driver or kernel module, as one might expect
of a networking stack. Instead, Reticulum is distributed as a Python module,
containing the networking core, and a set of utility and daemon programs.</p>
<p>This means that no special privileges are required to install or use it. It
is also very light-weight, and easy to transfer to, and install on new systems.</p>
<p>When you have Reticulum installed, any program or application that uses Reticulum
will automatically load and initialise Reticulum when it starts, if it is not
already running.</p>
<p>In many cases, this approach is sufficient. When any program needs to use
Reticulum, it is loaded, initialised, interfaces are brought up, and the
program can now communicate over any Reticulum networks available. If another
program starts up and also wants access to the same Reticulum network, the already
running instance is simply shared. This works for any number of programs running
concurrently, and is very easy to use, but depending on your use case, there
are other options.</p>
<sectionid="configuration-data">
<h2>Configuration & Data<aclass="headerlink"href="#configuration-data"title="Link to this heading">¶</a></h2>
<p>Reticulum stores all information that it needs to function in a single file-system
directory. When Reticulum is started, it will look for a valid configuration
<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>
<divclass="highlight-ini notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># This is the default Reticulum config file.</span>
<spanclass="c1"># You should probably edit it to include any additional,</span>
<spanclass="c1"># interfaces and settings you might need.</span>
<spanclass="c1"># Only the most basic options are included in this default</span>
<spanclass="c1"># configuration. To see a more verbose, and much longer,</span>
<spanclass="c1"># configuration example, you can run the command:</span>
<spanclass="c1"># rnsd --exampleconfig</span>
<spanclass="k">[reticulum]</span>
<spanclass="c1"># If you enable Transport, your system will route traffic</span>
<spanclass="c1"># for other peers, pass announces and serve path requests.</span>
<spanclass="c1"># This should be done for systems that are suited to act</span>
<spanclass="c1"># as transport nodes, ie. if they are stationary and</span>
<spanclass="c1"># always-on. This directive is optional and can be removed</span>
<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
of this manual.</p>
</section>
<sectionid="included-utility-programs">
<h2>Included Utility Programs<aclass="headerlink"href="#included-utility-programs"title="Link to this heading">¶</a></h2>
<p>Reticulum includes a range of useful utilities, both for managing your Reticulum
networks, and for carrying out common tasks over Reticulum networks, such as
transferring files to remote systems, and executing commands and programs remotely.</p>
<p>If you often use Reticulum from several different programs, or simply want
Reticulum to stay available all the time, for example if you are hosting
a transport node, you might want to run Reticulum as a separate service that
other programs, applications and services can utilise.</p>
<sectionid="the-rnsd-utility">
<h3>The rnsd Utility<aclass="headerlink"href="#the-rnsd-utility"title="Link to this heading">¶</a></h3>
<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>
--config CONFIG path to alternative Reticulum config directory
-v, --verbose
-q, --quiet
-s, --service rnsd is running as a service and should log to file
-i, --interactive drop into interactive shell after initialisation
--exampleconfig print verbose configuration example to stdout and exit
--version show program's version number and exit
</pre></div>
</div>
<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>
</section>
<sectionid="the-rnstatus-utility">
<h3>The rnstatus Utility<aclass="headerlink"href="#the-rnstatus-utility"title="Link to this heading">¶</a></h3>
<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>
-R hash transport identity hash of remote instance to get status from
-i path path to identity used for remote management
-w seconds timeout before giving up on remote queries
-d, --discovered list discovered interfaces
-D show details and config entries for discovered interfaces
-m, --monitor continuously monitor status
-I, --monitor-interval seconds
refresh interval for monitor mode (default: 1)
-v, --verbose
</pre></div>
</div>
<divclass="admonition note">
<pclass="admonition-title">Note</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>
</div>
</section>
<sectionid="the-rnid-utility">
<h3>The rnid Utility<aclass="headerlink"href="#the-rnid-utility"title="Link to this heading">¶</a></h3>
<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
full_name full destination name in dotted notation
destination_hash hexadecimal hash of the destination
options:
-h, --help show this help message and exit
--config CONFIG path to alternative Reticulum config directory
-s SIZE, --size SIZE size of probe packet payload in bytes
-n PROBES, --probes PROBES
number of probes to send
-t seconds, --timeout seconds
timeout before giving up
-w seconds, --wait seconds
time between each probe
--version show program's version number and exit
-v, --verbose
</pre></div>
</div>
</section>
<sectionid="the-rncp-utility">
<h3>The rncp Utility<aclass="headerlink"href="#the-rncp-utility"title="Link to this heading">¶</a></h3>
<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>
<h3>The rngit Utility<aclass="headerlink"href="#the-rngit-utility"title="Link to this heading">¶</a></h3>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">rngit</span></code> utility provides full Git repository hosting and interaction over Reticulum. It allows you to host Git repositories on Reticulum nodes, and to interact with remote repositories using standard Git commands through the <codeclass="docutils literal notranslate"><spanclass="pre">rns://</span></code> URL scheme.</p>
<p>The system consists of two parts: The <codeclass="docutils literal notranslate"><spanclass="pre">rngit</span></code> node that hosts repositories, and the <codeclass="docutils literal notranslate"><spanclass="pre">git-remote-rns</span></code> helper that enables Git to communicate with rngit nodes. As soon as you have RNS installed on your system, you can transparently use Git with Reticulum-hosted repositories just like any other type of remote. Git over Reticulum uses URLs in the following format: <codeclass="docutils literal notranslate"><spanclass="pre">rns://DESTINATION_HASH/group/repo</span></code>.</p>
<p>If you set a branch to track a Reticulum remote as the default upstream, you can simply use <cite>git</cite> as you normally would; all commands work transparently and as expected.</p>
<divclass="admonition warning">
<pclass="admonition-title">Warning</p>
<p><strong>The rngit program is a new addition to RNS!</strong> This functionality was introduced in RNS 1.2.0. While great care has been taken to design a secure, but highly configurable and flexible permission system for allowing many users to interact with many different repositories on a single node, <codeclass="docutils literal notranslate"><spanclass="pre">rngit</span></code> has not been tested extensively in the wild! Be careful when hosting repositories, especially if they are public or semi-public.</p>
</div>
<p><strong>Usage Examples</strong></p>
<p>Run <codeclass="docutils literal notranslate"><spanclass="pre">rngit</span></code> to start a repository node:</p>
<p>On the first run, <codeclass="docutils literal notranslate"><spanclass="pre">rngit</span></code> will create a default configuration file. You will then need to edit this, to point to your repository locations, configure access permissions, and perform any other necessary configuration.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">rngit</span></code> node organizes repositories into groups. Each group is a directory containing bare Git repositories. The repository path format is <codeclass="docutils literal notranslate"><spanclass="pre">group_name/repo_name</span></code>. For example, a repository at <codeclass="docutils literal notranslate"><spanclass="pre">/var/git/public/myrepo</span></code> would be accessible as <codeclass="docutils literal notranslate"><spanclass="pre">public/myrepo</span></code> via the URL <codeclass="docutils literal notranslate"><spanclass="pre">rns://DESTINATION_HASH/public/myrepo</span></code>.</p>
<p><strong>Configuration</strong></p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">rngit</span></code> node configuration file is located at <codeclass="docutils literal notranslate"><spanclass="pre">~/.rngit/config</span></code> (or <codeclass="docutils literal notranslate"><spanclass="pre">/etc/rngit/config</span></code> for system-wide installations). The default configuration includes:</p>
<ulclass="simple">
<li><p>Repository group paths defining where to find bare repositories</p></li>
<li><p>Access permissions for groups and individual repositories</p></li>
<li><p>Announce intervals for network visibility</p></li>
</ul>
<p>Access permissions can be configured at the group level in the config file, or per-repository using <codeclass="docutils literal notranslate"><spanclass="pre">.allowed</span></code> files. Permissions use the format <codeclass="docutils literal notranslate"><spanclass="pre">permission:target</span></code> where permission is <codeclass="docutils literal notranslate"><spanclass="pre">r</span></code> (read), <codeclass="docutils literal notranslate"><spanclass="pre">w</span></code> (write), or <codeclass="docutils literal notranslate"><spanclass="pre">rw</span></code> (read/write), and target is <codeclass="docutils literal notranslate"><spanclass="pre">all</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">none</span></code>, or a specific identity hash.</p>
<p>Repository-specific <codeclass="docutils literal notranslate"><spanclass="pre">.allowed</span></code> files can be static text files or executable scripts that output permission rules to stdout. A <codeclass="docutils literal notranslate"><spanclass="pre">group.allowed</span></code> file in a repository group directory applies to all repositories within that group.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">git-remote-rns</span></code> helper is automatically invoked by Git when interacting with <codeclass="docutils literal notranslate"><spanclass="pre">rns://</span></code> URLs. It is not typically run directly by users, but accepts the following environment variables for configuration:</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">RNGIT_CONFIG</span></code> - Path to alternative client configuration directory</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">RNS_CONFIG</span></code> - Path to alternative Reticulum configuration directory</p></li>
</ul>
<p>The client configuration file is located at <codeclass="docutils literal notranslate"><spanclass="pre">~/.rngit/client_config</span></code> and allows adjusting parameters such as the reference batch size for transfers.</p>
<h3>The rnx Utility<aclass="headerlink"href="#the-rnx-utility"title="Link to this heading">¶</a></h3>
<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>
making it ideal for remote administration and management tasks that require
real-time interaction, just like SSH does for IP networks.</p>
<p><codeclass="docutils literal notranslate"><spanclass="pre">rnsh</span></code> operates in two modes: a <em>listener</em> mode that accepts incoming
connections, and an <em>initiator</em> mode that connects to a remote listener. Both
sides authenticate using Reticulum Identities, ensuring that only authorised
peers can establish sessions.</p>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p><codeclass="docutils literal notranslate"><spanclass="pre">rnsh</span></code> provides a genuine interactive terminal over Reticulum. It supports
full terminal emulation including escape sequences, window resizing, signal
forwarding, and piping of standard input, output and error streams. This
makes it suitable for running text editors, terminal multiplexers, and any
other interactive programs on remote systems.</p>
</div>
<p><strong>Usage Examples</strong></p>
<p>Start <codeclass="docutils literal notranslate"><spanclass="pre">rnsh</span></code> in listener mode, accepting connections from specific identities:</p>
<divclass="highlight-text notranslate"><divclass="highlight"><pre><span></span>$ rnsh -l -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
</pre></div>
</div>
<p>You can also specify allowed identity hashes (one per line) in the file
<codeclass="docutils literal notranslate"><spanclass="pre">~/.rnsh/allowed_identities</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">~/.config/rnsh/allowed_identities</span></code>, and
<p>Specify a command to run on the remote system, separating <codeclass="docutils literal notranslate"><spanclass="pre">rnsh</span></code> options from
the remote command with <codeclass="docutils literal notranslate"><spanclass="pre">--</span></code>:</p>
<divclass="highlight-text notranslate"><divclass="highlight"><pre><span></span>$ rnsh 7a55144adf826958a9529a3bcf08b149 -- top
</pre></div>
</div>
<p>Set a default command for the listener, in case the initiator does not supply
one, or when remote command execution is disabled:</p>
<p>Use the <codeclass="docutils literal notranslate"><spanclass="pre">-p</span></code> flag to display the identity and destination hash for a listener:</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">-b</span></code> option specifies the announce period in seconds. Use <codeclass="docutils literal notranslate"><spanclass="pre">0</span></code> to
announce only once at startup.</p>
<p><strong>Authentication & Authorisation</strong></p>
with a Reticulum Identity whose hash is present in the list of allowed
identities. Allowed identities can be specified on the command line with the
<codeclass="docutils literal notranslate"><spanclass="pre">-a</span></code> option, and can be used multiple times:</p>
<divclass="highlight-text notranslate"><divclass="highlight"><pre><span></span>$ rnsh -l -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
</pre></div>
</div>
<p>You can also maintain a list of allowed identity hashes in the file
<codeclass="docutils literal notranslate"><spanclass="pre">~/.rnsh/allowed_identities</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">~/.config/rnsh/allowed_identities</span></code>,
with one hex hash per line. This file is reloaded every time a new connection
is received, so changes take effect immediately without restarting <codeclass="docutils literal notranslate"><spanclass="pre">rnsh</span></code>.</p>
<p>If you want to accept connections from any identity (for testing or in fully
trusted environments), you can disable authentication with the <codeclass="docutils literal notranslate"><spanclass="pre">-n</span></code> option:</p>
<p>Disabling authentication with <codeclass="docutils literal notranslate"><spanclass="pre">-n</span></code> means that <strong>any</strong> Reticulum peer that
can reach your listener will be able to execute commands on your system. Only
use this option if you <em>really</em> know what you’re doing.</p>
</div>
<p><strong>Remote Command Control</strong></p>
<p>When running in listener mode, <codeclass="docutils literal notranslate"><spanclass="pre">rnsh</span></code> allows you to control how remote
commands are handled:</p>
<ulclass="simple">
<li><p>By default, the listener accepts the command sent by the initiator. If the
initiator does not supply a command, the listener’s default shell is used.</p></li>
<li><p>Use <codeclass="docutils literal notranslate"><spanclass="pre">-C</span></code> (<codeclass="docutils literal notranslate"><spanclass="pre">--no-remote-command</span></code>) to disable execution of commands received
from the initiator. Only the listener’s default command (or the command
specified after <codeclass="docutils literal notranslate"><spanclass="pre">--</span></code>) will be executed:</p></li>
<p>This allows you to run multiple listeners on the same node, each with a
different service name and purpose.</p>
<p><strong>Initiator Options</strong></p>
<p>When connecting to a remote listener, several options are available:</p>
<ulclass="simple">
<li><p>Use <codeclass="docutils literal notranslate"><spanclass="pre">-N</span></code> (<codeclass="docutils literal notranslate"><spanclass="pre">--no-id</span></code>) to disable sending your identity to the remote
listener. Note that the listener must have authentication disabled (<codeclass="docutils literal notranslate"><spanclass="pre">-n</span></code>)
for the connection to succeed in this case.</p></li>
<li><p>Use <codeclass="docutils literal notranslate"><spanclass="pre">-m</span></code> (<codeclass="docutils literal notranslate"><spanclass="pre">--mirror</span></code>) to make the initiator return with the exit code of
the remote process, rather than always returning <codeclass="docutils literal notranslate"><spanclass="pre">0</span></code>.</p></li>
<li><p>Use <codeclass="docutils literal notranslate"><spanclass="pre">-w</span></code> (<codeclass="docutils literal notranslate"><spanclass="pre">--timeout</span></code>) to specify the connection and request timeout in
seconds. By default, the timeout matches the Reticulum path request timeout.</p></li>
</ul>
<p><strong>Identity & Destination</strong></p>
<p>The default identity file for <codeclass="docutils literal notranslate"><spanclass="pre">rnsh</span></code> is stored at
<codeclass="docutils literal notranslate"><spanclass="pre">~/.reticulum/identities/rnsh</span></code>, but you can specify a different one with the
<codeclass="docutils literal notranslate"><spanclass="pre">-i</span></code> option, which will be created if it does not already exist:</p>
<p>To display the identity and destination information for a listener, use the
<codeclass="docutils literal notranslate"><spanclass="pre">-p</span></code> option. When combined with <codeclass="docutils literal notranslate"><spanclass="pre">-l</span></code>, both the identity and the listening
<p>By default, all log output is routed to <codeclass="docutils literal notranslate"><spanclass="pre">~/.rnsh/logfile</span></code> for initiators.</p>
<p><strong>Escape Sequences</strong></p>
<p>During an active <codeclass="docutils literal notranslate"><spanclass="pre">rnsh</span></code> session, the following escape sequences are
available. These are only recognised immediately after a newline character:</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">~~</span></code> - Send a literal tilde character</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">~.</span></code> - Terminate the session and exit immediately</p></li>
<h3>The rnodeconf Utility<aclass="headerlink"href="#the-rnodeconf-utility"title="Link to this heading">¶</a></h3>
<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>
Set specific baud rate when flashing device. Default is 921600
-N, --normal Switch device to normal mode
-T, --tnc Switch device to TNC mode
-b, --bluetooth-on Turn device bluetooth on
-B, --bluetooth-off Turn device bluetooth off
-p, --bluetooth-pair Put device into bluetooth pairing mode
-D, --display i Set display intensity (0-255)
-t, --timeout s Set display timeout in seconds, 0 to disable
-R, --rotation rotation
Set display rotation, valid values are 0 through 3
--display-addr byte Set display address as hex byte (00 - FF)
--recondition-display
Start display reconditioning
--np i Set NeoPixel intensity (0-255)
--freq Hz Frequency in Hz for TNC mode
--bw Hz Bandwidth in Hz for TNC mode
--txp dBm TX power in dBm for TNC mode
--sf factor Spreading factor for TNC mode (7 - 12)
--cr rate Coding rate for TNC mode (5 - 8)
-x, --ia-enable Enable interference avoidance
-X, --ia-disable Disable interference avoidance
-c, --config Print device configuration
--eeprom-backup Backup EEPROM to file
--eeprom-dump Dump EEPROM to console
--eeprom-wipe Unlock and wipe EEPROM
-P, --public Display public part of signing key
--trust-key hexbytes Public key to trust for device verification
--version Print program version and exit
-f, --flash Flash firmware and bootstrap EEPROM
-r, --rom Bootstrap EEPROM without flashing firmware
-k, --key Generate a new signing key and exit
-S, --sign Display public part of signing key
-H, --firmware-hash FIRMWARE_HASH
Set installed firmware hash
--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>
section of this manual.</p>
</section>
</section>
<sectionid="discovering-interfaces">
<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>
<h2>Remote Management<aclass="headerlink"href="#remote-management"title="Link to this heading">¶</a></h2>
<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>
</section>
<sectionid="blackhole-management">
<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>
<divclass="admonition important">
<pclass="admonition-title">Important</p>
<p>There is fundamentally <strong>no way</strong> to <em>globally</em> block or censor any identity or destination in Reticulum networks. The blackhole functionality will prevent announces from (and traffic to) all destinations associated with the blackholed identity <em>on your own network segments only</em>.</p>
<p>This provides users and operators with control over what they want to allow <em>on their own network segments</em>, but there is no way to globally censor or remove an identity, as long as <em>someone</em> is willing to provide transport for it.</p>
</div>
<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>
<divclass="admonition warning">
<pclass="admonition-title">Warning</p>
<p><strong>Verify Before Subscribing!</strong> Subscribing to a blackhole source is a powerful action that grants that source the ability to dictate who you can communicate with. Before adding a source to your configuration, verify that the maintainer aligns with your usage policy and values. Blindly subscribing to untrusted lists could inadvertently block legitimate peers or essential services.</p>
</div>
<p>When enabled, your Transport Instance will periodically (approximately once per hour) connect to configured sources, retrieve their latest blackhole lists, and automatically merge them into your local blocklist. This provides “set-and-forget” protection for both individual users and large networks.</p>
<p><strong>Configuration</strong></p>
<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><strong>Enabling Publishing</strong></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>
</section>
</section>
<sectionid="improving-system-configuration">
<h2>Improving System Configuration<aclass="headerlink"href="#improving-system-configuration"title="Link to this heading">¶</a></h2>
<p>If you are setting up a system for permanent use with Reticulum, there is a
few system configuration changes that can make this easier to administrate.
These changes will be detailed here.</p>
<sectionid="fixed-serial-port-names">
<h3>Fixed Serial Port Names<aclass="headerlink"href="#fixed-serial-port-names"title="Link to this heading">¶</a></h3>
<p>On a Reticulum instance with several serial port based interfaces, it can be
beneficial to use the fixed device names for the serial ports, instead
of the dynamically allocated shorthands such as <codeclass="docutils literal notranslate"><spanclass="pre">/dev/ttyUSB0</span></code>. Under most
Debian-based distributions, including Ubuntu and Raspberry Pi OS, these nodes
can be found under <codeclass="docutils literal notranslate"><spanclass="pre">/dev/serial/by-id</span></code>.</p>
<p>You can use such a device path directly in place of the numbered shorthands.
Here is an example of a packet radio TNC configured as such:</p>
<divclass="highlight-text notranslate"><divclass="highlight"><pre><span></span>[[Packet Radio KISS Interface]]
type = KISSInterface
interface_enabled = True
outgoing = true
port = /dev/serial/by-id/usb-FTDI_FT230X_Basic_UART_43891CKM-if00-port0
speed = 115200
databits = 8
parity = none
stopbits = 1
preamble = 150
txtail = 10
persistence = 200
slottime = 20
</pre></div>
</div>
<p>Using this methodology avoids potential naming mix-ups where physical devices
might be plugged and unplugged in different orders, or when device name
assignment varies from one boot to another.</p>
</section>
<sectionid="reticulum-as-a-system-service">
<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>Instead of starting Reticulum manually, you can install <codeclass="docutils literal notranslate"><spanclass="pre">rnsd</span></code> as a system
service and have it start automatically at boot.</p>
<sectionid="systemwide-service">
<h4>Systemwide Service<aclass="headerlink"href="#systemwide-service"title="Link to this heading">¶</a></h4>
<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>
<h4>Userspace Service<aclass="headerlink"href="#userspace-service"title="Link to this heading">¶</a></h4>
<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>
