Mirror/markqvist___Reticulum
1
0
Fork 0
mirror of https://github.com/markqvist/Reticulum.git synced 2026-04-27 14:20:35 +00:00
Code Issues Projects Releases Packages Wiki Activity

Added rnsh to documentation

Browse source
This commit is contained in:
Mark Qvist 2026-04-27 00:42:15 +02:00
commit 043a5dc4e7
8 changed files with 785 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

7
README.md
View file

@ -98,12 +98,12 @@ If you want to quickly get an idea of what Reticulum can do, take a look at the
[Programs Using Reticulum](https://reticulum.network/manual/software.html)
section of the manual, or the following resources:
- You can use the [rnsh](https://github.com/acehoss/rnsh) program to establish remote shell sessions over Reticulum.
- [LXMF](https://github.com/markqvist/lxmf) is a distributed, delay and disruption tolerant message transfer protocol built on Reticulum
- The [LXST](https://github.com/markqvist/lxst) protocol and framework provides real-time audio and signals transport over Reticulum. It includes primitives and utilities for building voice-based applications and hardware devices, such as the `rnphone` program, that can be used to build hardware telephones.
- For an off-grid, encrypted and resilient mesh communications platform, see [Nomad Network](https://github.com/markqvist/NomadNet)
- The Android, Linux, macOS and Windows app [Sideband](https://github.com/markqvist/Sideband) has a graphical interface and many advanced features, such as file transfers, image and voice messages, real-time voice calls, a distributed telemetry system, mapping capabilities and full plugin extensibility.
- [MeshChatX](https://git.quad4.io/RNS-Things/MeshChatX) is a full-featured LXMF client with many built-in tools and functionalities, that also supports image and voice messages, file transfers and voice calls. It also includes a built-in page browser for browsing Nomad Network nodes.
- You can use the included [rnsh](https://reticulum.network/manual/using.html#the-rnsh-utility) program to establish remote shell sessions over Reticulum.
## Where can Reticulum be used?
Over practically any medium that can support at least a half-duplex channel
@ -184,7 +184,8 @@ section of the [Reticulum Manual](https://markqvist.github.io/Reticulum/manual/)
- A diagnostics tool called `rnprobe` for checking connectivity to destinations
- A simple file transfer program called `rncp` making it easy to transfer files between systems
- The identity management and encryption utility `rnid` let's you manage Identities and encrypt/decrypt files
- The remote command execution program `rnx` let's you run commands and programs and retrieve output from remote systems
- The `rnsh` program allows you to establish fully interactive shell session with remote systems
- The remote command execution program `rnx` let's you run simple commands and programs and retrieve output from remote systems
- The `rngit` program provides a full multi-repository Git node for serving repositories over Reticulum
- The included `git-remote-rns` helper allows you to interact with Git repositories over Reticulum
@ -276,7 +277,7 @@ to find interface definitions for initial connectivity to the global distributed
***Important!** Historically, a developer-targeted testnet was made available by the Reticulum project itself. As the amount of global Reticulum nodes and entrypoints have grown to a substantial quantity, this public testnet, including the Amsterdam Testnet entrypoint, has now been decommissioned. If your still have instances that relied on this entrypoint for connectivity, transition to using the distributed backbone instead. Reticulum now includes a full on-network interface discovery and connectivity bootstrapping system. Read the [Bootstrapping Connectivity](https://reticulum.network/manual/gettingstartedfast.html#bootstrapping-connectivity) section of the manual for pointers.*
## Support Reticulum
You can help support the continued development of open, free and private communications systems by donating via one of the following channels:
For this to be possible, I need your help. Please support the continued development of open, free and private communications systems by donating via one of the following channels:
- Monero:
```

BIN
docs/Reticulum Manual.epub
View file

Binary file not shown.

BIN
docs/Reticulum Manual.pdf
View file

Binary file not shown.

276
docs/manual/_sources/using.rst.txt
View file

@ -853,6 +853,282 @@ another one, which will be created if it does not already exist
--version show program's version number and exit
The rnsh Utility
================
The ``rnsh`` utility provides a fully interactive remote shell over Reticulum.
It allows you to establish encrypted, authenticated shell sessions on remote
systems, complete with terminal emulation, pipe support, and window resizing.
While the ``rnx`` utility is useful for simple remote command execution and
retrieving output, ``rnsh`` provides a complete interactive terminal experience,
making it ideal for remote administration and management tasks that require
real-time interaction, just like SSH does for IP networks.
``rnsh`` operates in two modes: a *listener* mode that accepts incoming
connections, and an *initiator* mode that connects to a remote listener. Both
sides authenticate using Reticulum Identities, ensuring that only authorised
peers can establish sessions.
.. note::
``rnsh`` 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.
**Usage Examples**
Start ``rnsh`` in listener mode, accepting connections from specific identities:
.. code:: text
$ rnsh -l -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
You can also specify allowed identity hashes (one per line) in the file
``~/.rnsh/allowed_identities`` or ``~/.config/rnsh/allowed_identities``, and
simply run the program in listener mode:
.. code:: text
$ rnsh -l
Connect to a remote listener from another system:
.. code:: text
$ rnsh 7a55144adf826958a9529a3bcf08b149
Specify a command to run on the remote system, separating ``rnsh`` options from
the remote command with ``--``:
.. code:: text
$ rnsh 7a55144adf826958a9529a3bcf08b149 -- top
Set a default command for the listener, in case the initiator does not supply
one, or when remote command execution is disabled:
.. code:: text
$ rnsh -l -- /bin/bash --login
Use the ``-m`` flag to mirror the exit code of the remote process:
.. code:: text
$ rnsh -m 7a55144adf826958a9529a3bcf08b149 -- /usr/local/bin/check-status
Use the ``-p`` flag to display the identity and destination hash for a listener:
.. code:: text
$ rnsh -l -p
Identity : <984b74a3f768bef236af4371e6f248cd>
Listening on : 7a55144adf826958a9529a3bcf08b149
Use a specific identity file rather than the default:
.. code:: text
$ rnsh -l -i /path/to/identity
Announce the listener destination on startup, and periodically:
.. code:: text
$ rnsh -l -b 900
The ``-b`` option specifies the announce period in seconds. Use ``0`` to
announce only once at startup.
**Authentication & Authorisation**
By default, ``rnsh`` requires that connecting initiators identify themselves
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
``-a`` option, and can be used multiple times:
.. code:: text
$ rnsh -l -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
You can also maintain a list of allowed identity hashes in the file
``~/.rnsh/allowed_identities`` or ``~/.config/rnsh/allowed_identities``,
with one hex hash per line. This file is reloaded every time a new connection
is received, so changes take effect immediately without restarting ``rnsh``.
If you want to accept connections from any identity (for testing or in fully
trusted environments), you can disable authentication with the ``-n`` option:
.. code:: text
$ rnsh -l -n
.. warning::
Disabling authentication with ``-n`` means that **any** Reticulum peer that
can reach your listener will be able to execute commands on your system. Only
use this option if you *really* know what you're doing.
**Remote Command Control**
When running in listener mode, ``rnsh`` allows you to control how remote
commands are handled:
- 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.
- Use ``-C`` (``--no-remote-command``) to disable execution of commands received
from the initiator. Only the listener's default command (or the command
specified after ``--``) will be executed:
.. code:: text
$ rnsh -l -C -- /usr/local/bin/safe-script
- Use ``-A`` (``--remote-command-as-args``) to append the initiator's command
to the listener's default command instead of replacing it. This can be useful
for restricting the remote to a specific program while still allowing the
initiator to pass arguments:
.. code:: text
$ rnsh -l -A -- /usr/bin/top
**Service Names**
When running in listener mode, ``rnsh`` uses a service name to differentiate
between multiple listener instances that may share the same identity. By
default, the service name is ``default``. You can specify a different service
name with the ``-s`` option:
.. code:: text
$ rnsh -l -s monitoring
This allows you to run multiple listeners on the same node, each with a
different service name and purpose.
**Initiator Options**
When connecting to a remote listener, several options are available:
- Use ``-N`` (``--no-id``) to disable sending your identity to the remote
listener. Note that the listener must have authentication disabled (``-n``)
for the connection to succeed in this case.
- Use ``-m`` (``--mirror``) to make the initiator return with the exit code of
the remote process, rather than always returning ``0``.
- Use ``-w`` (``--timeout``) to specify the connection and request timeout in
seconds. By default, the timeout matches the Reticulum path request timeout.
**Identity & Destination**
The default identity file for ``rnsh`` is stored at
``~/.reticulum/identities/rnsh``, but you can specify a different one with the
``-i`` option, which will be created if it does not already exist:
.. code:: text
$ rnsh -l -i /path/to/identity
To display the identity and destination information for a listener, use the
``-p`` option. When combined with ``-l``, both the identity and the listening
destination hash are displayed:
.. code:: text
$ rnsh -p
Identity : <984b74a3f768bef236af4371e6f248cd>
$ rnsh -l -p
Identity : <984b74a3f768bef236af4371e6f248cd>
Listening on : 7a55144adf826958a9529a3bcf08b149
**Verbosity**
Like other Reticulum utilities, ``rnsh`` supports the ``-v`` and ``-q`` flags
to increase or decrease logging verbosity. Multiple flags can be specified to
further adjust the log level. The default log level is ``INFO`` for listeners
and ``ERROR`` for initiators.
.. code:: text
$ rnsh -l -vv # Listener with debug-level output
$ rnsh -q 7a55144adf826958a9529a3bcf08b149 # Quiet initiator
By default, all log output is routed to ``~/.rnsh/logfile`` for initiators.
**Escape Sequences**
During an active ``rnsh`` session, the following escape sequences are
available. These are only recognised immediately after a newline character:
- ``~~`` - Send a literal tilde character
- ``~.`` - Terminate the session and exit immediately
- ``~L`` - Toggle line-interactive mode
- ``~?`` - Display the escape sequence quick reference
**All Command-Line Options**
.. code:: text
usage: rnsh [-h] [--config CONFIG] [--identity IDENTITY] [-v] [-q] [-p]
[--version] [-l] [-s SERVICE] [-b PERIOD] [-a HASH] [-n] [-A] [-C]
[-N] [-m] [-w SECONDS]
[destination]
Reticulum Remote Shell Utility
positional arguments:
destination hexadecimal hash of the destination to connect to
options:
-h, --help show this help message and exit
--config, -c CONFIG path to alternative Reticulum config directory
--identity, -i IDENTITY
path to identity file to use
-v, --verbose increase verbosity
-q, --quiet decrease verbosity
-p, --print-identity print identity and destination info and exit
--version show program's version number and exit
-l, --listen listen (server) mode; any command specified after --
will be used as the default command when the initiator
does not provide one or when remote command execution
is disabled; if no command is specified, the default
shell of the user running rnsh will be used
-s, --service SERVICE
service name for identity file if not the default
-b, --announce PERIOD
announce on startup and every PERIOD seconds; specify
0 to announce on startup only
-a, --allowed HASH allow this identity to connect (may be specified
multiple times); allowed identities can also be
specified in ~/.rnsh/allowed_identities or
~/.config/rnsh/allowed_identities, one hash per line
-n, --no-auth disable authentication (allow any identity to connect)
-A, --remote-command-as-args
concatenate remote command to the argument list of the
default program or shell
-C, --no-remote-command
disable executing command lines received from the
remote initiator
-N, --no-id disable identity announcement on connect
-m, --mirror return with the exit code of the remote process
-w, --timeout SECONDS
connect and request timeout in seconds
When specifying a command to execute, separate rnsh options from the command
and its arguments with --. For example:
rnsh -l -- /bin/bash --login
rnsh <destination> -- ls -la /tmp
The rnodeconf Utility
=====================

1
docs/manual/index.html
View file

@ -411,6 +411,7 @@ to participate in the development of Reticulum itself.</p>
<li class="toctree-l3"><a class="reference internal" href="using.html#the-rncp-utility">The rncp Utility</a></li>
<li class="toctree-l3"><a class="reference internal" href="using.html#the-rngit-utility">The rngit Utility</a></li>
<li class="toctree-l3"><a class="reference internal" href="using.html#the-rnx-utility">The rnx Utility</a></li>
<li class="toctree-l3"><a class="reference internal" href="using.html#the-rnsh-utility">The rnsh Utility</a></li>
<li class="toctree-l3"><a class="reference internal" href="using.html#the-rnodeconf-utility">The rnodeconf Utility</a></li>
</ul>
</li>

2
docs/manual/searchindex.js
View file

File diff suppressed because one or more lines are too long

227
docs/manual/using.html
View file

@ -984,6 +984,232 @@ optional arguments:
</pre></div>
</div>
</section>
<section id="the-rnsh-utility">
<h3>The rnsh Utility<a class="headerlink" href="#the-rnsh-utility" title="Link to this heading"></a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> utility provides a fully interactive remote shell over Reticulum.
It allows you to establish encrypted, authenticated shell sessions on remote
systems, complete with terminal emulation, pipe support, and window resizing.</p>
<p>While the <code class="docutils literal notranslate"><span class="pre">rnx</span></code> utility is useful for simple remote command execution and
retrieving output, <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> provides a complete interactive terminal experience,
making it ideal for remote administration and management tasks that require
real-time interaction, just like SSH does for IP networks.</p>
<p><code class="docutils literal notranslate"><span class="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>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p><code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> in listener mode, accepting connections from specific identities:</p>
<div class="highlight-text notranslate"><div class="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
<code class="docutils literal notranslate"><span class="pre">~/.rnsh/allowed_identities</span></code> or <code class="docutils literal notranslate"><span class="pre">~/.config/rnsh/allowed_identities</span></code>, and
simply run the program in listener mode:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l
</pre></div>
</div>
<p>Connect to a remote listener from another system:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh 7a55144adf826958a9529a3bcf08b149
</pre></div>
</div>
<p>Specify a command to run on the remote system, separating <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> options from
the remote command with <code class="docutils literal notranslate"><span class="pre">--</span></code>:</p>
<div class="highlight-text notranslate"><div class="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>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l -- /bin/bash --login
</pre></div>
</div>
<p>Use the <code class="docutils literal notranslate"><span class="pre">-m</span></code> flag to mirror the exit code of the remote process:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -m 7a55144adf826958a9529a3bcf08b149 -- /usr/local/bin/check-status
</pre></div>
</div>
<p>Use the <code class="docutils literal notranslate"><span class="pre">-p</span></code> flag to display the identity and destination hash for a listener:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l -p
Identity : &lt;984b74a3f768bef236af4371e6f248cd&gt;
Listening on : 7a55144adf826958a9529a3bcf08b149
</pre></div>
</div>
<p>Use a specific identity file rather than the default:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l -i /path/to/identity
</pre></div>
</div>
<p>Announce the listener destination on startup, and periodically:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l -b 900
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">-b</span></code> option specifies the announce period in seconds. Use <code class="docutils literal notranslate"><span class="pre">0</span></code> to
announce only once at startup.</p>
<p><strong>Authentication &amp; Authorisation</strong></p>
<p>By default, <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> requires that connecting initiators identify themselves
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
<code class="docutils literal notranslate"><span class="pre">-a</span></code> option, and can be used multiple times:</p>
<div class="highlight-text notranslate"><div class="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
<code class="docutils literal notranslate"><span class="pre">~/.rnsh/allowed_identities</span></code> or <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">-n</span></code> option:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l -n
</pre></div>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Disabling authentication with <code class="docutils literal notranslate"><span class="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, <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> allows you to control how remote
commands are handled:</p>
<ul class="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 <code class="docutils literal notranslate"><span class="pre">-C</span></code> (<code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">--</span></code>) will be executed:</p></li>
</ul>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l -C -- /usr/local/bin/safe-script
</pre></div>
</div>
<ul class="simple">
<li><p>Use <code class="docutils literal notranslate"><span class="pre">-A</span></code> (<code class="docutils literal notranslate"><span class="pre">--remote-command-as-args</span></code>) to append the initiator’s command
to the listener’s default command instead of replacing it. This can be useful
for restricting the remote to a specific program while still allowing the
initiator to pass arguments:</p></li>
</ul>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l -A -- /usr/bin/top
</pre></div>
</div>
<p><strong>Service Names</strong></p>
<p>When running in listener mode, <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> uses a service name to differentiate
between multiple listener instances that may share the same identity. By
default, the service name is <code class="docutils literal notranslate"><span class="pre">default</span></code>. You can specify a different service
name with the <code class="docutils literal notranslate"><span class="pre">-s</span></code> option:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l -s monitoring
</pre></div>
</div>
<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>
<ul class="simple">
<li><p>Use <code class="docutils literal notranslate"><span class="pre">-N</span></code> (<code class="docutils literal notranslate"><span class="pre">--no-id</span></code>) to disable sending your identity to the remote
listener. Note that the listener must have authentication disabled (<code class="docutils literal notranslate"><span class="pre">-n</span></code>)
for the connection to succeed in this case.</p></li>
<li><p>Use <code class="docutils literal notranslate"><span class="pre">-m</span></code> (<code class="docutils literal notranslate"><span class="pre">--mirror</span></code>) to make the initiator return with the exit code of
the remote process, rather than always returning <code class="docutils literal notranslate"><span class="pre">0</span></code>.</p></li>
<li><p>Use <code class="docutils literal notranslate"><span class="pre">-w</span></code> (<code class="docutils literal notranslate"><span class="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 &amp; Destination</strong></p>
<p>The default identity file for <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> is stored at
<code class="docutils literal notranslate"><span class="pre">~/.reticulum/identities/rnsh</span></code>, but you can specify a different one with the
<code class="docutils literal notranslate"><span class="pre">-i</span></code> option, which will be created if it does not already exist:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l -i /path/to/identity
</pre></div>
</div>
<p>To display the identity and destination information for a listener, use the
<code class="docutils literal notranslate"><span class="pre">-p</span></code> option. When combined with <code class="docutils literal notranslate"><span class="pre">-l</span></code>, both the identity and the listening
destination hash are displayed:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -p
Identity : &lt;984b74a3f768bef236af4371e6f248cd&gt;
$ rnsh -l -p
Identity : &lt;984b74a3f768bef236af4371e6f248cd&gt;
Listening on : 7a55144adf826958a9529a3bcf08b149
</pre></div>
</div>
<p><strong>Verbosity</strong></p>
<p>Like other Reticulum utilities, <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> supports the <code class="docutils literal notranslate"><span class="pre">-v</span></code> and <code class="docutils literal notranslate"><span class="pre">-q</span></code> flags
to increase or decrease logging verbosity. Multiple flags can be specified to
further adjust the log level. The default log level is <code class="docutils literal notranslate"><span class="pre">INFO</span></code> for listeners
and <code class="docutils literal notranslate"><span class="pre">ERROR</span></code> for initiators.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsh -l -vv # Listener with debug-level output
$ rnsh -q 7a55144adf826958a9529a3bcf08b149 # Quiet initiator
</pre></div>
</div>
<p>By default, all log output is routed to <code class="docutils literal notranslate"><span class="pre">~/.rnsh/logfile</span></code> for initiators.</p>
<p><strong>Escape Sequences</strong></p>
<p>During an active <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> session, the following escape sequences are
available. These are only recognised immediately after a newline character:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">~~</span></code> - Send a literal tilde character</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">~.</span></code> - Terminate the session and exit immediately</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">~L</span></code> - Toggle line-interactive mode</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">~?</span></code> - Display the escape sequence quick reference</p></li>
</ul>
<p><strong>All Command-Line Options</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnsh [-h] [--config CONFIG] [--identity IDENTITY] [-v] [-q] [-p]
[--version] [-l] [-s SERVICE] [-b PERIOD] [-a HASH] [-n] [-A] [-C]
[-N] [-m] [-w SECONDS]
[destination]
Reticulum Remote Shell Utility
positional arguments:
destination hexadecimal hash of the destination to connect to
options:
-h, --help show this help message and exit
--config, -c CONFIG path to alternative Reticulum config directory
--identity, -i IDENTITY
path to identity file to use
-v, --verbose increase verbosity
-q, --quiet decrease verbosity
-p, --print-identity print identity and destination info and exit
--version show program&#39;s version number and exit
-l, --listen listen (server) mode; any command specified after --
will be used as the default command when the initiator
does not provide one or when remote command execution
is disabled; if no command is specified, the default
shell of the user running rnsh will be used
-s, --service SERVICE
service name for identity file if not the default
-b, --announce PERIOD
announce on startup and every PERIOD seconds; specify
0 to announce on startup only
-a, --allowed HASH allow this identity to connect (may be specified
multiple times); allowed identities can also be
specified in ~/.rnsh/allowed_identities or
~/.config/rnsh/allowed_identities, one hash per line
-n, --no-auth disable authentication (allow any identity to connect)
-A, --remote-command-as-args
concatenate remote command to the argument list of the
default program or shell
-C, --no-remote-command
disable executing command lines received from the
remote initiator
-N, --no-id disable identity announcement on connect
-m, --mirror return with the exit code of the remote process
-w, --timeout SECONDS
connect and request timeout in seconds
When specifying a command to execute, separate rnsh options from the command
and its arguments with --. For example:
rnsh -l -- /bin/bash --login
rnsh &lt;destination&gt; -- ls -la /tmp
</pre></div>
</div>
</section>
<section id="the-rnodeconf-utility">
<h3>The rnodeconf Utility<a class="headerlink" href="#the-rnodeconf-utility" title="Link 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
@ -1440,6 +1666,7 @@ systemctl --user enable rnsd.service
<li><a class="reference internal" href="#the-rncp-utility">The rncp Utility</a></li>
<li><a class="reference internal" href="#the-rngit-utility">The rngit Utility</a></li>
<li><a class="reference internal" href="#the-rnx-utility">The rnx Utility</a></li>
<li><a class="reference internal" href="#the-rnsh-utility">The rnsh Utility</a></li>
<li><a class="reference internal" href="#the-rnodeconf-utility">The rnodeconf Utility</a></li>
</ul>
</li>

276
docs/source/using.rst
View file

@ -853,6 +853,282 @@ another one, which will be created if it does not already exist
--version show program's version number and exit
The rnsh Utility
================
The ``rnsh`` utility provides a fully interactive remote shell over Reticulum.
It allows you to establish encrypted, authenticated shell sessions on remote
systems, complete with terminal emulation, pipe support, and window resizing.
While the ``rnx`` utility is useful for simple remote command execution and
retrieving output, ``rnsh`` provides a complete interactive terminal experience,
making it ideal for remote administration and management tasks that require
real-time interaction, just like SSH does for IP networks.
``rnsh`` operates in two modes: a *listener* mode that accepts incoming
connections, and an *initiator* mode that connects to a remote listener. Both
sides authenticate using Reticulum Identities, ensuring that only authorised
peers can establish sessions.
.. note::
``rnsh`` 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.
**Usage Examples**
Start ``rnsh`` in listener mode, accepting connections from specific identities:
.. code:: text
$ rnsh -l -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
You can also specify allowed identity hashes (one per line) in the file
``~/.rnsh/allowed_identities`` or ``~/.config/rnsh/allowed_identities``, and
simply run the program in listener mode:
.. code:: text
$ rnsh -l
Connect to a remote listener from another system:
.. code:: text
$ rnsh 7a55144adf826958a9529a3bcf08b149
Specify a command to run on the remote system, separating ``rnsh`` options from
the remote command with ``--``:
.. code:: text
$ rnsh 7a55144adf826958a9529a3bcf08b149 -- top
Set a default command for the listener, in case the initiator does not supply
one, or when remote command execution is disabled:
.. code:: text
$ rnsh -l -- /bin/bash --login
Use the ``-m`` flag to mirror the exit code of the remote process:
.. code:: text
$ rnsh -m 7a55144adf826958a9529a3bcf08b149 -- /usr/local/bin/check-status
Use the ``-p`` flag to display the identity and destination hash for a listener:
.. code:: text
$ rnsh -l -p
Identity : <984b74a3f768bef236af4371e6f248cd>
Listening on : 7a55144adf826958a9529a3bcf08b149
Use a specific identity file rather than the default:
.. code:: text
$ rnsh -l -i /path/to/identity
Announce the listener destination on startup, and periodically:
.. code:: text
$ rnsh -l -b 900
The ``-b`` option specifies the announce period in seconds. Use ``0`` to
announce only once at startup.
**Authentication & Authorisation**
By default, ``rnsh`` requires that connecting initiators identify themselves
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
``-a`` option, and can be used multiple times:
.. code:: text
$ rnsh -l -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
You can also maintain a list of allowed identity hashes in the file
``~/.rnsh/allowed_identities`` or ``~/.config/rnsh/allowed_identities``,
with one hex hash per line. This file is reloaded every time a new connection
is received, so changes take effect immediately without restarting ``rnsh``.
If you want to accept connections from any identity (for testing or in fully
trusted environments), you can disable authentication with the ``-n`` option:
.. code:: text
$ rnsh -l -n
.. warning::
Disabling authentication with ``-n`` means that **any** Reticulum peer that
can reach your listener will be able to execute commands on your system. Only
use this option if you *really* know what you're doing.
**Remote Command Control**
When running in listener mode, ``rnsh`` allows you to control how remote
commands are handled:
- 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.
- Use ``-C`` (``--no-remote-command``) to disable execution of commands received
from the initiator. Only the listener's default command (or the command
specified after ``--``) will be executed:
.. code:: text
$ rnsh -l -C -- /usr/local/bin/safe-script
- Use ``-A`` (``--remote-command-as-args``) to append the initiator's command
to the listener's default command instead of replacing it. This can be useful
for restricting the remote to a specific program while still allowing the
initiator to pass arguments:
.. code:: text
$ rnsh -l -A -- /usr/bin/top
**Service Names**
When running in listener mode, ``rnsh`` uses a service name to differentiate
between multiple listener instances that may share the same identity. By
default, the service name is ``default``. You can specify a different service
name with the ``-s`` option:
.. code:: text
$ rnsh -l -s monitoring
This allows you to run multiple listeners on the same node, each with a
different service name and purpose.
**Initiator Options**
When connecting to a remote listener, several options are available:
- Use ``-N`` (``--no-id``) to disable sending your identity to the remote
listener. Note that the listener must have authentication disabled (``-n``)
for the connection to succeed in this case.
- Use ``-m`` (``--mirror``) to make the initiator return with the exit code of
the remote process, rather than always returning ``0``.
- Use ``-w`` (``--timeout``) to specify the connection and request timeout in
seconds. By default, the timeout matches the Reticulum path request timeout.
**Identity & Destination**
The default identity file for ``rnsh`` is stored at
``~/.reticulum/identities/rnsh``, but you can specify a different one with the
``-i`` option, which will be created if it does not already exist:
.. code:: text
$ rnsh -l -i /path/to/identity
To display the identity and destination information for a listener, use the
``-p`` option. When combined with ``-l``, both the identity and the listening
destination hash are displayed:
.. code:: text
$ rnsh -p
Identity : <984b74a3f768bef236af4371e6f248cd>
$ rnsh -l -p
Identity : <984b74a3f768bef236af4371e6f248cd>
Listening on : 7a55144adf826958a9529a3bcf08b149
**Verbosity**
Like other Reticulum utilities, ``rnsh`` supports the ``-v`` and ``-q`` flags
to increase or decrease logging verbosity. Multiple flags can be specified to
further adjust the log level. The default log level is ``INFO`` for listeners
and ``ERROR`` for initiators.
.. code:: text
$ rnsh -l -vv # Listener with debug-level output
$ rnsh -q 7a55144adf826958a9529a3bcf08b149 # Quiet initiator
By default, all log output is routed to ``~/.rnsh/logfile`` for initiators.
**Escape Sequences**
During an active ``rnsh`` session, the following escape sequences are
available. These are only recognised immediately after a newline character:
- ``~~`` - Send a literal tilde character
- ``~.`` - Terminate the session and exit immediately
- ``~L`` - Toggle line-interactive mode
- ``~?`` - Display the escape sequence quick reference
**All Command-Line Options**
.. code:: text
usage: rnsh [-h] [--config CONFIG] [--identity IDENTITY] [-v] [-q] [-p]
[--version] [-l] [-s SERVICE] [-b PERIOD] [-a HASH] [-n] [-A] [-C]
[-N] [-m] [-w SECONDS]
[destination]
Reticulum Remote Shell Utility
positional arguments:
destination hexadecimal hash of the destination to connect to
options:
-h, --help show this help message and exit
--config, -c CONFIG path to alternative Reticulum config directory
--identity, -i IDENTITY
path to identity file to use
-v, --verbose increase verbosity
-q, --quiet decrease verbosity
-p, --print-identity print identity and destination info and exit
--version show program's version number and exit
-l, --listen listen (server) mode; any command specified after --
will be used as the default command when the initiator
does not provide one or when remote command execution
is disabled; if no command is specified, the default
shell of the user running rnsh will be used
-s, --service SERVICE
service name for identity file if not the default
-b, --announce PERIOD
announce on startup and every PERIOD seconds; specify
0 to announce on startup only
-a, --allowed HASH allow this identity to connect (may be specified
multiple times); allowed identities can also be
specified in ~/.rnsh/allowed_identities or
~/.config/rnsh/allowed_identities, one hash per line
-n, --no-auth disable authentication (allow any identity to connect)
-A, --remote-command-as-args
concatenate remote command to the argument list of the
default program or shell
-C, --no-remote-command
disable executing command lines received from the
remote initiator
-N, --no-id disable identity announcement on connect
-m, --mirror return with the exit code of the remote process
-w, --timeout SECONDS
connect and request timeout in seconds
When specifying a command to execute, separate rnsh options from the command
and its arguments with --. For example:
rnsh -l -- /bin/bash --login
rnsh <destination> -- ls -la /tmp
The rnodeconf Utility
=====================