William/Reticulum
1
0
Fork 0
mirror of https://github.com/markqvist/Reticulum.git synced 2024-11-22 13:40:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updated utilities section of docs

Browse Source
This commit is contained in:
Mark Qvist 2023-09-18 23:16:57 +02:00
parent 334f2a364d
commit 70cbb8dc79
6 changed files with 495 additions and 223 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/Reticulum Manual.epub
View File

Binary file not shown.

BIN
docs/Reticulum Manual.pdf
View File

Binary file not shown.

256
docs/manual/_sources/using.rst.txt
View File

@ -179,28 +179,34 @@ When ``rnsd`` is running, it will keep all configured interfaces open, handle tr
it is enabled, and allow any other programs to immediately utilise the it is enabled, and allow any other programs to immediately utilise the
Reticulum network it is configured for. Reticulum network it is configured for.
You can even run multiple instances of rnsd with different configurations on You can even run multiple instances of ``rnsd`` with different configurations on
the same system. the same system.
.. code:: text **Usage Examples**
# Install Reticulum Run ``rnsd``:
pip3 install rns
# Run rnsd
rnsd
.. code:: text .. code:: text
usage: rnsd [-h] [--config CONFIG] [-v] [-q] [--version] $ rnsd
[2023-08-18 17:59:56] [Notice] Started rnsd version 0.5.8
**All Command-Line Options**
.. code:: text
usage: rnsd.py [-h] [--config CONFIG] [-v] [-q] [-s] [--exampleconfig] [--version]
Reticulum Network Stack Daemon Reticulum Network Stack Daemon
optional arguments: options:
-h, --help show this help message and exit -h, --help show this help message and exit
--config CONFIG path to alternative Reticulum config directory --config CONFIG path to alternative Reticulum config directory
-v, --verbose -v, --verbose
-q, --quiet -q, --quiet
-s, --service rnsd is running as a service and should log to file
--exampleconfig print verbose configuration example to stdout and exit
--version show program's version number and exit --version show program's version number and exit
You can easily add ``rnsd`` as an always-on service by :ref:`configuring a service<using-systemd>`. You can easily add ``rnsd`` as an always-on service by :ref:`configuring a service<using-systemd>`.
@ -211,12 +217,14 @@ The rnstatus Utility
Using the ``rnstatus`` utility, you can view the status of configured Reticulum Using the ``rnstatus`` utility, you can view the status of configured Reticulum
interfaces, similar to the ``ifconfig`` program. interfaces, similar to the ``ifconfig`` program.
**Usage Examples**
Run ``rnstatus``:
.. code:: text .. code:: text
# Run rnstatus $ rnstatus
rnstatus
# Example output
Shared Instance[37428] Shared Instance[37428]
Status : Up Status : Up
Serving : 1 program Serving : 1 program
@ -249,17 +257,39 @@ interfaces, similar to the ``ifconfig`` program.
Reticulum Transport Instance <5245a8efe1788c6a1cd36144a270e13b> running Reticulum Transport Instance <5245a8efe1788c6a1cd36144a270e13b> running
Filter output to only show some interfaces:
.. code:: text .. code:: text
usage: rnstatus [-h] [--config CONFIG] [--version] [-a] [-v] $ rnstatus rnode
RNodeInterface[RNode UHF]
Status : Up
Mode : Access Point
Rate : 1.30 kbps
Access : 64-bit IFAC by <…e702c42ba8>
Traffic : 8.49 KB↑
9.23 KB↓
Reticulum Transport Instance <5245a8efe1788c6a1cd36144a270e13b> running
**All Command-Line Options**
.. code:: text
usage: rnstatus.py [-h] [--config CONFIG] [--version] [-a] [-j] [-v] [filter]
Reticulum Network Stack Status Reticulum Network Stack Status
optional arguments: positional arguments:
filter only display interfaces with names including filter
options:
-h, --help show this help message and exit -h, --help show this help message and exit
--config CONFIG path to alternative Reticulum config directory --config CONFIG path to alternative Reticulum config directory
--version show program's version number and exit --version show program's version number and exit
-a, --all show all interfaces -a, --all show all interfaces
-j, --json output in JSON format
-v, --verbose -v, --verbose
@ -268,42 +298,67 @@ The rnid Utility
With the ``rnid`` utility, you can generate, manage and view Reticulum Identities. With the ``rnid`` utility, you can generate, manage and view Reticulum Identities.
The program can also calculate Destination hashes, and perform encryption and The program can also calculate Destination hashes, and perform encryption and
decryption of files. Using ``rnid``, it is possible to asymmetrically encrypt decryption of files.
files and information for any destination hash, and also to create and verify
cryptographic signatures. Using ``rnid``, it is possible to asymmetrically encrypt files and information for
any Reticulum destination hash, and also to create and verify cryptographic signatures.
**Usage Examples**
Generate a new Identity:
.. code:: text .. code:: text
# Generate a new Identity $ rnid -g ./new_identity
rnid -g ./new_identity
# Display Identity key information Display Identity key information:
rnid -i ./new_identity -p
.. code:: text
$ rnid -i ./new_identity -p
Loaded Identity <984b74a3f768bef236af4371e6f248cd> from new_id Loaded Identity <984b74a3f768bef236af4371e6f248cd> from new_id
Public Key : 0f4259fef4521ab75a3409e353fe9073eb10783b4912a6a9937c57bf44a62c1e Public Key : 0f4259fef4521ab75a3409e353fe9073eb10783b4912a6a9937c57bf44a62c1e
Private Key : Hidden Private Key : Hidden
# Encrypt a file for an LXMF user Encrypt a file for an LXMF user:
rnid -i 8dd57a738226809646089335a6b03695 -e my_file.txt
.. code:: text
$ rnid -i 8dd57a738226809646089335a6b03695 -e my_file.txt
Recalled Identity <bc7291552be7a58f361522990465165c> for destination <8dd57a738226809646089335a6b03695> Recalled Identity <bc7291552be7a58f361522990465165c> for destination <8dd57a738226809646089335a6b03695>
Encrypting my_file.txt Encrypting my_file.txt
File my_file.txt encrypted for <bc7291552be7a58f361522990465165c> to my_file.txt.rfe File my_file.txt encrypted for <bc7291552be7a58f361522990465165c> to my_file.txt.rfe
# If the Identity for the destination is not already known, If the Identity for the destination is not already known, you can fetch it from the network by using the ``-R`` command-line option:
# you can fetch it from the network by using the -R option
rnid -R -i 30602def3b3506a28ed33db6f60cc6c9 -e my_file.txt .. code:: text
$ rnid -R -i 30602def3b3506a28ed33db6f60cc6c9 -e my_file.txt
Requesting unknown Identity for <30602def3b3506a28ed33db6f60cc6c9>... Requesting unknown Identity for <30602def3b3506a28ed33db6f60cc6c9>...
Received Identity <2b489d06eaf7c543808c76a5332a447d> for destination <30602def3b3506a28ed33db6f60cc6c9> from the network Received Identity <2b489d06eaf7c543808c76a5332a447d> for destination <30602def3b3506a28ed33db6f60cc6c9> from the network
Encrypting my_file.txt Encrypting my_file.txt
File my_file.txt encrypted for <2b489d06eaf7c543808c76a5332a447d> to my_file.txt.rfe File my_file.txt encrypted for <2b489d06eaf7c543808c76a5332a447d> to my_file.txt.rfe
Decrypt a file using the Reticulum Identity it was encrypted for:
.. code:: text .. code:: text
usage: rnid [-h] [--config path] [-i identity] [-g path] [-v] [-q] [-a aspects] [-H aspects] [-e path] [-d path] [-s path] [-V path] [-r path] [-w path] [-f] [-R] [-t seconds] [-p] [-P] $ rnid -i ./my_identity -d my_file.txt.rfe
[--version]
Loaded Identity <2225fdeecaf6e2db4556c3c2d7637294> from ./my_identity
Decrypting ./my_file.txt.rfe...
File ./my_file.txt.rfe decrypted with <2225fdeecaf6e2db4556c3c2d7637294> to ./my_file.txt
**All Command-Line Options**
.. code:: text
usage: rnid.py [-h] [--config path] [-i identity] [-g path] [-v] [-q] [-a aspects]
[-H aspects] [-e path] [-d path] [-s path] [-V path] [-r path] [-w path]
[-f] [-R] [-t seconds] [-p] [-P] [--version]
Reticulum Identity & Encryption Utility Reticulum Identity & Encryption Utility
@ -344,24 +399,29 @@ The rnpath Utility
With the ``rnpath`` utility, you can look up and view paths for With the ``rnpath`` utility, you can look up and view paths for
destinations on the Reticulum network. destinations on the Reticulum network.
**Usage Examples**
Resolve path to a destination:
.. code:: text .. code:: text
# Run rnpath $ rnpath c89b4da064bf66d280f0e4d8abfd9806
rnpath c89b4da064bf66d280f0e4d8abfd9806
# Example output
Path found, destination <c89b4da064bf66d280f0e4d8abfd9806> is 4 hops away via <f53a1c4278e0726bb73fcc623d6ce763> on TCPInterface[Testnet/dublin.connect.reticulum.network:4965] Path found, destination <c89b4da064bf66d280f0e4d8abfd9806> is 4 hops away via <f53a1c4278e0726bb73fcc623d6ce763> on TCPInterface[Testnet/dublin.connect.reticulum.network:4965]
**All Command-Line Options**
.. code:: text .. code:: text
usage: rnpath [-h] [--config CONFIG] [--version] [-t] [-r] [-d] [-D] [-w seconds] [-v] [destination] usage: rnpath.py [-h] [--config CONFIG] [--version] [-t] [-r] [-d] [-D]
[-w seconds] [-v] [destination]
Reticulum Path Discovery Utility Reticulum Path Discovery Utility
positional arguments: positional arguments:
destination hexadecimal hash of the destination destination hexadecimal hash of the destination
optional arguments: options:
-h, --help show this help message and exit -h, --help show this help message and exit
--config CONFIG path to alternative Reticulum config directory --config CONFIG path to alternative Reticulum config directory
--version show program's version number and exit --version show program's version number and exit
@ -381,16 +441,20 @@ to the ``ping`` program. Please note that probes will only be answered if the
specified destination is configured to send proofs for received packets. Many specified destination is configured to send proofs for received packets. Many
destinations will not have this option enabled, and will not be probable. destinations will not have this option enabled, and will not be probable.
**Usage Examples**
Probe a destination:
.. code:: text .. code:: text
# Run rnprobe $ rnprobe example_utilities.echo.request 2d03725b327348980d570f739a3a5708
rnprobe example_utilities.echo.request 2d03725b327348980d570f739a3a5708
# Example output
Sent 16 byte probe to <2d03725b327348980d570f739a3a5708> Sent 16 byte probe to <2d03725b327348980d570f739a3a5708>
Valid reply received from <2d03725b327348980d570f739a3a5708> Valid reply received from <2d03725b327348980d570f739a3a5708>
Round-trip time is 38.469 milliseconds over 2 hops Round-trip time is 38.469 milliseconds over 2 hops
**All Command-Line Options**
.. code:: text .. code:: text
usage: rnprobe [-h] [--config CONFIG] [--version] [-v] [full_name] [destination_hash] usage: rnprobe [-h] [--config CONFIG] [--version] [-v] [full_name] [destination_hash]
@ -414,20 +478,39 @@ The rncp Utility
The ``rncp`` utility is a simple file transfer tool. Using it, you can transfer The ``rncp`` utility is a simple file transfer tool. Using it, you can transfer
files through Reticulum. files through Reticulum.
**Usage Examples**
Run rncp on the receiving system, specifying which identities are allowed to send files:
.. code:: text .. code:: text
# Run rncp on the receiving system, specifying which identities $ rncp --listen -a 1726dbad538775b5bf9b0ea25a4079c8 -a c50cc4e4f7838b6c31f60ab9032cbc62
# are allowed to send files
rncp --receive -a 1726dbad538775b5bf9b0ea25a4079c8 -a c50cc4e4f7838b6c31f60ab9032cbc62
# From another system, copy a file to the receiving system You can also specify allowed identity hashes (one per line) in the file ~/.rncp/allowed_identities
rncp ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e and simply running the program in listener mode:
You can specify as many allowed senders as needed, or complete disable authentication.
.. code:: text .. code:: text
usage: rncp [-h] [--config path] [-v] [-q] [-p] [-r] [-b] [-a allowed_hash] [-n] [-w seconds] [--version] [file] [destination] $ rncp --listen
From another system, copy a file to the receiving system:
.. code:: text
$ rncp ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
Or fetch a file from the remote system:
.. code:: text
$ rncp --fetch ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
**All Command-Line Options**
.. code:: text
usage: rncp.py [-h] [--config path] [-v] [-q] [-S] [-l] [-f] [-b seconds]
[-a allowed_hash] [-n] [-p] [-w seconds] [--version] [file] [destination]
Reticulum File Transfer Utility Reticulum File Transfer Utility
@ -435,19 +518,20 @@ You can specify as many allowed senders as needed, or complete disable authentic
file file to be transferred file file to be transferred
destination hexadecimal hash of the receiver destination hexadecimal hash of the receiver
optional arguments: options:
-h, --help show this help message and exit -h, --help show this help message and exit
--config path path to alternative Reticulum config directory --config path path to alternative Reticulum config directory
-v, --verbose increase verbosity -v, --verbose increase verbosity
-q, --quiet decrease verbosity -q, --quiet decrease verbosity
-p, --print-identity print identity and destination info and exit -S, --silent disable transfer progress output
-r, --receive wait for incoming files -l, --listen listen for incoming transfer requests
-b, --no-announce don't announce at program start -f, --fetch fetch file from remote listener instead of sending
-b seconds announce interval, 0 to only announce at startup
-a allowed_hash accept from this identity -a allowed_hash accept from this identity
-n, --no-auth accept files from anyone -n, --no-auth accept files and fetches from anyone
-p, --print-identity print identity and destination info and exit
-w seconds sender timeout before giving up -w seconds sender timeout before giving up
--version show program's version number and exit --version show program's version number and exit
-v, --verbose
The rnx Utility The rnx Utility
@ -455,32 +539,43 @@ The rnx Utility
The ``rnx`` utility is a basic remote command execution program. It allows you to The ``rnx`` utility is a basic remote command execution program. It allows you to
execute commands on remote systems over Reticulum, and to view returned command execute commands on remote systems over Reticulum, and to view returned command
output. output. For a fully interactive remote shell solution, be sure to also take a look
at the `rnsh <https://github.com/acehoss/rnsh>`_ program.
**Usage Examples**
Run rnx on the listening system, specifying which identities are allowed to execute commands:
.. code:: text .. code:: text
# Run rnx on the listening system, specifying which identities $ rnx --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
# are allowed to execute commands
rnx --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
# From another system, run a command From another system, run a command on the remote:
rnx 7a55144adf826958a9529a3bcf08b149 "cat /proc/cpuinfo"
# Or enter the interactive mode pseudo-shell
rnx 7a55144adf826958a9529a3bcf08b149 -x
# The default identity file is stored in
# ~/.reticulum/identities/rnx, but you can use
# another one, which will be created if it does
# not already exist
rnx 7a55144adf826958a9529a3bcf08b149 -i /path/to/identity -x
You can specify as many allowed senders as needed, or completely disable authentication.
.. code:: text .. code:: text
usage: rnx [-h] [--config path] [-v] [-q] [-p] [-l] [-i identity] [-x] [-b] [-a allowed_hash] [-n] [-N] [-d] [-m] [-w seconds] [-W seconds] [--stdin STDIN] [--stdout STDOUT] [--stderr STDERR] [--version] $ rnx 7a55144adf826958a9529a3bcf08b149 "cat /proc/cpuinfo"
[destination] [command]
Or enter the interactive mode pseudo-shell:
.. code:: text
$ rnx 7a55144adf826958a9529a3bcf08b149 -x
The default identity file is stored in ``~/.reticulum/identities/rnx``, but you can use
another one, which will be created if it does not already exist
.. code:: text
$ rnx 7a55144adf826958a9529a3bcf08b149 -i /path/to/identity -x
**All Command-Line Options**
.. code:: text
usage: rnx [-h] [--config path] [-v] [-q] [-p] [-l] [-i identity] [-x] [-b] [-n] [-N]
[-d] [-m] [-a allowed_hash] [-w seconds] [-W seconds] [--stdin STDIN]
[--stdout STDOUT] [--stderr STDERR] [--version] [destination] [command]
Reticulum Remote Execution Utility Reticulum Remote Execution Utility
@ -517,11 +612,19 @@ The rnodeconf Utility
The ``rnodeconf`` utility allows you to inspect and configure existing :ref:`RNodes<rnode-main>`, and The ``rnodeconf`` utility allows you to inspect and configure existing :ref:`RNodes<rnode-main>`, and
to create and provision new :ref:`RNodes<rnode-main>` from any supported hardware devices. to create and provision new :ref:`RNodes<rnode-main>` from any supported hardware devices.
**All Command-Line Options**
.. code:: text .. code:: text
usage: rnodeconf [-h] [-i] [-a] [-u] [-U] [--fw-version version] [--nocheck] [-C] [-N] [-T] [-b] [-B] [-p] [--freq Hz] [--bw Hz] [--txp dBm] [--sf factor] [--cr rate] [--eeprom-backup] [--eeprom-dump] [--eeprom-wipe] [--version] [port] usage: rnodeconf.py [-h] [-i] [-a] [-u] [-U] [--fw-version version] [--nocheck] [-e]
[-E] [-C] [--baud-flash baud_flash] [-N] [-T] [-b] [-B] [-p] [-D i]
[--freq Hz] [--bw Hz] [--txp dBm] [--sf factor] [--cr rate]
[--eeprom-backup] [--eeprom-dump] [--eeprom-wipe] [-P]
[--trust-key hexbytes] [--version] [port]
RNode Configuration and firmware utility. This program allows you to change various settings and startup modes of RNode. It can also install, flash and update the firmware on supported devices. RNode Configuration and firmware utility. This program allows you to change various
settings and startup modes of RNode. It can also install, flash and update the firmware
on supported devices.
positional arguments: positional arguments:
port serial port where RNode is attached port serial port where RNode is attached
@ -537,11 +640,14 @@ to create and provision new :ref:`RNodes<rnode-main>` from any supported hardwar
-e, --extract Extract firmware from connected RNode for later use -e, --extract Extract firmware from connected RNode for later use
-E, --use-extracted Use the extracted firmware for autoinstallation or update -E, --use-extracted Use the extracted firmware for autoinstallation or update
-C, --clear-cache Clear locally cached firmware files -C, --clear-cache Clear locally cached firmware files
--baud-flash baud_flash
Set specific baud rate when flashing device. Default is 921600
-N, --normal Switch device to normal mode -N, --normal Switch device to normal mode
-T, --tnc Switch device to TNC mode -T, --tnc Switch device to TNC mode
-b, --bluetooth-on Turn device bluetooth on -b, --bluetooth-on Turn device bluetooth on
-B, --bluetooth-off Turn device bluetooth off -B, --bluetooth-off Turn device bluetooth off
-p, --bluetooth-pair Put device into bluetooth pairing mode -p, --bluetooth-pair Put device into bluetooth pairing mode
-D i, --display i Set display intensity (0-255)
--freq Hz Frequency in Hz for TNC mode --freq Hz Frequency in Hz for TNC mode
--bw Hz Bandwidth in Hz for TNC mode --bw Hz Bandwidth in Hz for TNC mode
--txp dBm TX power in dBm for TNC mode --txp dBm TX power in dBm for TNC mode
@ -550,6 +656,8 @@ to create and provision new :ref:`RNodes<rnode-main>` from any supported hardwar
--eeprom-backup Backup EEPROM to file --eeprom-backup Backup EEPROM to file
--eeprom-dump Dump EEPROM to console --eeprom-dump Dump EEPROM to console
--eeprom-wipe Unlock and wipe EEPROM --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 --version Print program version and exit
For more information on how to create your own RNodes, please read the :ref:`Creating RNodes<rnode-creating>` For more information on how to create your own RNodes, please read the :ref:`Creating RNodes<rnode-creating>`

2
docs/manual/searchindex.js
View File

File diff suppressed because one or more lines are too long

209
docs/manual/using.html
View File

@ -379,24 +379,27 @@ other programs, applications and services can utilise.</p>
When <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> is running, it will keep all configured interfaces open, handle transport if When <code class="docutils literal notranslate"><span class="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 it is enabled, and allow any other programs to immediately utilise the
Reticulum network it is configured for.</p> Reticulum network it is configured for.</p>
<p>You can even run multiple instances of rnsd with different configurations on <p>You can even run multiple instances of <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> with different configurations on
the same system.</p> the same system.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Install Reticulum <p><strong>Usage Examples</strong></p>
pip3 install rns <p>Run <code class="docutils literal notranslate"><span class="pre">rnsd</span></code>:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsd
# Run rnsd [2023-08-18 17:59:56] [Notice] Started rnsd version 0.5.8
rnsd
</pre></div> </pre></div>
</div> </div>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnsd [-h] [--config CONFIG] [-v] [-q] [--version] <p><strong>All Command-Line Options</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnsd.py [-h] [--config CONFIG] [-v] [-q] [-s] [--exampleconfig] [--version]
Reticulum Network Stack Daemon Reticulum Network Stack Daemon
optional arguments: options:
-h, --help show this help message and exit -h, --help show this help message and exit
--config CONFIG path to alternative Reticulum config directory --config CONFIG path to alternative Reticulum config directory
-v, --verbose -v, --verbose
-q, --quiet -q, --quiet
-s, --service rnsd is running as a service and should log to file
--exampleconfig print verbose configuration example to stdout and exit
--version show program&#39;s version number and exit --version show program&#39;s version number and exit
</pre></div> </pre></div>
</div> </div>
@ -406,10 +409,10 @@ optional arguments:
<h3>The rnstatus Utility<a class="headerlink" href="#the-rnstatus-utility" title="Permalink to this heading">#</a></h3> <h3>The rnstatus Utility<a class="headerlink" href="#the-rnstatus-utility" title="Permalink to this heading">#</a></h3>
<p>Using the <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code> utility, you can view the status of configured Reticulum <p>Using the <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code> utility, you can view the status of configured Reticulum
interfaces, similar to the <code class="docutils literal notranslate"><span class="pre">ifconfig</span></code> program.</p> interfaces, similar to the <code class="docutils literal notranslate"><span class="pre">ifconfig</span></code> program.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rnstatus <p><strong>Usage Examples</strong></p>
rnstatus <p>Run <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code>:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnstatus
# Example output
Shared Instance[37428] Shared Instance[37428]
Status : Up Status : Up
Serving : 1 program Serving : 1 program
@ -443,15 +446,34 @@ RNodeInterface[RNode UHF]
Reticulum Transport Instance &lt;5245a8efe1788c6a1cd36144a270e13b&gt; running Reticulum Transport Instance &lt;5245a8efe1788c6a1cd36144a270e13b&gt; running
</pre></div> </pre></div>
</div> </div>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnstatus [-h] [--config CONFIG] [--version] [-a] [-v] <p>Filter output to only show some interfaces:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnstatus rnode
RNodeInterface[RNode UHF]
Status : Up
Mode : Access Point
Rate : 1.30 kbps
Access : 64-bit IFAC by &lt;…e702c42ba8&gt;
Traffic : 8.49 KB↑
9.23 KB↓
Reticulum Transport Instance &lt;5245a8efe1788c6a1cd36144a270e13b&gt; running
</pre></div>
</div>
<p><strong>All Command-Line Options</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnstatus.py [-h] [--config CONFIG] [--version] [-a] [-j] [-v] [filter]
Reticulum Network Stack Status Reticulum Network Stack Status
optional arguments: positional arguments:
filter only display interfaces with names including filter
options:
-h, --help show this help message and exit -h, --help show this help message and exit
--config CONFIG path to alternative Reticulum config directory --config CONFIG path to alternative Reticulum config directory
--version show program&#39;s version number and exit --version show program&#39;s version number and exit
-a, --all show all interfaces -a, --all show all interfaces
-j, --json output in JSON format
-v, --verbose -v, --verbose
</pre></div> </pre></div>
</div> </div>
@ -460,29 +482,32 @@ optional arguments:
<h3>The rnid Utility<a class="headerlink" href="#the-rnid-utility" title="Permalink to this heading">#</a></h3> <h3>The rnid Utility<a class="headerlink" href="#the-rnid-utility" title="Permalink to this heading">#</a></h3>
<p>With the <code class="docutils literal notranslate"><span class="pre">rnid</span></code> utility, you can generate, manage and view Reticulum Identities. <p>With the <code class="docutils literal notranslate"><span class="pre">rnid</span></code> utility, you can generate, manage and view Reticulum Identities.
The program can also calculate Destination hashes, and perform encryption and The program can also calculate Destination hashes, and perform encryption and
decryption of files. Using <code class="docutils literal notranslate"><span class="pre">rnid</span></code>, it is possible to asymmetrically encrypt decryption of files.</p>
files and information for any destination hash, and also to create and verify <p>Using <code class="docutils literal notranslate"><span class="pre">rnid</span></code>, it is possible to asymmetrically encrypt files and information for
cryptographic signatures.</p> any Reticulum destination hash, and also to create and verify cryptographic signatures.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Generate a new Identity <p><strong>Usage Examples</strong></p>
rnid -g ./new_identity <p>Generate a new Identity:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnid -g ./new_identity
# Display Identity key information </pre></div>
rnid -i ./new_identity -p </div>
<p>Display Identity key information:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnid -i ./new_identity -p
Loaded Identity &lt;984b74a3f768bef236af4371e6f248cd&gt; from new_id Loaded Identity &lt;984b74a3f768bef236af4371e6f248cd&gt; from new_id
Public Key : 0f4259fef4521ab75a3409e353fe9073eb10783b4912a6a9937c57bf44a62c1e Public Key : 0f4259fef4521ab75a3409e353fe9073eb10783b4912a6a9937c57bf44a62c1e
Private Key : Hidden Private Key : Hidden
</pre></div>
# Encrypt a file for an LXMF user </div>
rnid -i 8dd57a738226809646089335a6b03695 -e my_file.txt <p>Encrypt a file for an LXMF user:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnid -i 8dd57a738226809646089335a6b03695 -e my_file.txt
Recalled Identity &lt;bc7291552be7a58f361522990465165c&gt; for destination &lt;8dd57a738226809646089335a6b03695&gt; Recalled Identity &lt;bc7291552be7a58f361522990465165c&gt; for destination &lt;8dd57a738226809646089335a6b03695&gt;
Encrypting my_file.txt Encrypting my_file.txt
File my_file.txt encrypted for &lt;bc7291552be7a58f361522990465165c&gt; to my_file.txt.rfe File my_file.txt encrypted for &lt;bc7291552be7a58f361522990465165c&gt; to my_file.txt.rfe
</pre></div>
# If the Identity for the destination is not already known, </div>
# you can fetch it from the network by using the -R option <p>If the Identity for the destination is not already known, you can fetch it from the network by using the <code class="docutils literal notranslate"><span class="pre">-R</span></code> command-line option:</p>
rnid -R -i 30602def3b3506a28ed33db6f60cc6c9 -e my_file.txt <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnid -R -i 30602def3b3506a28ed33db6f60cc6c9 -e my_file.txt
Requesting unknown Identity for &lt;30602def3b3506a28ed33db6f60cc6c9&gt;... Requesting unknown Identity for &lt;30602def3b3506a28ed33db6f60cc6c9&gt;...
Received Identity &lt;2b489d06eaf7c543808c76a5332a447d&gt; for destination &lt;30602def3b3506a28ed33db6f60cc6c9&gt; from the network Received Identity &lt;2b489d06eaf7c543808c76a5332a447d&gt; for destination &lt;30602def3b3506a28ed33db6f60cc6c9&gt; from the network
@ -490,8 +515,18 @@ Encrypting my_file.txt
File my_file.txt encrypted for &lt;2b489d06eaf7c543808c76a5332a447d&gt; to my_file.txt.rfe File my_file.txt encrypted for &lt;2b489d06eaf7c543808c76a5332a447d&gt; to my_file.txt.rfe
</pre></div> </pre></div>
</div> </div>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnid [-h] [--config path] [-i identity] [-g path] [-v] [-q] [-a aspects] [-H aspects] [-e path] [-d path] [-s path] [-V path] [-r path] [-w path] [-f] [-R] [-t seconds] [-p] [-P] <p>Decrypt a file using the Reticulum Identity it was encrypted for:</p>
[--version] <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnid -i ./my_identity -d my_file.txt.rfe
Loaded Identity &lt;2225fdeecaf6e2db4556c3c2d7637294&gt; from ./my_identity
Decrypting ./my_file.txt.rfe...
File ./my_file.txt.rfe decrypted with &lt;2225fdeecaf6e2db4556c3c2d7637294&gt; to ./my_file.txt
</pre></div>
</div>
<p><strong>All Command-Line Options</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnid.py [-h] [--config path] [-i identity] [-g path] [-v] [-q] [-a aspects]
[-H aspects] [-e path] [-d path] [-s path] [-V path] [-r path] [-w path]
[-f] [-R] [-t seconds] [-p] [-P] [--version]
Reticulum Identity &amp; Encryption Utility Reticulum Identity &amp; Encryption Utility
@ -531,21 +566,23 @@ options:
<h3>The rnpath Utility<a class="headerlink" href="#the-rnpath-utility" title="Permalink to this heading">#</a></h3> <h3>The rnpath Utility<a class="headerlink" href="#the-rnpath-utility" title="Permalink to this heading">#</a></h3>
<p>With the <code class="docutils literal notranslate"><span class="pre">rnpath</span></code> utility, you can look up and view paths for <p>With the <code class="docutils literal notranslate"><span class="pre">rnpath</span></code> utility, you can look up and view paths for
destinations on the Reticulum network.</p> destinations on the Reticulum network.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rnpath <p><strong>Usage Examples</strong></p>
rnpath c89b4da064bf66d280f0e4d8abfd9806 <p>Resolve path to a destination:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnpath c89b4da064bf66d280f0e4d8abfd9806
# Example output
Path found, destination &lt;c89b4da064bf66d280f0e4d8abfd9806&gt; is 4 hops away via &lt;f53a1c4278e0726bb73fcc623d6ce763&gt; on TCPInterface[Testnet/dublin.connect.reticulum.network:4965] Path found, destination &lt;c89b4da064bf66d280f0e4d8abfd9806&gt; is 4 hops away via &lt;f53a1c4278e0726bb73fcc623d6ce763&gt; on TCPInterface[Testnet/dublin.connect.reticulum.network:4965]
</pre></div> </pre></div>
</div> </div>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnpath [-h] [--config CONFIG] [--version] [-t] [-r] [-d] [-D] [-w seconds] [-v] [destination] <p><strong>All Command-Line Options</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnpath.py [-h] [--config CONFIG] [--version] [-t] [-r] [-d] [-D]
[-w seconds] [-v] [destination]
Reticulum Path Discovery Utility Reticulum Path Discovery Utility
positional arguments: positional arguments:
destination hexadecimal hash of the destination destination hexadecimal hash of the destination
optional arguments: options:
-h, --help show this help message and exit -h, --help show this help message and exit
--config CONFIG path to alternative Reticulum config directory --config CONFIG path to alternative Reticulum config directory
--version show program&#39;s version number and exit --version show program&#39;s version number and exit
@ -564,15 +601,16 @@ optional arguments:
to the <code class="docutils literal notranslate"><span class="pre">ping</span></code> program. Please note that probes will only be answered if the to the <code class="docutils literal notranslate"><span class="pre">ping</span></code> program. Please note that probes will only be answered if the
specified destination is configured to send proofs for received packets. Many specified destination is configured to send proofs for received packets. Many
destinations will not have this option enabled, and will not be probable.</p> destinations will not have this option enabled, and will not be probable.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rnprobe <p><strong>Usage Examples</strong></p>
rnprobe example_utilities.echo.request 2d03725b327348980d570f739a3a5708 <p>Probe a destination:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnprobe example_utilities.echo.request 2d03725b327348980d570f739a3a5708
# Example output
Sent 16 byte probe to &lt;2d03725b327348980d570f739a3a5708&gt; Sent 16 byte probe to &lt;2d03725b327348980d570f739a3a5708&gt;
Valid reply received from &lt;2d03725b327348980d570f739a3a5708&gt; Valid reply received from &lt;2d03725b327348980d570f739a3a5708&gt;
Round-trip time is 38.469 milliseconds over 2 hops Round-trip time is 38.469 milliseconds over 2 hops
</pre></div> </pre></div>
</div> </div>
<p><strong>All Command-Line Options</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnprobe [-h] [--config CONFIG] [--version] [-v] [full_name] [destination_hash] <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnprobe [-h] [--config CONFIG] [--version] [-v] [full_name] [destination_hash]
Reticulum Probe Utility Reticulum Probe Utility
@ -593,16 +631,27 @@ optional arguments:
<h3>The rncp Utility<a class="headerlink" href="#the-rncp-utility" title="Permalink to this heading">#</a></h3> <h3>The rncp Utility<a class="headerlink" href="#the-rncp-utility" title="Permalink to this heading">#</a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">rncp</span></code> utility is a simple file transfer tool. Using it, you can transfer <p>The <code class="docutils literal notranslate"><span class="pre">rncp</span></code> utility is a simple file transfer tool. Using it, you can transfer
files through Reticulum.</p> files through Reticulum.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rncp on the receiving system, specifying which identities <p><strong>Usage Examples</strong></p>
# are allowed to send files <p>Run rncp on the receiving system, specifying which identities are allowed to send files:</p>
rncp --receive -a 1726dbad538775b5bf9b0ea25a4079c8 -a c50cc4e4f7838b6c31f60ab9032cbc62 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rncp --listen -a 1726dbad538775b5bf9b0ea25a4079c8 -a c50cc4e4f7838b6c31f60ab9032cbc62
# From another system, copy a file to the receiving system
rncp ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
</pre></div> </pre></div>
</div> </div>
<p>You can specify as many allowed senders as needed, or complete disable authentication.</p> <p>You can also specify allowed identity hashes (one per line) in the file ~/.rncp/allowed_identities
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rncp [-h] [--config path] [-v] [-q] [-p] [-r] [-b] [-a allowed_hash] [-n] [-w seconds] [--version] [file] [destination] and simply running the program in listener mode:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rncp --listen
</pre></div>
</div>
<p>From another system, copy a file to the receiving system:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rncp ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
</pre></div>
</div>
<p>Or fetch a file from the remote system:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rncp --fetch ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
</pre></div>
</div>
<p><strong>All Command-Line Options</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rncp.py [-h] [--config path] [-v] [-q] [-S] [-l] [-f] [-b seconds]
[-a allowed_hash] [-n] [-p] [-w seconds] [--version] [file] [destination]
Reticulum File Transfer Utility Reticulum File Transfer Utility
@ -610,19 +659,20 @@ positional arguments:
file file to be transferred file file to be transferred
destination hexadecimal hash of the receiver destination hexadecimal hash of the receiver
optional arguments: options:
-h, --help show this help message and exit -h, --help show this help message and exit
--config path path to alternative Reticulum config directory --config path path to alternative Reticulum config directory
-v, --verbose increase verbosity -v, --verbose increase verbosity
-q, --quiet decrease verbosity -q, --quiet decrease verbosity
-p, --print-identity print identity and destination info and exit -S, --silent disable transfer progress output
-r, --receive wait for incoming files -l, --listen listen for incoming transfer requests
-b, --no-announce don&#39;t announce at program start -f, --fetch fetch file from remote listener instead of sending
-b seconds announce interval, 0 to only announce at startup
-a allowed_hash accept from this identity -a allowed_hash accept from this identity
-n, --no-auth accept files from anyone -n, --no-auth accept files and fetches from anyone
-p, --print-identity print identity and destination info and exit
-w seconds sender timeout before giving up -w seconds sender timeout before giving up
--version show program&#39;s version number and exit --version show program&#39;s version number and exit
-v, --verbose
</pre></div> </pre></div>
</div> </div>
</section> </section>
@ -630,27 +680,30 @@ optional arguments:
<h3>The rnx Utility<a class="headerlink" href="#the-rnx-utility" title="Permalink to this heading">#</a></h3> <h3>The rnx Utility<a class="headerlink" href="#the-rnx-utility" title="Permalink to this heading">#</a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">rnx</span></code> utility is a basic remote command execution program. It allows you to <p>The <code class="docutils literal notranslate"><span class="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 execute commands on remote systems over Reticulum, and to view returned command
output.</p> output. For a fully interactive remote shell solution, be sure to also take a look
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rnx on the listening system, specifying which identities at the <a class="reference external" href="https://github.com/acehoss/rnsh">rnsh</a> program.</p>
# are allowed to execute commands <p><strong>Usage Examples</strong></p>
rnx --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10 <p>Run rnx on the listening system, specifying which identities are allowed to execute commands:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnx --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
# From another system, run a command
rnx 7a55144adf826958a9529a3bcf08b149 &quot;cat /proc/cpuinfo&quot;
# Or enter the interactive mode pseudo-shell
rnx 7a55144adf826958a9529a3bcf08b149 -x
# The default identity file is stored in
# ~/.reticulum/identities/rnx, but you can use
# another one, which will be created if it does
# not already exist
rnx 7a55144adf826958a9529a3bcf08b149 -i /path/to/identity -x
</pre></div> </pre></div>
</div> </div>
<p>You can specify as many allowed senders as needed, or completely disable authentication.</p> <p>From another system, run a command on the remote:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnx [-h] [--config path] [-v] [-q] [-p] [-l] [-i identity] [-x] [-b] [-a allowed_hash] [-n] [-N] [-d] [-m] [-w seconds] [-W seconds] [--stdin STDIN] [--stdout STDOUT] [--stderr STDERR] [--version] <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnx 7a55144adf826958a9529a3bcf08b149 &quot;cat /proc/cpuinfo&quot;
[destination] [command] </pre></div>
</div>
<p>Or enter the interactive mode pseudo-shell:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnx 7a55144adf826958a9529a3bcf08b149 -x
</pre></div>
</div>
<p>The default identity file is stored in <code class="docutils literal notranslate"><span class="pre">~/.reticulum/identities/rnx</span></code>, but you can use
another one, which will be created if it does not already exist</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnx 7a55144adf826958a9529a3bcf08b149 -i /path/to/identity -x
</pre></div>
</div>
<p><strong>All Command-Line Options</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnx [-h] [--config path] [-v] [-q] [-p] [-l] [-i identity] [-x] [-b] [-n] [-N]
[-d] [-m] [-a allowed_hash] [-w seconds] [-W seconds] [--stdin STDIN]
[--stdout STDOUT] [--stderr STDERR] [--version] [destination] [command]
Reticulum Remote Execution Utility Reticulum Remote Execution Utility
@ -686,9 +739,16 @@ optional arguments:
<h3>The rnodeconf Utility<a class="headerlink" href="#the-rnodeconf-utility" title="Permalink to this heading">#</a></h3> <h3>The rnodeconf Utility<a class="headerlink" href="#the-rnodeconf-utility" title="Permalink to this heading">#</a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">rnodeconf</span></code> utility allows you to inspect and configure existing <a class="reference internal" href="hardware.html#rnode-main"><span class="std std-ref">RNodes</span></a>, and <p>The <code class="docutils literal notranslate"><span class="pre">rnodeconf</span></code> utility allows you to inspect and configure existing <a class="reference internal" href="hardware.html#rnode-main"><span class="std std-ref">RNodes</span></a>, and
to create and provision new <a class="reference internal" href="hardware.html#rnode-main"><span class="std std-ref">RNodes</span></a> from any supported hardware devices.</p> to create and provision new <a class="reference internal" href="hardware.html#rnode-main"><span class="std std-ref">RNodes</span></a> from any supported hardware devices.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnodeconf [-h] [-i] [-a] [-u] [-U] [--fw-version version] [--nocheck] [-C] [-N] [-T] [-b] [-B] [-p] [--freq Hz] [--bw Hz] [--txp dBm] [--sf factor] [--cr rate] [--eeprom-backup] [--eeprom-dump] [--eeprom-wipe] [--version] [port] <p><strong>All Command-Line Options</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnodeconf.py [-h] [-i] [-a] [-u] [-U] [--fw-version version] [--nocheck] [-e]
[-E] [-C] [--baud-flash baud_flash] [-N] [-T] [-b] [-B] [-p] [-D i]
[--freq Hz] [--bw Hz] [--txp dBm] [--sf factor] [--cr rate]
[--eeprom-backup] [--eeprom-dump] [--eeprom-wipe] [-P]
[--trust-key hexbytes] [--version] [port]
RNode Configuration and firmware utility. This program allows you to change various settings and startup modes of RNode. It can also install, flash and update the firmware on supported devices. RNode Configuration and firmware utility. This program allows you to change various
settings and startup modes of RNode. It can also install, flash and update the firmware
on supported devices.
positional arguments: positional arguments:
port serial port where RNode is attached port serial port where RNode is attached
@ -704,11 +764,14 @@ options:
-e, --extract Extract firmware from connected RNode for later use -e, --extract Extract firmware from connected RNode for later use
-E, --use-extracted Use the extracted firmware for autoinstallation or update -E, --use-extracted Use the extracted firmware for autoinstallation or update
-C, --clear-cache Clear locally cached firmware files -C, --clear-cache Clear locally cached firmware files
--baud-flash baud_flash
Set specific baud rate when flashing device. Default is 921600
-N, --normal Switch device to normal mode -N, --normal Switch device to normal mode
-T, --tnc Switch device to TNC mode -T, --tnc Switch device to TNC mode
-b, --bluetooth-on Turn device bluetooth on -b, --bluetooth-on Turn device bluetooth on
-B, --bluetooth-off Turn device bluetooth off -B, --bluetooth-off Turn device bluetooth off
-p, --bluetooth-pair Put device into bluetooth pairing mode -p, --bluetooth-pair Put device into bluetooth pairing mode
-D i, --display i Set display intensity (0-255)
--freq Hz Frequency in Hz for TNC mode --freq Hz Frequency in Hz for TNC mode
--bw Hz Bandwidth in Hz for TNC mode --bw Hz Bandwidth in Hz for TNC mode
--txp dBm TX power in dBm for TNC mode --txp dBm TX power in dBm for TNC mode
@ -717,6 +780,8 @@ options:
--eeprom-backup Backup EEPROM to file --eeprom-backup Backup EEPROM to file
--eeprom-dump Dump EEPROM to console --eeprom-dump Dump EEPROM to console
--eeprom-wipe Unlock and wipe EEPROM --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 --version Print program version and exit
</pre></div> </pre></div>
</div> </div>

251
docs/source/using.rst
View File

@ -179,28 +179,34 @@ When ``rnsd`` is running, it will keep all configured interfaces open, handle tr
it is enabled, and allow any other programs to immediately utilise the it is enabled, and allow any other programs to immediately utilise the
Reticulum network it is configured for. Reticulum network it is configured for.
You can even run multiple instances of rnsd with different configurations on You can even run multiple instances of ``rnsd`` with different configurations on
the same system. the same system.
.. code:: text **Usage Examples**
# Install Reticulum Run ``rnsd``:
pip3 install rns
# Run rnsd
rnsd
.. code:: text .. code:: text
usage: rnsd [-h] [--config CONFIG] [-v] [-q] [--version] $ rnsd
[2023-08-18 17:59:56] [Notice] Started rnsd version 0.5.8
**All Command-Line Options**
.. code:: text
usage: rnsd.py [-h] [--config CONFIG] [-v] [-q] [-s] [--exampleconfig] [--version]
Reticulum Network Stack Daemon Reticulum Network Stack Daemon
optional arguments: options:
-h, --help show this help message and exit -h, --help show this help message and exit
--config CONFIG path to alternative Reticulum config directory --config CONFIG path to alternative Reticulum config directory
-v, --verbose -v, --verbose
-q, --quiet -q, --quiet
-s, --service rnsd is running as a service and should log to file
--exampleconfig print verbose configuration example to stdout and exit
--version show program's version number and exit --version show program's version number and exit
You can easily add ``rnsd`` as an always-on service by :ref:`configuring a service<using-systemd>`. You can easily add ``rnsd`` as an always-on service by :ref:`configuring a service<using-systemd>`.
@ -211,12 +217,14 @@ The rnstatus Utility
Using the ``rnstatus`` utility, you can view the status of configured Reticulum Using the ``rnstatus`` utility, you can view the status of configured Reticulum
interfaces, similar to the ``ifconfig`` program. interfaces, similar to the ``ifconfig`` program.
**Usage Examples**
Run ``rnstatus``:
.. code:: text .. code:: text
# Run rnstatus $ rnstatus
rnstatus
# Example output
Shared Instance[37428] Shared Instance[37428]
Status : Up Status : Up
Serving : 1 program Serving : 1 program
@ -249,17 +257,39 @@ interfaces, similar to the ``ifconfig`` program.
Reticulum Transport Instance <5245a8efe1788c6a1cd36144a270e13b> running Reticulum Transport Instance <5245a8efe1788c6a1cd36144a270e13b> running
Filter output to only show some interfaces:
.. code:: text .. code:: text
usage: rnstatus [-h] [--config CONFIG] [--version] [-a] [-v] $ rnstatus rnode
RNodeInterface[RNode UHF]
Status : Up
Mode : Access Point
Rate : 1.30 kbps
Access : 64-bit IFAC by <…e702c42ba8>
Traffic : 8.49 KB↑
9.23 KB↓
Reticulum Transport Instance <5245a8efe1788c6a1cd36144a270e13b> running
**All Command-Line Options**
.. code:: text
usage: rnstatus.py [-h] [--config CONFIG] [--version] [-a] [-j] [-v] [filter]
Reticulum Network Stack Status Reticulum Network Stack Status
optional arguments: positional arguments:
filter only display interfaces with names including filter
options:
-h, --help show this help message and exit -h, --help show this help message and exit
--config CONFIG path to alternative Reticulum config directory --config CONFIG path to alternative Reticulum config directory
--version show program's version number and exit --version show program's version number and exit
-a, --all show all interfaces -a, --all show all interfaces
-j, --json output in JSON format
-v, --verbose -v, --verbose
@ -268,42 +298,67 @@ The rnid Utility
With the ``rnid`` utility, you can generate, manage and view Reticulum Identities. With the ``rnid`` utility, you can generate, manage and view Reticulum Identities.
The program can also calculate Destination hashes, and perform encryption and The program can also calculate Destination hashes, and perform encryption and
decryption of files. Using ``rnid``, it is possible to asymmetrically encrypt decryption of files.
files and information for any destination hash, and also to create and verify
cryptographic signatures. Using ``rnid``, it is possible to asymmetrically encrypt files and information for
any Reticulum destination hash, and also to create and verify cryptographic signatures.
**Usage Examples**
Generate a new Identity:
.. code:: text .. code:: text
# Generate a new Identity $ rnid -g ./new_identity
rnid -g ./new_identity
# Display Identity key information Display Identity key information:
rnid -i ./new_identity -p
.. code:: text
$ rnid -i ./new_identity -p
Loaded Identity <984b74a3f768bef236af4371e6f248cd> from new_id Loaded Identity <984b74a3f768bef236af4371e6f248cd> from new_id
Public Key : 0f4259fef4521ab75a3409e353fe9073eb10783b4912a6a9937c57bf44a62c1e Public Key : 0f4259fef4521ab75a3409e353fe9073eb10783b4912a6a9937c57bf44a62c1e
Private Key : Hidden Private Key : Hidden
# Encrypt a file for an LXMF user Encrypt a file for an LXMF user:
rnid -i 8dd57a738226809646089335a6b03695 -e my_file.txt
.. code:: text
$ rnid -i 8dd57a738226809646089335a6b03695 -e my_file.txt
Recalled Identity <bc7291552be7a58f361522990465165c> for destination <8dd57a738226809646089335a6b03695> Recalled Identity <bc7291552be7a58f361522990465165c> for destination <8dd57a738226809646089335a6b03695>
Encrypting my_file.txt Encrypting my_file.txt
File my_file.txt encrypted for <bc7291552be7a58f361522990465165c> to my_file.txt.rfe File my_file.txt encrypted for <bc7291552be7a58f361522990465165c> to my_file.txt.rfe
# If the Identity for the destination is not already known, If the Identity for the destination is not already known, you can fetch it from the network by using the ``-R`` command-line option:
# you can fetch it from the network by using the -R option
rnid -R -i 30602def3b3506a28ed33db6f60cc6c9 -e my_file.txt .. code:: text
$ rnid -R -i 30602def3b3506a28ed33db6f60cc6c9 -e my_file.txt
Requesting unknown Identity for <30602def3b3506a28ed33db6f60cc6c9>... Requesting unknown Identity for <30602def3b3506a28ed33db6f60cc6c9>...
Received Identity <2b489d06eaf7c543808c76a5332a447d> for destination <30602def3b3506a28ed33db6f60cc6c9> from the network Received Identity <2b489d06eaf7c543808c76a5332a447d> for destination <30602def3b3506a28ed33db6f60cc6c9> from the network
Encrypting my_file.txt Encrypting my_file.txt
File my_file.txt encrypted for <2b489d06eaf7c543808c76a5332a447d> to my_file.txt.rfe File my_file.txt encrypted for <2b489d06eaf7c543808c76a5332a447d> to my_file.txt.rfe
Decrypt a file using the Reticulum Identity it was encrypted for:
.. code:: text .. code:: text
usage: rnid [-h] [--config path] [-i identity] [-g path] [-v] [-q] [-a aspects] [-H aspects] [-e path] [-d path] [-s path] [-V path] [-r path] [-w path] [-f] [-R] [-t seconds] [-p] [-P] $ rnid -i ./my_identity -d my_file.txt.rfe
[--version]
Loaded Identity <2225fdeecaf6e2db4556c3c2d7637294> from ./my_identity
Decrypting ./my_file.txt.rfe...
File ./my_file.txt.rfe decrypted with <2225fdeecaf6e2db4556c3c2d7637294> to ./my_file.txt
**All Command-Line Options**
.. code:: text
usage: rnid.py [-h] [--config path] [-i identity] [-g path] [-v] [-q] [-a aspects]
[-H aspects] [-e path] [-d path] [-s path] [-V path] [-r path] [-w path]
[-f] [-R] [-t seconds] [-p] [-P] [--version]
Reticulum Identity & Encryption Utility Reticulum Identity & Encryption Utility
@ -344,24 +399,29 @@ The rnpath Utility
With the ``rnpath`` utility, you can look up and view paths for With the ``rnpath`` utility, you can look up and view paths for
destinations on the Reticulum network. destinations on the Reticulum network.
**Usage Examples**
Resolve path to a destination:
.. code:: text .. code:: text
# Run rnpath $ rnpath c89b4da064bf66d280f0e4d8abfd9806
rnpath c89b4da064bf66d280f0e4d8abfd9806
# Example output
Path found, destination <c89b4da064bf66d280f0e4d8abfd9806> is 4 hops away via <f53a1c4278e0726bb73fcc623d6ce763> on TCPInterface[Testnet/dublin.connect.reticulum.network:4965] Path found, destination <c89b4da064bf66d280f0e4d8abfd9806> is 4 hops away via <f53a1c4278e0726bb73fcc623d6ce763> on TCPInterface[Testnet/dublin.connect.reticulum.network:4965]
**All Command-Line Options**
.. code:: text .. code:: text
usage: rnpath [-h] [--config CONFIG] [--version] [-t] [-r] [-d] [-D] [-w seconds] [-v] [destination] usage: rnpath.py [-h] [--config CONFIG] [--version] [-t] [-r] [-d] [-D]
[-w seconds] [-v] [destination]
Reticulum Path Discovery Utility Reticulum Path Discovery Utility
positional arguments: positional arguments:
destination hexadecimal hash of the destination destination hexadecimal hash of the destination
optional arguments: options:
-h, --help show this help message and exit -h, --help show this help message and exit
--config CONFIG path to alternative Reticulum config directory --config CONFIG path to alternative Reticulum config directory
--version show program's version number and exit --version show program's version number and exit
@ -381,16 +441,20 @@ to the ``ping`` program. Please note that probes will only be answered if the
specified destination is configured to send proofs for received packets. Many specified destination is configured to send proofs for received packets. Many
destinations will not have this option enabled, and will not be probable. destinations will not have this option enabled, and will not be probable.
**Usage Examples**
Probe a destination:
.. code:: text .. code:: text
# Run rnprobe $ rnprobe example_utilities.echo.request 2d03725b327348980d570f739a3a5708
rnprobe example_utilities.echo.request 2d03725b327348980d570f739a3a5708
# Example output
Sent 16 byte probe to <2d03725b327348980d570f739a3a5708> Sent 16 byte probe to <2d03725b327348980d570f739a3a5708>
Valid reply received from <2d03725b327348980d570f739a3a5708> Valid reply received from <2d03725b327348980d570f739a3a5708>
Round-trip time is 38.469 milliseconds over 2 hops Round-trip time is 38.469 milliseconds over 2 hops
**All Command-Line Options**
.. code:: text .. code:: text
usage: rnprobe [-h] [--config CONFIG] [--version] [-v] [full_name] [destination_hash] usage: rnprobe [-h] [--config CONFIG] [--version] [-v] [full_name] [destination_hash]
@ -414,28 +478,39 @@ The rncp Utility
The ``rncp`` utility is a simple file transfer tool. Using it, you can transfer The ``rncp`` utility is a simple file transfer tool. Using it, you can transfer
files through Reticulum. files through Reticulum.
**Usage Examples**
Run rncp on the receiving system, specifying which identities are allowed to send files:
.. code:: text .. code:: text
# Run rncp on the receiving system, specifying which identities $ rncp --listen -a 1726dbad538775b5bf9b0ea25a4079c8 -a c50cc4e4f7838b6c31f60ab9032cbc62
# are allowed to send files
rncp --listen -a 1726dbad538775b5bf9b0ea25a4079c8 -a c50cc4e4f7838b6c31f60ab9032cbc62
# You can also specify allowed identity hashes (one per line) You can also specify allowed identity hashes (one per line) in the file ~/.rncp/allowed_identities
# in the file ~/.rncp/allowed_identities and simply running and simply running the program in listener mode:
# the program in listener mode
rncp --listen
# From another system, copy a file to the receiving system
rncp ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
# Or fetch a file from the remote system
rncp --fetch ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
You can specify as many allowed senders as needed, or completely disable authentication.
.. code:: text .. code:: text
usage: rncp.py [-h] [--config path] [-v] [-q] [-S] [-l] [-f] [-b seconds] [-a allowed_hash] [-n] [-p] [-w seconds] [--version] [file] [destination] $ rncp --listen
From another system, copy a file to the receiving system:
.. code:: text
$ rncp ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
Or fetch a file from the remote system:
.. code:: text
$ rncp --fetch ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
**All Command-Line Options**
.. code:: text
usage: rncp.py [-h] [--config path] [-v] [-q] [-S] [-l] [-f] [-b seconds]
[-a allowed_hash] [-n] [-p] [-w seconds] [--version] [file] [destination]
Reticulum File Transfer Utility Reticulum File Transfer Utility
@ -464,32 +539,43 @@ The rnx Utility
The ``rnx`` utility is a basic remote command execution program. It allows you to The ``rnx`` utility is a basic remote command execution program. It allows you to
execute commands on remote systems over Reticulum, and to view returned command execute commands on remote systems over Reticulum, and to view returned command
output. output. For a fully interactive remote shell solution, be sure to also take a look
at the `rnsh <https://github.com/acehoss/rnsh>`_ program.
**Usage Examples**
Run rnx on the listening system, specifying which identities are allowed to execute commands:
.. code:: text .. code:: text
# Run rnx on the listening system, specifying which identities $ rnx --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
# are allowed to execute commands
rnx --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
# From another system, run a command From another system, run a command on the remote:
rnx 7a55144adf826958a9529a3bcf08b149 "cat /proc/cpuinfo"
# Or enter the interactive mode pseudo-shell
rnx 7a55144adf826958a9529a3bcf08b149 -x
# The default identity file is stored in
# ~/.reticulum/identities/rnx, but you can use
# another one, which will be created if it does
# not already exist
rnx 7a55144adf826958a9529a3bcf08b149 -i /path/to/identity -x
You can specify as many allowed senders as needed, or completely disable authentication.
.. code:: text .. code:: text
usage: rnx [-h] [--config path] [-v] [-q] [-p] [-l] [-i identity] [-x] [-b] [-a allowed_hash] [-n] [-N] [-d] [-m] [-w seconds] [-W seconds] [--stdin STDIN] [--stdout STDOUT] [--stderr STDERR] [--version] $ rnx 7a55144adf826958a9529a3bcf08b149 "cat /proc/cpuinfo"
[destination] [command]
Or enter the interactive mode pseudo-shell:
.. code:: text
$ rnx 7a55144adf826958a9529a3bcf08b149 -x
The default identity file is stored in ``~/.reticulum/identities/rnx``, but you can use
another one, which will be created if it does not already exist
.. code:: text
$ rnx 7a55144adf826958a9529a3bcf08b149 -i /path/to/identity -x
**All Command-Line Options**
.. code:: text
usage: rnx [-h] [--config path] [-v] [-q] [-p] [-l] [-i identity] [-x] [-b] [-n] [-N]
[-d] [-m] [-a allowed_hash] [-w seconds] [-W seconds] [--stdin STDIN]
[--stdout STDOUT] [--stderr STDERR] [--version] [destination] [command]
Reticulum Remote Execution Utility Reticulum Remote Execution Utility
@ -526,11 +612,19 @@ The rnodeconf Utility
The ``rnodeconf`` utility allows you to inspect and configure existing :ref:`RNodes<rnode-main>`, and The ``rnodeconf`` utility allows you to inspect and configure existing :ref:`RNodes<rnode-main>`, and
to create and provision new :ref:`RNodes<rnode-main>` from any supported hardware devices. to create and provision new :ref:`RNodes<rnode-main>` from any supported hardware devices.
**All Command-Line Options**
.. code:: text .. code:: text
usage: rnodeconf [-h] [-i] [-a] [-u] [-U] [--fw-version version] [--nocheck] [-C] [-N] [-T] [-b] [-B] [-p] [--freq Hz] [--bw Hz] [--txp dBm] [--sf factor] [--cr rate] [--eeprom-backup] [--eeprom-dump] [--eeprom-wipe] [--version] [port] usage: rnodeconf.py [-h] [-i] [-a] [-u] [-U] [--fw-version version] [--nocheck] [-e]
[-E] [-C] [--baud-flash baud_flash] [-N] [-T] [-b] [-B] [-p] [-D i]
[--freq Hz] [--bw Hz] [--txp dBm] [--sf factor] [--cr rate]
[--eeprom-backup] [--eeprom-dump] [--eeprom-wipe] [-P]
[--trust-key hexbytes] [--version] [port]
RNode Configuration and firmware utility. This program allows you to change various settings and startup modes of RNode. It can also install, flash and update the firmware on supported devices. RNode Configuration and firmware utility. This program allows you to change various
settings and startup modes of RNode. It can also install, flash and update the firmware
on supported devices.
positional arguments: positional arguments:
port serial port where RNode is attached port serial port where RNode is attached
@ -546,11 +640,14 @@ to create and provision new :ref:`RNodes<rnode-main>` from any supported hardwar
-e, --extract Extract firmware from connected RNode for later use -e, --extract Extract firmware from connected RNode for later use
-E, --use-extracted Use the extracted firmware for autoinstallation or update -E, --use-extracted Use the extracted firmware for autoinstallation or update
-C, --clear-cache Clear locally cached firmware files -C, --clear-cache Clear locally cached firmware files
--baud-flash baud_flash
Set specific baud rate when flashing device. Default is 921600
-N, --normal Switch device to normal mode -N, --normal Switch device to normal mode
-T, --tnc Switch device to TNC mode -T, --tnc Switch device to TNC mode
-b, --bluetooth-on Turn device bluetooth on -b, --bluetooth-on Turn device bluetooth on
-B, --bluetooth-off Turn device bluetooth off -B, --bluetooth-off Turn device bluetooth off
-p, --bluetooth-pair Put device into bluetooth pairing mode -p, --bluetooth-pair Put device into bluetooth pairing mode
-D i, --display i Set display intensity (0-255)
--freq Hz Frequency in Hz for TNC mode --freq Hz Frequency in Hz for TNC mode
--bw Hz Bandwidth in Hz for TNC mode --bw Hz Bandwidth in Hz for TNC mode
--txp dBm TX power in dBm for TNC mode --txp dBm TX power in dBm for TNC mode
@ -559,6 +656,8 @@ to create and provision new :ref:`RNodes<rnode-main>` from any supported hardwar
--eeprom-backup Backup EEPROM to file --eeprom-backup Backup EEPROM to file
--eeprom-dump Dump EEPROM to console --eeprom-dump Dump EEPROM to console
--eeprom-wipe Unlock and wipe EEPROM --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 --version Print program version and exit
For more information on how to create your own RNodes, please read the :ref:`Creating RNodes<rnode-creating>` For more information on how to create your own RNodes, please read the :ref:`Creating RNodes<rnode-creating>`