<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="Getting Started Fast"href="gettingstartedfast.html"/>
<spanid="using-main"></span><h1>Using Reticulum on Your System<aclass="headerlink"href="#using-reticulum-on-your-system"title="Permalink 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="Permalink 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-default 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>
<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
<h2>Included Utility Programs<aclass="headerlink"href="#included-utility-programs"title="Permalink 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="Permalink 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
<p>You can even run multiple instances of <codeclass="docutils literal notranslate"><spanclass="pre">rnsd</span></code> with different configurations on
<p>Run <codeclass="docutils literal notranslate"><spanclass="pre">rnsd</span></code> in service mode, ensuring all logging output is sent directly to file:</p>
--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="Permalink 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>
<h3>The rnid Utility<aclass="headerlink"href="#the-rnid-utility"title="Permalink 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
--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="Permalink 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
<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>
--version show program's version number and exit
</pre></div>
</div>
</section>
<sectionid="the-rnx-utility">
<h3>The rnx Utility<aclass="headerlink"href="#the-rnx-utility"title="Permalink 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>
--config path path to alternative Reticulum config directory
-v, --verbose increase verbosity
-q, --quiet decrease verbosity
-p, --print-identity print identity and destination info and exit
-l, --listen listen for incoming commands
-i identity path to identity to use
-x, --interactive enter interactive mode
-b, --no-announce don't announce at program start
-a allowed_hash accept from this identity
-n, --noauth accept files from anyone
-N, --noid don't identify to listener
-d, --detailed show detailed result output
-m mirror exit code of remote command
-w seconds connect and request timeout before giving up
-W seconds max result download time
--stdin STDIN pass input to stdin
--stdout STDOUT max size in bytes of returned stdout
--stderr STDERR max size in bytes of returned stderr
--version show program's version number and exit
</pre></div>
</div>
</section>
<sectionid="the-rnodeconf-utility">
<h3>The rnodeconf Utility<aclass="headerlink"href="#the-rnodeconf-utility"title="Permalink 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>
<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="improving-system-configuration">
<h2>Improving System Configuration<aclass="headerlink"href="#improving-system-configuration"title="Permalink 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="Permalink 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="Permalink 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>
<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="Permalink 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>
