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

Updated documentation

Browse Source
This commit is contained in:
Mark Qvist 2023-09-18 13:02:18 +02:00
parent d7b54ff397
commit 96cf6a790e
7 changed files with 144 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
docs/manual/_sources/gettingstartedfast.rst.txt
View File

@ -70,7 +70,8 @@ Remote Shell
The `rnsh <https://github.com/acehoss/rnsh>`_ program lets you establish fully interactive The `rnsh <https://github.com/acehoss/rnsh>`_ program lets you establish fully interactive
remote shell sessions over Reticulum. It also allows you to pipe any program to or from a remote shell sessions over Reticulum. It also allows you to pipe any program to or from a
remote system, and is similar to how ``ssh`` works. remote system, and is similar to how ``ssh`` works. The ``rnsh`` is very efficient, and
can facilitate fully interactive shell sessions, even over extremely low-bandwidth links.
Nomad Network Nomad Network
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
@ -281,7 +282,7 @@ started is to install the latest release of Reticulum via pip:
.. code:: .. code::
pip3 install rns pip install rns
The above command will install Reticulum and dependencies, and you will be The above command will install Reticulum and dependencies, and you will be
ready to import and use RNS in your own programs. The next step will most ready to import and use RNS in your own programs. The next step will most
@ -291,7 +292,7 @@ For extended functionality, you can install optional dependencies:
.. code:: .. code::
pip3 install pyserial pip install pyserial
Further information can be found in the :ref:`API Reference<api-main>`. Further information can be found in the :ref:`API Reference<api-main>`.
@ -306,7 +307,7 @@ don't use pip, but try this recipe:
.. code:: .. code::
# Install dependencies # Install dependencies
pip3 install cryptography pyserial pip install cryptography pyserial
# Clone repository # Clone repository
git clone https://github.com/markqvist/Reticulum.git git clone https://github.com/markqvist/Reticulum.git
@ -316,25 +317,25 @@ don't use pip, but try this recipe:
ln -s ../RNS ./Examples/ ln -s ../RNS ./Examples/
# Run an example # Run an example
python3 Examples/Echo.py -s python Examples/Echo.py -s
# Unless you've manually created a config file, Reticulum will do so now, # Unless you've manually created a config file, Reticulum will do so now,
# and immediately exit. Make any necessary changes to the file: # and immediately exit. Make any necessary changes to the file:
nano ~/.reticulum/config nano ~/.reticulum/config
# ... and launch the example again. # ... and launch the example again.
python3 Examples/Echo.py -s python Examples/Echo.py -s
# You can now repeat the process on another computer, # You can now repeat the process on another computer,
# and run the same example with -h to get command line options. # and run the same example with -h to get command line options.
python3 Examples/Echo.py -h python Examples/Echo.py -h
# Run the example in client mode to "ping" the server. # Run the example in client mode to "ping" the server.
# Replace the hash below with the actual destination hash of your server. # Replace the hash below with the actual destination hash of your server.
python3 Examples/Echo.py 174a64852a75682259ad8b921b8bf416 python Examples/Echo.py 174a64852a75682259ad8b921b8bf416
# Have a look at another example # Have a look at another example
python3 Examples/Filetransfer.py -h python Examples/Filetransfer.py -h
When you have experimented with the basic examples, it's time to go read the When you have experimented with the basic examples, it's time to go read the
:ref:`Understanding Reticulum<understanding-main>` chapter. Before submitting :ref:`Understanding Reticulum<understanding-main>` chapter. Before submitting
@ -446,11 +447,11 @@ detailed in this manual.
Debian Bookworm Debian Bookworm
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
On versions of Debian released after April 2023, it is no longer possible On versions of Debian released after April 2023, it is no longer possible by default
to use ``pip`` to install packages onto your system. Unfortunately, you will need to to use ``pip`` to install packages onto your system. Unfortunately, you will need to
use the replacement ``pipx`` command instead, which places installed packages in an use the replacement ``pipx`` command instead, which places installed packages in an
isolated environment. This should not negatively affect Reticulum, but installation isolated environment. This should not negatively affect Reticulum, but will not work
via this method is not fully tested yet. for including and using Reticulum in your own scripts and programs.
.. code:: .. code::
@ -463,14 +464,28 @@ via this method is not fully tested yet.
# Install Reticulum # Install Reticulum
pipx install rns pipx install rns
Alternatively, you can restore normal behaviour to ``pip`` by creating or editing
the configuration file located at ``~/.config/pip/pip.conf``, and adding the
following section:
.. code:: text
[global]
break-system-packages = true
Please note that the "break-system-packages" directive is a somewhat misleading choice
of words. Setting it will of course not break any system packages, but will simply
allow installing ``pip`` packages user- and system-wide. While this *could* in rare
cases lead to version conflicts, it does not generally pose any problems.
Ubuntu Lunar Ubuntu Lunar
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
On versions of Ubuntu released after April 2023, it is no longer possible On versions of Ubuntu released after April 2023, it is no longer possible by default
to use ``pip`` to install packages onto your system. Unfortunately, you will need to to use ``pip`` to install packages onto your system. Unfortunately, you will need to
use the replacement ``pipx`` command instead, which places installed packages in an use the replacement ``pipx`` command instead, which places installed packages in an
isolated environment. This should not negatively affect Reticulum, but installation isolated environment. This should not negatively affect Reticulum, but will not work
via this method is not fully tested yet. for including and using Reticulum in your own scripts and programs.
.. code:: .. code::
@ -483,14 +498,24 @@ via this method is not fully tested yet.
# Install Reticulum # Install Reticulum
pipx install rns pipx install rns
Alternatively, you can restore normal behaviour to ``pip`` by creating or editing
the configuration file located at ``~/.config/pip/pip.conf``, and adding the
following section:
.. code:: text
[global]
break-system-packages = true
Please note that the "break-system-packages" directive is a somewhat misleading choice
of words. Setting it will of course not break any system packages, but will simply
allow installing ``pip`` packages user- and system-wide. While this _could_ in rare
cases lead to version conflicts, it does not generally pose any problems.
Pure-Python Reticulum Pure-Python Reticulum
============================================== ==============================================
In some rare cases, and on more obscure system types, it is not possible to In some rare cases, and on more obscure system types, it is not possible to
install one or more dependencies install one or more dependencies. In such situations,
On more unusual systems, and in some rare cases, it might not be possible to
install or even compile one or more of the above modules. In such situations,
you can use the ``rnspure`` package instead of the ``rns`` package, or use ``pip`` you can use the ``rnspure`` package instead of the ``rns`` package, or use ``pip``
with the ``--no-dependencies`` command-line option. The ``rnspure`` with the ``--no-dependencies`` command-line option. The ``rnspure``
package requires no external dependencies for installation. Please note that the package requires no external dependencies for installation. Please note that the

10
docs/manual/_sources/whatis.rst.txt
View File

@ -21,15 +21,15 @@ networks, without any need for hierarchical or beaureucratic structures to contr
or manage them, while ensuring individuals and communities full sovereignty or manage them, while ensuring individuals and communities full sovereignty
over their own network segments. over their own network segments.
Reticulum is a complete networking stack, and does not need IP or higher Reticulum is a **complete networking stack**, and does not need IP or higher
layers, although it is easy to utilise IP (with TCP or UDP) as the underlying layers, although it is easy to utilise IP (with TCP or UDP) as the underlying
carrier for Reticulum. It is therefore trivial to tunnel Reticulum over the carrier for Reticulum. It is therefore trivial to tunnel Reticulum over the
Internet or private IP networks. Reticulum is built directly on cryptographic Internet or private IP networks. Reticulum is built directly on cryptographic
principles, allowing resilience and stable functionality in open and trustless principles, allowing resilience and stable functionality in open and trustless
networks. networks.
No kernel modules or drivers are required. Reticulum runs completely in No kernel modules or drivers are required. Reticulum can run completely in
userland, and can run on practically any system that runs Python 3. Reticulum userland, and will run on practically any system that runs Python 3. Reticulum
runs well even on small single-board computers like the Pi Zero. runs well even on small single-board computers like the Pi Zero.
@ -38,7 +38,7 @@ Current Status
**Please know!** Reticulum should currently be considered beta software. All core protocol **Please know!** Reticulum should currently be considered beta software. All core protocol
features are implemented and functioning, but additions will probably occur as features are implemented and functioning, but additions will probably occur as
real-world use is explored. *There will be bugs*. The API and wire-format can be real-world use is explored. *There will be bugs*. The API and wire-format can be
considered stable at the moment, but could change if absolutely warranted. considered complete and stable at the moment, but could change if absolutely warranted.
What does Reticulum Offer? What does Reticulum Offer?
@ -71,7 +71,7 @@ What does Reticulum Offer?
* Efficient link establishment * Efficient link establishment
* Total bandwidth cost of setting up a link is only 3 packets, totalling 297 bytes * Total cost of setting up an encrypted and verified link is only 3 packets, totalling 297 bytes
* Low cost of keeping links open at only 0.44 bits per second * Low cost of keeping links open at only 0.44 bits per second

59
docs/manual/gettingstartedfast.html
View File

@ -277,7 +277,8 @@ radio interfaces can then be added later.</p>
<h3>Remote Shell<a class="headerlink" href="#remote-shell" title="Permalink to this heading">#</a></h3> <h3>Remote Shell<a class="headerlink" href="#remote-shell" title="Permalink to this heading">#</a></h3>
<p>The <a class="reference external" href="https://github.com/acehoss/rnsh">rnsh</a> program lets you establish fully interactive <p>The <a class="reference external" href="https://github.com/acehoss/rnsh">rnsh</a> program lets you establish fully interactive
remote shell sessions over Reticulum. It also allows you to pipe any program to or from a remote shell sessions over Reticulum. It also allows you to pipe any program to or from a
remote system, and is similar to how <code class="docutils literal notranslate"><span class="pre">ssh</span></code> works.</p> remote system, and is similar to how <code class="docutils literal notranslate"><span class="pre">ssh</span></code> works. The <code class="docutils literal notranslate"><span class="pre">rnsh</span></code> is very efficient, and
can facilitate fully interactive shell sessions, even over extremely low-bandwidth links.</p>
</section> </section>
<section id="nomad-network"> <section id="nomad-network">
<h3>Nomad Network<a class="headerlink" href="#nomad-network" title="Permalink to this heading">#</a></h3> <h3>Nomad Network<a class="headerlink" href="#nomad-network" title="Permalink to this heading">#</a></h3>
@ -426,7 +427,7 @@ digital radio transceiver, that integrates easily with Reticulum.</p>
<p>To build one yourself requires installing a custom firmware on a supported LoRa <p>To build one yourself requires installing a custom firmware on a supported LoRa
development board with an auto-install script. Please see the <a class="reference internal" href="hardware.html#hardware-main"><span class="std std-ref">Communications Hardware</span></a> development board with an auto-install script. Please see the <a class="reference internal" href="hardware.html#hardware-main"><span class="std std-ref">Communications Hardware</span></a>
chapter for a guide. If you prefer purchasing a ready-made unit, you can refer to the chapter for a guide. If you prefer purchasing a ready-made unit, you can refer to the
<a class="reference internal" href="hardware.html#rnode-suppliers"><span class="std std-ref">list of suppliers</span></a>. For more information on RNode, you can also <span class="xref std std-ref">list of suppliers</span>. For more information on RNode, you can also
refer to these additional external resources:</p> refer to these additional external resources:</p>
<ul class="simple"> <ul class="simple">
<li><p><a class="reference external" href="https://unsigned.io/how-to-make-your-own-rnodes/">How To Make Your Own RNodes</a></p></li> <li><p><a class="reference external" href="https://unsigned.io/how-to-make-your-own-rnodes/">How To Make Your Own RNodes</a></p></li>
@ -443,14 +444,14 @@ and propose adding an interface for the hardware.</p>
<h2>Develop a Program with Reticulum<a class="headerlink" href="#develop-a-program-with-reticulum" title="Permalink to this heading">#</a></h2> <h2>Develop a Program with Reticulum<a class="headerlink" href="#develop-a-program-with-reticulum" title="Permalink to this heading">#</a></h2>
<p>If you want to develop programs that use Reticulum, the easiest way to get <p>If you want to develop programs that use Reticulum, the easiest way to get
started is to install the latest release of Reticulum via pip:</p> started is to install the latest release of Reticulum via pip:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip3</span> <span class="n">install</span> <span class="n">rns</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">rns</span>
</pre></div> </pre></div>
</div> </div>
<p>The above command will install Reticulum and dependencies, and you will be <p>The above command will install Reticulum and dependencies, and you will be
ready to import and use RNS in your own programs. The next step will most ready to import and use RNS in your own programs. The next step will most
likely be to look at some <a class="reference internal" href="examples.html#examples-main"><span class="std std-ref">Example Programs</span></a>.</p> likely be to look at some <a class="reference internal" href="examples.html#examples-main"><span class="std std-ref">Example Programs</span></a>.</p>
<p>For extended functionality, you can install optional dependencies:</p> <p>For extended functionality, you can install optional dependencies:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip3</span> <span class="n">install</span> <span class="n">pyserial</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">pyserial</span>
</pre></div> </pre></div>
</div> </div>
<p>Further information can be found in the <a class="reference internal" href="reference.html#api-main"><span class="std std-ref">API Reference</span></a>.</p> <p>Further information can be found in the <a class="reference internal" href="reference.html#api-main"><span class="std std-ref">API Reference</span></a>.</p>
@ -461,7 +462,7 @@ likely be to look at some <a class="reference internal" href="examples.html#exam
utilities, you’ll want to get the latest source from GitHub. In that case, utilities, you’ll want to get the latest source from GitHub. In that case,
don’t use pip, but try this recipe:</p> don’t use pip, but try this recipe:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install dependencies</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install dependencies</span>
<span class="n">pip3</span> <span class="n">install</span> <span class="n">cryptography</span> <span class="n">pyserial</span> <span class="n">pip</span> <span class="n">install</span> <span class="n">cryptography</span> <span class="n">pyserial</span>
<span class="c1"># Clone repository</span> <span class="c1"># Clone repository</span>
<span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">markqvist</span><span class="o">/</span><span class="n">Reticulum</span><span class="o">.</span><span class="n">git</span> <span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">markqvist</span><span class="o">/</span><span class="n">Reticulum</span><span class="o">.</span><span class="n">git</span>
@ -471,25 +472,25 @@ don’t use pip, but try this recipe:</p>
<span class="n">ln</span> <span class="o">-</span><span class="n">s</span> <span class="o">../</span><span class="n">RNS</span> <span class="o">./</span><span class="n">Examples</span><span class="o">/</span> <span class="n">ln</span> <span class="o">-</span><span class="n">s</span> <span class="o">../</span><span class="n">RNS</span> <span class="o">./</span><span class="n">Examples</span><span class="o">/</span>
<span class="c1"># Run an example</span> <span class="c1"># Run an example</span>
<span class="n">python3</span> <span class="n">Examples</span><span class="o">/</span><span class="n">Echo</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">s</span> <span class="n">python</span> <span class="n">Examples</span><span class="o">/</span><span class="n">Echo</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">s</span>
<span class="c1"># Unless you&#39;ve manually created a config file, Reticulum will do so now,</span> <span class="c1"># Unless you&#39;ve manually created a config file, Reticulum will do so now,</span>
<span class="c1"># and immediately exit. Make any necessary changes to the file:</span> <span class="c1"># and immediately exit. Make any necessary changes to the file:</span>
<span class="n">nano</span> <span class="o">~/.</span><span class="n">reticulum</span><span class="o">/</span><span class="n">config</span> <span class="n">nano</span> <span class="o">~/.</span><span class="n">reticulum</span><span class="o">/</span><span class="n">config</span>
<span class="c1"># ... and launch the example again.</span> <span class="c1"># ... and launch the example again.</span>
<span class="n">python3</span> <span class="n">Examples</span><span class="o">/</span><span class="n">Echo</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">s</span> <span class="n">python</span> <span class="n">Examples</span><span class="o">/</span><span class="n">Echo</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">s</span>
<span class="c1"># You can now repeat the process on another computer,</span> <span class="c1"># You can now repeat the process on another computer,</span>
<span class="c1"># and run the same example with -h to get command line options.</span> <span class="c1"># and run the same example with -h to get command line options.</span>
<span class="n">python3</span> <span class="n">Examples</span><span class="o">/</span><span class="n">Echo</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">h</span> <span class="n">python</span> <span class="n">Examples</span><span class="o">/</span><span class="n">Echo</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">h</span>
<span class="c1"># Run the example in client mode to &quot;ping&quot; the server.</span> <span class="c1"># Run the example in client mode to &quot;ping&quot; the server.</span>
<span class="c1"># Replace the hash below with the actual destination hash of your server.</span> <span class="c1"># Replace the hash below with the actual destination hash of your server.</span>
<span class="n">python3</span> <span class="n">Examples</span><span class="o">/</span><span class="n">Echo</span><span class="o">.</span><span class="n">py</span> <span class="mi">174</span><span class="n">a64852a75682259ad8b921b8bf416</span> <span class="n">python</span> <span class="n">Examples</span><span class="o">/</span><span class="n">Echo</span><span class="o">.</span><span class="n">py</span> <span class="mi">174</span><span class="n">a64852a75682259ad8b921b8bf416</span>
<span class="c1"># Have a look at another example</span> <span class="c1"># Have a look at another example</span>
<span class="n">python3</span> <span class="n">Examples</span><span class="o">/</span><span class="n">Filetransfer</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">h</span> <span class="n">python</span> <span class="n">Examples</span><span class="o">/</span><span class="n">Filetransfer</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">h</span>
</pre></div> </pre></div>
</div> </div>
<p>When you have experimented with the basic examples, it’s time to go read the <p>When you have experimented with the basic examples, it’s time to go read the
@ -586,11 +587,11 @@ detailed in this manual.</p>
</section> </section>
<section id="debian-bookworm"> <section id="debian-bookworm">
<h3>Debian Bookworm<a class="headerlink" href="#debian-bookworm" title="Permalink to this heading">#</a></h3> <h3>Debian Bookworm<a class="headerlink" href="#debian-bookworm" title="Permalink to this heading">#</a></h3>
<p>On versions of Debian released after April 2023, it is no longer possible <p>On versions of Debian released after April 2023, it is no longer possible by default
to use <code class="docutils literal notranslate"><span class="pre">pip</span></code> to install packages onto your system. Unfortunately, you will need to to use <code class="docutils literal notranslate"><span class="pre">pip</span></code> to install packages onto your system. Unfortunately, you will need to
use the replacement <code class="docutils literal notranslate"><span class="pre">pipx</span></code> command instead, which places installed packages in an use the replacement <code class="docutils literal notranslate"><span class="pre">pipx</span></code> command instead, which places installed packages in an
isolated environment. This should not negatively affect Reticulum, but installation isolated environment. This should not negatively affect Reticulum, but will not work
via this method is not fully tested yet.</p> for including and using Reticulum in your own scripts and programs.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install pipx</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install pipx</span>
<span class="n">sudo</span> <span class="n">apt</span> <span class="n">install</span> <span class="n">pipx</span> <span class="n">sudo</span> <span class="n">apt</span> <span class="n">install</span> <span class="n">pipx</span>
@ -601,14 +602,25 @@ via this method is not fully tested yet.</p>
<span class="n">pipx</span> <span class="n">install</span> <span class="n">rns</span> <span class="n">pipx</span> <span class="n">install</span> <span class="n">rns</span>
</pre></div> </pre></div>
</div> </div>
<p>Alternatively, you can restore normal behaviour to <code class="docutils literal notranslate"><span class="pre">pip</span></code> by creating or editing
the configuration file located at <code class="docutils literal notranslate"><span class="pre">~/.config/pip/pip.conf</span></code>, and adding the
following section:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[global]
break-system-packages = true
</pre></div>
</div>
<p>Please note that the “break-system-packages” directive is a somewhat misleading choice
of words. Setting it will of course not break any system packages, but will simply
allow installing <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages user- and system-wide. While this <em>could</em> in rare
cases lead to version conflicts, it does not generally pose any problems.</p>
</section> </section>
<section id="ubuntu-lunar"> <section id="ubuntu-lunar">
<h3>Ubuntu Lunar<a class="headerlink" href="#ubuntu-lunar" title="Permalink to this heading">#</a></h3> <h3>Ubuntu Lunar<a class="headerlink" href="#ubuntu-lunar" title="Permalink to this heading">#</a></h3>
<p>On versions of Ubuntu released after April 2023, it is no longer possible <p>On versions of Ubuntu released after April 2023, it is no longer possible by default
to use <code class="docutils literal notranslate"><span class="pre">pip</span></code> to install packages onto your system. Unfortunately, you will need to to use <code class="docutils literal notranslate"><span class="pre">pip</span></code> to install packages onto your system. Unfortunately, you will need to
use the replacement <code class="docutils literal notranslate"><span class="pre">pipx</span></code> command instead, which places installed packages in an use the replacement <code class="docutils literal notranslate"><span class="pre">pipx</span></code> command instead, which places installed packages in an
isolated environment. This should not negatively affect Reticulum, but installation isolated environment. This should not negatively affect Reticulum, but will not work
via this method is not fully tested yet.</p> for including and using Reticulum in your own scripts and programs.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install pipx</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install pipx</span>
<span class="n">sudo</span> <span class="n">apt</span> <span class="n">install</span> <span class="n">pipx</span> <span class="n">sudo</span> <span class="n">apt</span> <span class="n">install</span> <span class="n">pipx</span>
@ -619,14 +631,23 @@ via this method is not fully tested yet.</p>
<span class="n">pipx</span> <span class="n">install</span> <span class="n">rns</span> <span class="n">pipx</span> <span class="n">install</span> <span class="n">rns</span>
</pre></div> </pre></div>
</div> </div>
<p>Alternatively, you can restore normal behaviour to <code class="docutils literal notranslate"><span class="pre">pip</span></code> by creating or editing
the configuration file located at <code class="docutils literal notranslate"><span class="pre">~/.config/pip/pip.conf</span></code>, and adding the
following section:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>[global]
break-system-packages = true
</pre></div>
</div>
<p>Please note that the “break-system-packages” directive is a somewhat misleading choice
of words. Setting it will of course not break any system packages, but will simply
allow installing <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages user- and system-wide. While this _could_ in rare
cases lead to version conflicts, it does not generally pose any problems.</p>
</section> </section>
</section> </section>
<section id="pure-python-reticulum"> <section id="pure-python-reticulum">
<h2>Pure-Python Reticulum<a class="headerlink" href="#pure-python-reticulum" title="Permalink to this heading">#</a></h2> <h2>Pure-Python Reticulum<a class="headerlink" href="#pure-python-reticulum" title="Permalink to this heading">#</a></h2>
<p>In some rare cases, and on more obscure system types, it is not possible to <p>In some rare cases, and on more obscure system types, it is not possible to
install one or more dependencies</p> install one or more dependencies. In such situations,
<p>On more unusual systems, and in some rare cases, it might not be possible to
install or even compile one or more of the above modules. In such situations,
you can use the <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> package instead of the <code class="docutils literal notranslate"><span class="pre">rns</span></code> package, or use <code class="docutils literal notranslate"><span class="pre">pip</span></code> you can use the <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> package instead of the <code class="docutils literal notranslate"><span class="pre">rns</span></code> package, or use <code class="docutils literal notranslate"><span class="pre">pip</span></code>
with the <code class="docutils literal notranslate"><span class="pre">--no-dependencies</span></code> command-line option. The <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> with the <code class="docutils literal notranslate"><span class="pre">--no-dependencies</span></code> command-line option. The <code class="docutils literal notranslate"><span class="pre">rnspure</span></code>
package requires no external dependencies for installation. Please note that the package requires no external dependencies for installation. Please note that the

2
docs/manual/searchindex.js
View File

File diff suppressed because one or more lines are too long

10
docs/manual/whatis.html
View File

@ -238,21 +238,21 @@ outside control, manipulation or censorship.</p>
networks, without any need for hierarchical or beaureucratic structures to control networks, without any need for hierarchical or beaureucratic structures to control
or manage them, while ensuring individuals and communities full sovereignty or manage them, while ensuring individuals and communities full sovereignty
over their own network segments.</p> over their own network segments.</p>
<p>Reticulum is a complete networking stack, and does not need IP or higher <p>Reticulum is a <strong>complete networking stack</strong>, and does not need IP or higher
layers, although it is easy to utilise IP (with TCP or UDP) as the underlying layers, although it is easy to utilise IP (with TCP or UDP) as the underlying
carrier for Reticulum. It is therefore trivial to tunnel Reticulum over the carrier for Reticulum. It is therefore trivial to tunnel Reticulum over the
Internet or private IP networks. Reticulum is built directly on cryptographic Internet or private IP networks. Reticulum is built directly on cryptographic
principles, allowing resilience and stable functionality in open and trustless principles, allowing resilience and stable functionality in open and trustless
networks.</p> networks.</p>
<p>No kernel modules or drivers are required. Reticulum runs completely in <p>No kernel modules or drivers are required. Reticulum can run completely in
userland, and can run on practically any system that runs Python 3. Reticulum userland, and will run on practically any system that runs Python 3. Reticulum
runs well even on small single-board computers like the Pi Zero.</p> runs well even on small single-board computers like the Pi Zero.</p>
<section id="current-status"> <section id="current-status">
<h2>Current Status<a class="headerlink" href="#current-status" title="Permalink to this heading">#</a></h2> <h2>Current Status<a class="headerlink" href="#current-status" title="Permalink to this heading">#</a></h2>
<p><strong>Please know!</strong> Reticulum should currently be considered beta software. All core protocol <p><strong>Please know!</strong> Reticulum should currently be considered beta software. All core protocol
features are implemented and functioning, but additions will probably occur as features are implemented and functioning, but additions will probably occur as
real-world use is explored. <em>There will be bugs</em>. The API and wire-format can be real-world use is explored. <em>There will be bugs</em>. The API and wire-format can be
considered stable at the moment, but could change if absolutely warranted.</p> considered complete and stable at the moment, but could change if absolutely warranted.</p>
</section> </section>
<section id="what-does-reticulum-offer"> <section id="what-does-reticulum-offer">
<h2>What does Reticulum Offer?<a class="headerlink" href="#what-does-reticulum-offer" title="Permalink to this heading">#</a></h2> <h2>What does Reticulum Offer?<a class="headerlink" href="#what-does-reticulum-offer" title="Permalink to this heading">#</a></h2>
@ -275,7 +275,7 @@ considered stable at the moment, but could change if absolutely warranted.</p>
<li><p>An intuitive and developer-friendly API</p></li> <li><p>An intuitive and developer-friendly API</p></li>
<li><p>Efficient link establishment</p> <li><p>Efficient link establishment</p>
<ul> <ul>
<li><p>Total bandwidth cost of setting up a link is only 3 packets, totalling 297 bytes</p></li> <li><p>Total cost of setting up an encrypted and verified link is only 3 packets, totalling 297 bytes</p></li>
<li><p>Low cost of keeping links open at only 0.44 bits per second</p></li> <li><p>Low cost of keeping links open at only 0.44 bits per second</p></li>
</ul> </ul>
</li> </li>

63
docs/source/gettingstartedfast.rst
View File

@ -70,7 +70,8 @@ Remote Shell
The `rnsh <https://github.com/acehoss/rnsh>`_ program lets you establish fully interactive The `rnsh <https://github.com/acehoss/rnsh>`_ program lets you establish fully interactive
remote shell sessions over Reticulum. It also allows you to pipe any program to or from a remote shell sessions over Reticulum. It also allows you to pipe any program to or from a
remote system, and is similar to how ``ssh`` works. remote system, and is similar to how ``ssh`` works. The ``rnsh`` is very efficient, and
can facilitate fully interactive shell sessions, even over extremely low-bandwidth links.
Nomad Network Nomad Network
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
@ -281,7 +282,7 @@ started is to install the latest release of Reticulum via pip:
.. code:: .. code::
pip3 install rns pip install rns
The above command will install Reticulum and dependencies, and you will be The above command will install Reticulum and dependencies, and you will be
ready to import and use RNS in your own programs. The next step will most ready to import and use RNS in your own programs. The next step will most
@ -291,7 +292,7 @@ For extended functionality, you can install optional dependencies:
.. code:: .. code::
pip3 install pyserial pip install pyserial
Further information can be found in the :ref:`API Reference<api-main>`. Further information can be found in the :ref:`API Reference<api-main>`.
@ -306,7 +307,7 @@ don't use pip, but try this recipe:
.. code:: .. code::
# Install dependencies # Install dependencies
pip3 install cryptography pyserial pip install cryptography pyserial
# Clone repository # Clone repository
git clone https://github.com/markqvist/Reticulum.git git clone https://github.com/markqvist/Reticulum.git
@ -316,25 +317,25 @@ don't use pip, but try this recipe:
ln -s ../RNS ./Examples/ ln -s ../RNS ./Examples/
# Run an example # Run an example
python3 Examples/Echo.py -s python Examples/Echo.py -s
# Unless you've manually created a config file, Reticulum will do so now, # Unless you've manually created a config file, Reticulum will do so now,
# and immediately exit. Make any necessary changes to the file: # and immediately exit. Make any necessary changes to the file:
nano ~/.reticulum/config nano ~/.reticulum/config
# ... and launch the example again. # ... and launch the example again.
python3 Examples/Echo.py -s python Examples/Echo.py -s
# You can now repeat the process on another computer, # You can now repeat the process on another computer,
# and run the same example with -h to get command line options. # and run the same example with -h to get command line options.
python3 Examples/Echo.py -h python Examples/Echo.py -h
# Run the example in client mode to "ping" the server. # Run the example in client mode to "ping" the server.
# Replace the hash below with the actual destination hash of your server. # Replace the hash below with the actual destination hash of your server.
python3 Examples/Echo.py 174a64852a75682259ad8b921b8bf416 python Examples/Echo.py 174a64852a75682259ad8b921b8bf416
# Have a look at another example # Have a look at another example
python3 Examples/Filetransfer.py -h python Examples/Filetransfer.py -h
When you have experimented with the basic examples, it's time to go read the When you have experimented with the basic examples, it's time to go read the
:ref:`Understanding Reticulum<understanding-main>` chapter. Before submitting :ref:`Understanding Reticulum<understanding-main>` chapter. Before submitting
@ -446,11 +447,11 @@ detailed in this manual.
Debian Bookworm Debian Bookworm
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
On versions of Debian released after April 2023, it is no longer possible On versions of Debian released after April 2023, it is no longer possible by default
to use ``pip`` to install packages onto your system. Unfortunately, you will need to to use ``pip`` to install packages onto your system. Unfortunately, you will need to
use the replacement ``pipx`` command instead, which places installed packages in an use the replacement ``pipx`` command instead, which places installed packages in an
isolated environment. This should not negatively affect Reticulum, but installation isolated environment. This should not negatively affect Reticulum, but will not work
via this method is not fully tested yet. for including and using Reticulum in your own scripts and programs.
.. code:: .. code::
@ -463,14 +464,28 @@ via this method is not fully tested yet.
# Install Reticulum # Install Reticulum
pipx install rns pipx install rns
Alternatively, you can restore normal behaviour to ``pip`` by creating or editing
the configuration file located at ``~/.config/pip/pip.conf``, and adding the
following section:
.. code:: text
[global]
break-system-packages = true
Please note that the "break-system-packages" directive is a somewhat misleading choice
of words. Setting it will of course not break any system packages, but will simply
allow installing ``pip`` packages user- and system-wide. While this *could* in rare
cases lead to version conflicts, it does not generally pose any problems.
Ubuntu Lunar Ubuntu Lunar
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
On versions of Ubuntu released after April 2023, it is no longer possible On versions of Ubuntu released after April 2023, it is no longer possible by default
to use ``pip`` to install packages onto your system. Unfortunately, you will need to to use ``pip`` to install packages onto your system. Unfortunately, you will need to
use the replacement ``pipx`` command instead, which places installed packages in an use the replacement ``pipx`` command instead, which places installed packages in an
isolated environment. This should not negatively affect Reticulum, but installation isolated environment. This should not negatively affect Reticulum, but will not work
via this method is not fully tested yet. for including and using Reticulum in your own scripts and programs.
.. code:: .. code::
@ -483,14 +498,24 @@ via this method is not fully tested yet.
# Install Reticulum # Install Reticulum
pipx install rns pipx install rns
Alternatively, you can restore normal behaviour to ``pip`` by creating or editing
the configuration file located at ``~/.config/pip/pip.conf``, and adding the
following section:
.. code:: text
[global]
break-system-packages = true
Please note that the "break-system-packages" directive is a somewhat misleading choice
of words. Setting it will of course not break any system packages, but will simply
allow installing ``pip`` packages user- and system-wide. While this _could_ in rare
cases lead to version conflicts, it does not generally pose any problems.
Pure-Python Reticulum Pure-Python Reticulum
============================================== ==============================================
In some rare cases, and on more obscure system types, it is not possible to In some rare cases, and on more obscure system types, it is not possible to
install one or more dependencies install one or more dependencies. In such situations,
On more unusual systems, and in some rare cases, it might not be possible to
install or even compile one or more of the above modules. In such situations,
you can use the ``rnspure`` package instead of the ``rns`` package, or use ``pip`` you can use the ``rnspure`` package instead of the ``rns`` package, or use ``pip``
with the ``--no-dependencies`` command-line option. The ``rnspure`` with the ``--no-dependencies`` command-line option. The ``rnspure``
package requires no external dependencies for installation. Please note that the package requires no external dependencies for installation. Please note that the

10
docs/source/whatis.rst
View File

@ -21,15 +21,15 @@ networks, without any need for hierarchical or beaureucratic structures to contr
or manage them, while ensuring individuals and communities full sovereignty or manage them, while ensuring individuals and communities full sovereignty
over their own network segments. over their own network segments.
Reticulum is a complete networking stack, and does not need IP or higher Reticulum is a **complete networking stack**, and does not need IP or higher
layers, although it is easy to utilise IP (with TCP or UDP) as the underlying layers, although it is easy to utilise IP (with TCP or UDP) as the underlying
carrier for Reticulum. It is therefore trivial to tunnel Reticulum over the carrier for Reticulum. It is therefore trivial to tunnel Reticulum over the
Internet or private IP networks. Reticulum is built directly on cryptographic Internet or private IP networks. Reticulum is built directly on cryptographic
principles, allowing resilience and stable functionality in open and trustless principles, allowing resilience and stable functionality in open and trustless
networks. networks.
No kernel modules or drivers are required. Reticulum runs completely in No kernel modules or drivers are required. Reticulum can run completely in
userland, and can run on practically any system that runs Python 3. Reticulum userland, and will run on practically any system that runs Python 3. Reticulum
runs well even on small single-board computers like the Pi Zero. runs well even on small single-board computers like the Pi Zero.
@ -38,7 +38,7 @@ Current Status
**Please know!** Reticulum should currently be considered beta software. All core protocol **Please know!** Reticulum should currently be considered beta software. All core protocol
features are implemented and functioning, but additions will probably occur as features are implemented and functioning, but additions will probably occur as
real-world use is explored. *There will be bugs*. The API and wire-format can be real-world use is explored. *There will be bugs*. The API and wire-format can be
considered stable at the moment, but could change if absolutely warranted. considered complete and stable at the moment, but could change if absolutely warranted.
What does Reticulum Offer? What does Reticulum Offer?
@ -71,7 +71,7 @@ What does Reticulum Offer?
* Efficient link establishment * Efficient link establishment
* Total bandwidth cost of setting up a link is only 3 packets, totalling 297 bytes * Total cost of setting up an encrypted and verified link is only 3 packets, totalling 297 bytes
* Low cost of keeping links open at only 0.44 bits per second * Low cost of keeping links open at only 0.44 bits per second