Added rnx util to documentation

This commit is contained in:
Mark Qvist 2022-05-24 20:47:45 +02:00
parent 417ac9f8da
commit 3b8490ae9c
8 changed files with 260 additions and 52 deletions

View File

@ -138,6 +138,10 @@ take a look at the :ref:`Interfaces<interfaces-main>` chapter of this manual.
Included Utility Programs
-------------------------
Reticulum includes a range of useful utilities, both for managing your Reticulum
networks, and for carrying out common tasks over Reticulum networks, such as
transferring files to remote systems, and executing commands and programs remotely.
If you often use Reticulum from several different programs, or simply want
Reticulum to stay available all the time, for example if you are hosting
a transport node, you might want to run Reticulum as a separate service that
@ -314,8 +318,8 @@ files through Reticulum.
.. code:: text
# Run rncp on the receiving system, specifying which identities
# are allowed to send files.
rncp --receive --allow 940ea3f9e1037d38758f --allow e28d5aee4317c24a9041
# are allowed to send files
rncp --receive -a 940ea3f9e1037d38758f -a e28d5aee4317c24a9041
# From another system, copy a file to the receiving system
rncp ~/path/to/file.tgz 256320d405d6d525d1e9
@ -324,26 +328,88 @@ You can specify as many allowed senders as needed, or complete disable authentic
.. code:: text
usage: rncp.py [-h] [--config path] [-v] [-q] [-i] [-r] [-b] [-a ALLOW] [-n] [-w seconds] [--version] [file] [destination]
usage: rncp [-h] [--config path] [-v] [-q] [-p] [-r] [-b] [-a allowed_hash] [-n] [-w seconds] [--version] [file] [destination]
Reticulum File Transfer Utility
positional arguments:
file file to be transferred
destination hexadecimal hash of the receiver
file file to be transferred
destination hexadecimal hash of the receiver
optional arguments:
-h, --help show this help message and exit
--config path path to alternative Reticulum config directory
-v, --verbose increase verbosity
-q, --quiet decrease verbosity
-i, --identity print identity and destination info and exit
-r, --receive wait for incoming files
-b, --no-announce don't announce at program start
-a ALLOW, --allow ALLOW accept from this identity
-n, --no-auth accept files from anyone
-w seconds sender timeout before giving up
--version show program's version number and exit
-h, --help show this help message and exit
--config path path to alternative Reticulum config directory
-v, --verbose increase verbosity
-q, --quiet decrease verbosity
-p, --print-identity print identity and destination info and exit
-r, --receive wait for incoming files
-b, --no-announce don't announce at program start
-a allowed_hash accept from this identity
-n, --no-auth accept files from anyone
-w seconds sender timeout before giving up
--version show program's version number and exit
-v, --verbose
The rnx Utility
================
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
output.
.. code:: text
# Run rnx on the listening system, specifying which identities
# are allowed to execute commands
rncp --listen -a 8111c4ff2968ab0c1286 -a 590256654482b4ba4038
# From another system, run a command
rnx ad9a4c9da60089d41c29 "cat /proc/cpuinfo"
# Or enter the interactive mode pseudo-shell
rnx ad9a4c9da60089d41c29 -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 ad9a4c9da60089d41c29 -i /path/to/identity
You can specify as many allowed senders as needed, or complete disable authentication.
.. 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]
[destination] [command]
Reticulum Remote Execution Utility
positional arguments:
destination hexadecimal hash of the listener
command command to be execute
optional arguments:
-h, --help show this help message and exit
--config path path to alternative Reticulum config directory
-v, --verbose increase verbosity
-q, --quiet decrease verbosity
-p, --print-identity print identity and destination info and exit
-l, --listen listen for incoming commands
-i identity path to identity to use
-x, --interactive enter interactive mode
-b, --no-announce don't announce at program start
-a allowed_hash accept from this identity
-n, --noauth accept files from anyone
-N, --noid don't identify to listener
-d, --detailed show detailed result output
-m mirror exit code of remote command
-w seconds connect and request timeout before giving up
-W seconds max result download time
--stdin STDIN pass input to stdin
--stdout STDOUT max size in bytes of returned stdout
--stderr STDERR max size in bytes of returned stderr
--version show program's version number and exit
Improving System Configuration

View File

@ -334,6 +334,8 @@
<li><a href="reference.html#RNS.Destination.set_default_app_data">set_default_app_data() (RNS.Destination method)</a>
</li>
<li><a href="reference.html#RNS.PacketReceipt.set_delivery_callback">set_delivery_callback() (RNS.PacketReceipt method)</a>
</li>
<li><a href="reference.html#RNS.Link.set_link_closed_callback">set_link_closed_callback() (RNS.Link method)</a>
</li>
<li><a href="reference.html#RNS.Destination.set_link_established_callback">set_link_established_callback() (RNS.Destination method)</a>
</li>
@ -346,11 +348,11 @@
<li><a href="reference.html#RNS.Destination.set_proof_requested_callback">set_proof_requested_callback() (RNS.Destination method)</a>
</li>
<li><a href="reference.html#RNS.Destination.set_proof_strategy">set_proof_strategy() (RNS.Destination method)</a>
</li>
<li><a href="reference.html#RNS.Link.set_remote_identified_callback">set_remote_identified_callback() (RNS.Link method)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="reference.html#RNS.Link.set_remote_identified_callback">set_remote_identified_callback() (RNS.Link method)</a>
</li>
<li><a href="reference.html#RNS.Link.set_resource_callback">set_resource_callback() (RNS.Link method)</a>
</li>
<li><a href="reference.html#RNS.Link.set_resource_concluded_callback">set_resource_concluded_callback() (RNS.Link method)</a>

View File

@ -77,6 +77,7 @@ to participate in the development of Reticulum itself.</p>
<li class="toctree-l3"><a class="reference internal" href="using.html#the-rnpath-utility">The rnpath Utility</a></li>
<li class="toctree-l3"><a class="reference internal" href="using.html#the-rnprobe-utility">The rnprobe Utility</a></li>
<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-rnx-utility">The rnx Utility</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="using.html#improving-system-configuration">Improving System Configuration</a><ul>

Binary file not shown.

View File

@ -898,6 +898,18 @@ thus preserved. This method can be used for authentication.</p>
be used if a new link to the same destination is established.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="RNS.Link.set_link_closed_callback">
<span class="sig-name descname"><span class="pre">set_link_closed_callback</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">callback</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Link.set_link_closed_callback" title="Permalink to this definition"></a></dt>
<dd><p>Registers a function to be called when a link has been
torn down.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>callback</strong> A function or method with the signature <em>callback(link)</em> to be called.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="RNS.Link.set_packet_callback">
<span class="sig-name descname"><span class="pre">set_packet_callback</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">callback</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Link.set_packet_callback" title="Permalink to this definition"></a></dt>
@ -1233,7 +1245,7 @@ Transport system of Reticulum.</p>
<dl class="py method">
<dt class="sig sig-object py" id="RNS.Transport.request_path">
<em class="property"><span class="pre">static</span> </em><span class="sig-name descname"><span class="pre">request_path</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">destination_hash</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">on_interface</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Transport.request_path" title="Permalink to this definition"></a></dt>
<em class="property"><span class="pre">static</span> </em><span class="sig-name descname"><span class="pre">request_path</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">destination_hash</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">on_interface</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tag</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">recursive</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Transport.request_path" title="Permalink to this definition"></a></dt>
<dd><p>Requests a path to the destination from the network. If
another reachable peer on the network knows a path, it
will announce it.</p>

File diff suppressed because one or more lines are too long

View File

@ -169,6 +169,9 @@ take a look at the <a class="reference internal" href="interfaces.html#interface
</div>
<div class="section" id="included-utility-programs">
<h2>Included Utility Programs<a class="headerlink" href="#included-utility-programs" title="Permalink to this headline"></a></h2>
<p>Reticulum includes a range of useful utilities, both for managing your Reticulum
networks, and for carrying out common tasks over Reticulum networks, such as
transferring files to remote systems, and executing commands and programs remotely.</p>
<p>If you often use Reticulum from several different programs, or simply want
Reticulum to stay available all the time, for example if you are hosting
a transport node, you might want to run Reticulum as a separate service that
@ -323,34 +326,91 @@ optional arguments:
<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>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rncp on the receiving system, specifying which identities
# are allowed to send files.
rncp --receive --allow 940ea3f9e1037d38758f --allow e28d5aee4317c24a9041
# are allowed to send files
rncp --receive -a 940ea3f9e1037d38758f -a e28d5aee4317c24a9041
# From another system, copy a file to the receiving system
rncp ~/path/to/file.tgz 256320d405d6d525d1e9
</pre></div>
</div>
<p>You can specify as many allowed senders as needed, or complete disable authentication.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rncp.py [-h] [--config path] [-v] [-q] [-i] [-r] [-b] [-a ALLOW] [-n] [-w seconds] [--version] [file] [destination]
<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]
Reticulum File Transfer Utility
positional arguments:
file file to be transferred
destination hexadecimal hash of the receiver
file file to be transferred
destination hexadecimal hash of the receiver
optional arguments:
-h, --help show this help message and exit
--config path path to alternative Reticulum config directory
-v, --verbose increase verbosity
-q, --quiet decrease verbosity
-i, --identity print identity and destination info and exit
-r, --receive wait for incoming files
-b, --no-announce don&#39;t announce at program start
-a ALLOW, --allow ALLOW accept from this identity
-n, --no-auth accept files from anyone
-w seconds sender timeout before giving up
--version show program&#39;s version number and exit
-h, --help show this help message and exit
--config path path to alternative Reticulum config directory
-v, --verbose increase verbosity
-q, --quiet decrease verbosity
-p, --print-identity print identity and destination info and exit
-r, --receive wait for incoming files
-b, --no-announce don&#39;t announce at program start
-a allowed_hash accept from this identity
-n, --no-auth accept files from anyone
-w seconds sender timeout before giving up
--version show program&#39;s version number and exit
-v, --verbose
</pre></div>
</div>
</div>
<div class="section" id="the-rnx-utility">
<h3>The rnx Utility<a class="headerlink" href="#the-rnx-utility" title="Permalink to this headline"></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
execute commands on remote systems over Reticulum, and to view returned command
output.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rnx on the listening system, specifying which identities
# are allowed to execute commands
rncp --listen -a 8111c4ff2968ab0c1286 -a 590256654482b4ba4038
# From another system, run a command
rnx ad9a4c9da60089d41c29 &quot;cat /proc/cpuinfo&quot;
# Or enter the interactive mode pseudo-shell
rnx ad9a4c9da60089d41c29 -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 ad9a4c9da60089d41c29 -i /path/to/identity
</pre></div>
</div>
<p>You can specify as many allowed senders as needed, or complete disable authentication.</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]
[destination] [command]
Reticulum Remote Execution Utility
positional arguments:
destination hexadecimal hash of the listener
command command to be execute
optional arguments:
-h, --help show this help message and exit
--config path path to alternative Reticulum config directory
-v, --verbose increase verbosity
-q, --quiet decrease verbosity
-p, --print-identity print identity and destination info and exit
-l, --listen listen for incoming commands
-i identity path to identity to use
-x, --interactive enter interactive mode
-b, --no-announce don&#39;t announce at program start
-a allowed_hash accept from this identity
-n, --noauth accept files from anyone
-N, --noid don&#39;t identify to listener
-d, --detailed show detailed result output
-m mirror exit code of remote command
-w seconds connect and request timeout before giving up
-W seconds max result download time
--stdin STDIN pass input to stdin
--stdout STDOUT max size in bytes of returned stdout
--stderr STDERR max size in bytes of returned stderr
--version show program&#39;s version number and exit
</pre></div>
</div>
</div>
@ -452,6 +512,7 @@ WantedBy=multi-user.target
<li><a class="reference internal" href="#the-rnpath-utility">The rnpath Utility</a></li>
<li><a class="reference internal" href="#the-rnprobe-utility">The rnprobe Utility</a></li>
<li><a class="reference internal" href="#the-rncp-utility">The rncp Utility</a></li>
<li><a class="reference internal" href="#the-rnx-utility">The rnx Utility</a></li>
</ul>
</li>
<li><a class="reference internal" href="#improving-system-configuration">Improving System Configuration</a><ul>

View File

@ -138,6 +138,10 @@ take a look at the :ref:`Interfaces<interfaces-main>` chapter of this manual.
Included Utility Programs
-------------------------
Reticulum includes a range of useful utilities, both for managing your Reticulum
networks, and for carrying out common tasks over Reticulum networks, such as
transferring files to remote systems, and executing commands and programs remotely.
If you often use Reticulum from several different programs, or simply want
Reticulum to stay available all the time, for example if you are hosting
a transport node, you might want to run Reticulum as a separate service that
@ -314,8 +318,8 @@ files through Reticulum.
.. code:: text
# Run rncp on the receiving system, specifying which identities
# are allowed to send files.
rncp --receive --allow 940ea3f9e1037d38758f --allow e28d5aee4317c24a9041
# are allowed to send files
rncp --receive -a 940ea3f9e1037d38758f -a e28d5aee4317c24a9041
# From another system, copy a file to the receiving system
rncp ~/path/to/file.tgz 256320d405d6d525d1e9
@ -324,26 +328,88 @@ You can specify as many allowed senders as needed, or complete disable authentic
.. code:: text
usage: rncp.py [-h] [--config path] [-v] [-q] [-i] [-r] [-b] [-a ALLOW] [-n] [-w seconds] [--version] [file] [destination]
usage: rncp [-h] [--config path] [-v] [-q] [-p] [-r] [-b] [-a allowed_hash] [-n] [-w seconds] [--version] [file] [destination]
Reticulum File Transfer Utility
positional arguments:
file file to be transferred
destination hexadecimal hash of the receiver
file file to be transferred
destination hexadecimal hash of the receiver
optional arguments:
-h, --help show this help message and exit
--config path path to alternative Reticulum config directory
-v, --verbose increase verbosity
-q, --quiet decrease verbosity
-i, --identity print identity and destination info and exit
-r, --receive wait for incoming files
-b, --no-announce don't announce at program start
-a allowed_hash accept from this identity
-n, --no-auth accept files from anyone
-w seconds sender timeout before giving up
--version show program's version number and exit
-h, --help show this help message and exit
--config path path to alternative Reticulum config directory
-v, --verbose increase verbosity
-q, --quiet decrease verbosity
-p, --print-identity print identity and destination info and exit
-r, --receive wait for incoming files
-b, --no-announce don't announce at program start
-a allowed_hash accept from this identity
-n, --no-auth accept files from anyone
-w seconds sender timeout before giving up
--version show program's version number and exit
-v, --verbose
The rnx Utility
================
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
output.
.. code:: text
# Run rnx on the listening system, specifying which identities
# are allowed to execute commands
rncp --listen -a 8111c4ff2968ab0c1286 -a 590256654482b4ba4038
# From another system, run a command
rnx ad9a4c9da60089d41c29 "cat /proc/cpuinfo"
# Or enter the interactive mode pseudo-shell
rnx ad9a4c9da60089d41c29 -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 ad9a4c9da60089d41c29 -i /path/to/identity
You can specify as many allowed senders as needed, or complete disable authentication.
.. 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]
[destination] [command]
Reticulum Remote Execution Utility
positional arguments:
destination hexadecimal hash of the listener
command command to be execute
optional arguments:
-h, --help show this help message and exit
--config path path to alternative Reticulum config directory
-v, --verbose increase verbosity
-q, --quiet decrease verbosity
-p, --print-identity print identity and destination info and exit
-l, --listen listen for incoming commands
-i identity path to identity to use
-x, --interactive enter interactive mode
-b, --no-announce don't announce at program start
-a allowed_hash accept from this identity
-n, --noauth accept files from anyone
-N, --noid don't identify to listener
-d, --detailed show detailed result output
-m mirror exit code of remote command
-w seconds connect and request timeout before giving up
-W seconds max result download time
--stdin STDIN pass input to stdin
--stdout STDOUT max size in bytes of returned stdout
--stderr STDERR max size in bytes of returned stderr
--version show program's version number and exit
Improving System Configuration