mirror of
https://github.com/markqvist/Reticulum.git
synced 2026-04-27 22:25:37 +00:00
Added rnsh to documentation
This commit is contained in:
Mark Qvist
parent
32a1cdf494
commit
043a5dc4e7
8 changed files with 785 additions and 4 deletions
|
|
@ -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 : <984b74a3f768bef236af4371e6f248cd>
|
||||
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 & 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 & 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 : <984b74a3f768bef236af4371e6f248cd>
|
||||
|
||||
$ rnsh -l -p
|
||||
|
||||
Identity : <984b74a3f768bef236af4371e6f248cd>
|
||||
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'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
|
||||
</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>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue