Updated documentation

This commit is contained in:
Mark Qvist 2021-12-08 20:42:48 +01:00
parent c0383fa2b0
commit b432a7c7de
9 changed files with 186 additions and 13 deletions

View File

@ -18,6 +18,62 @@ For a high-level overview of how networks can be formed over different interface
types, have a look at the :ref:`Building Networks<networks-main>` chapter of this types, have a look at the :ref:`Building Networks<networks-main>` chapter of this
manual. manual.
.. _interfaces-auto:
Auto Interface
==============
The Auto Interface enables communication with other discoverable Reticulum
nodes over UDP. It does not need any functional IP infrastructure like
routers or DHCP servers, but will require at least some sort of switching
medium between peers (a wired switch, a WiFi access point or similar), and
that link-local IPv6 is enabled in your operating system, which should be
enabled by default in almost all OSes.
.. code::
# This example demonstrates a TCP server interface.
# It will listen for incoming connections on the
# specified IP address and port number.
[[Default Interface]]
type = AutoInterface
interface_enabled = True
outgoing = True
# You can create multiple isolated Reticulum
# networks on the same physical LAN by
# specifying different Group IDs.
group_id = reticulum
If you are connected to the Internet with IPv6, and your provider will route
IPv6 multicast, you can potentially configure the Auto Interface to globally
autodiscover other Reticulum nodes within your selected Group ID. You can specify
the discovery scope by setting it to one of ``link``, ``admin``, ``site``,
``organisation`` or ``global``.
.. code::
[[Default Interface]]
type = AutoInterface
interface_enabled = True
outgoing = True
# Configure global discovery
group_id = custom_network_name
discovery_scope = global
# Other configuration options
discovery_port = 48555
data_port = 49555
*Please Note!* If you use the Auto Interface, you will need the Python module
``netifaces`` installed on your system. You can install it with ``pip3 install netifaces``.
.. _interfaces-udp: .. _interfaces-udp:
UDP Interface UDP Interface
@ -28,6 +84,12 @@ private and the internet. It can also allow broadcast communication
over IP networks, so it can provide an easy way to enable connectivity over IP networks, so it can provide an easy way to enable connectivity
with all other peers on a local area network. with all other peers on a local area network.
*Please Note!* Using broadcast UDP traffic has performance implications,
especially on WiFi. If your goal is simply to enable easy communication
with all peers in your local ethernet broadcast domain, the
:ref:`Auto Interface<interfaces-auto>` performs better, and is just as
easy to use.
The below example is enabled by default on new Reticulum installations, The below example is enabled by default on new Reticulum installations,
as it provides an easy way to get started and to test Reticulum on a as it provides an easy way to get started and to test Reticulum on a
pre-existing LAN. pre-existing LAN.
@ -48,9 +110,7 @@ pre-existing LAN.
# The above configuration will allow communication # The above configuration will allow communication
# within the local broadcast domains of all local # within the local broadcast domains of all local
# IP interfaces. This is enabled by default as an # IP interfaces.
# easy way to get started, but you might want to
# consider altering it to something more specific.
# Instead of specifying listen_ip, listen_port, # Instead of specifying listen_ip, listen_port,
# forward_ip and forward_port, you can also bind # forward_ip and forward_port, you can also bind

View File

@ -2,7 +2,7 @@
What is Reticulum? What is Reticulum?
****************** ******************
Reticulum is a cryptography-based networking stack for wide-area networks built on readily available hardware, and can operate even with very high latency and extremely low bandwidth. Reticulum is a cryptography-based networking stack for wide-area networks built on readily available hardware, that can operate even with very high latency and extremely low bandwidth.
Reticulum allows you to build very wide-area networks with off-the-shelf tools, and offers end-to-end encryption, autoconfiguring cryptographically backed multi-hop transport, efficient addressing, unforgeable packet acknowledgements and more. Reticulum allows you to build very wide-area networks with off-the-shelf tools, and offers end-to-end encryption, autoconfiguring cryptographically backed multi-hop transport, efficient addressing, unforgeable packet acknowledgements and more.

View File

@ -174,7 +174,7 @@ notifications about announces from relevant destinations.</p>
<span class="n">APP_NAME</span> <span class="o">=</span> <span class="s2">&quot;example_utilities&quot;</span> <span class="n">APP_NAME</span> <span class="o">=</span> <span class="s2">&quot;example_utilities&quot;</span>
<span class="c1"># We initialise two lists of strings to use as app_data</span> <span class="c1"># We initialise two lists of strings to use as app_data</span>
<span class="n">fruits</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;Peach&quot;</span><span class="p">,</span> <span class="s2">&quot;Quince&quot;</span><span class="p">,</span> <span class="s2">&quot;Date palm&quot;</span><span class="p">,</span> <span class="s2">&quot;Tangerine&quot;</span><span class="p">,</span> <span class="s2">&quot;Pomelo&quot;</span><span class="p">,</span> <span class="s2">&quot;Carambola&quot;</span><span class="p">,</span> <span class="s2">&quot;Grape&quot;</span><span class="p">]</span> <span class="n">fruits</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;Peach&quot;</span><span class="p">,</span> <span class="s2">&quot;Quince&quot;</span><span class="p">,</span> <span class="s2">&quot;Date&quot;</span><span class="p">,</span> <span class="s2">&quot;Tangerine&quot;</span><span class="p">,</span> <span class="s2">&quot;Pomelo&quot;</span><span class="p">,</span> <span class="s2">&quot;Carambola&quot;</span><span class="p">,</span> <span class="s2">&quot;Grape&quot;</span><span class="p">]</span>
<span class="n">noble_gases</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;Helium&quot;</span><span class="p">,</span> <span class="s2">&quot;Neon&quot;</span><span class="p">,</span> <span class="s2">&quot;Argon&quot;</span><span class="p">,</span> <span class="s2">&quot;Krypton&quot;</span><span class="p">,</span> <span class="s2">&quot;Xenon&quot;</span><span class="p">,</span> <span class="s2">&quot;Radon&quot;</span><span class="p">,</span> <span class="s2">&quot;Oganesson&quot;</span><span class="p">]</span> <span class="n">noble_gases</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;Helium&quot;</span><span class="p">,</span> <span class="s2">&quot;Neon&quot;</span><span class="p">,</span> <span class="s2">&quot;Argon&quot;</span><span class="p">,</span> <span class="s2">&quot;Krypton&quot;</span><span class="p">,</span> <span class="s2">&quot;Xenon&quot;</span><span class="p">,</span> <span class="s2">&quot;Radon&quot;</span><span class="p">,</span> <span class="s2">&quot;Oganesson&quot;</span><span class="p">]</span>
<span class="c1"># This initialisation is executed when the program is started</span> <span class="c1"># This initialisation is executed when the program is started</span>

View File

@ -87,6 +87,7 @@ to participate in the development of Reticulum itself.</p>
</ul> </ul>
</li> </li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Supported Interfaces</a><ul> <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Supported Interfaces</a><ul>
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#auto-interface">Auto Interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#udp-interface">UDP Interface</a></li> <li class="toctree-l2"><a class="reference internal" href="interfaces.html#udp-interface">UDP Interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#tcp-server-interface">TCP Server Interface</a></li> <li class="toctree-l2"><a class="reference internal" href="interfaces.html#tcp-server-interface">TCP Server Interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#tcp-client-interface">TCP Client Interface</a></li> <li class="toctree-l2"><a class="reference internal" href="interfaces.html#tcp-client-interface">TCP Client Interface</a></li>

View File

@ -53,12 +53,65 @@ and gives example configurations for the respective interface types.</p>
<p>For a high-level overview of how networks can be formed over different interface <p>For a high-level overview of how networks can be formed over different interface
types, have a look at the <a class="reference internal" href="networks.html#networks-main"><span class="std std-ref">Building Networks</span></a> chapter of this types, have a look at the <a class="reference internal" href="networks.html#networks-main"><span class="std std-ref">Building Networks</span></a> chapter of this
manual.</p> manual.</p>
<div class="section" id="auto-interface">
<span id="interfaces-auto"></span><h2>Auto Interface<a class="headerlink" href="#auto-interface" title="Permalink to this headline"></a></h2>
<p>The Auto Interface enables communication with other discoverable Reticulum
nodes over UDP. It does not need any functional IP infrastructure like
routers or DHCP servers, but will require at least some sort of switching
medium between peers (a wired switch, a WiFi access point or similar), and
that link-local IPv6 is enabled in your operating system, which should be
enabled by default in almost all OSes.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a TCP server interface.</span>
<span class="c1"># It will listen for incoming connections on the</span>
<span class="c1"># specified IP address and port number.</span>
<span class="p">[[</span><span class="n">Default</span> <span class="n">Interface</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">AutoInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span>
<span class="n">outgoing</span> <span class="o">=</span> <span class="kc">True</span>
<span class="c1"># You can create multiple isolated Reticulum</span>
<span class="c1"># networks on the same physical LAN by</span>
<span class="c1"># specifying different Group IDs.</span>
<span class="n">group_id</span> <span class="o">=</span> <span class="n">reticulum</span>
</pre></div>
</div>
<p>If you are connected to the Internet with IPv6, and your provider will route
IPv6 multicast, you can potentially configure the Auto Interface to globally
autodiscover other Reticulum nodes within your selected Group ID. You can specify
the discovery scope by setting it to one of <code class="docutils literal notranslate"><span class="pre">link</span></code>, <code class="docutils literal notranslate"><span class="pre">admin</span></code>, <code class="docutils literal notranslate"><span class="pre">site</span></code>,
<code class="docutils literal notranslate"><span class="pre">organisation</span></code> or <code class="docutils literal notranslate"><span class="pre">global</span></code>.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Default</span> <span class="n">Interface</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">AutoInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span>
<span class="n">outgoing</span> <span class="o">=</span> <span class="kc">True</span>
<span class="c1"># Configure global discovery</span>
<span class="n">group_id</span> <span class="o">=</span> <span class="n">custom_network_name</span>
<span class="n">discovery_scope</span> <span class="o">=</span> <span class="k">global</span>
<span class="c1"># Other configuration options</span>
<span class="n">discovery_port</span> <span class="o">=</span> <span class="mi">48555</span>
<span class="n">data_port</span> <span class="o">=</span> <span class="mi">49555</span>
</pre></div>
</div>
<p><em>Please Note!</em> If you use the Auto Interface, you will need the Python module
<code class="docutils literal notranslate"><span class="pre">netifaces</span></code> installed on your system. You can install it with <code class="docutils literal notranslate"><span class="pre">pip3</span> <span class="pre">install</span> <span class="pre">netifaces</span></code>.</p>
</div>
<div class="section" id="udp-interface"> <div class="section" id="udp-interface">
<span id="interfaces-udp"></span><h2>UDP Interface<a class="headerlink" href="#udp-interface" title="Permalink to this headline"></a></h2> <span id="interfaces-udp"></span><h2>UDP Interface<a class="headerlink" href="#udp-interface" title="Permalink to this headline"></a></h2>
<p>A UDP interface can be useful for communicating over IP networks, both <p>A UDP interface can be useful for communicating over IP networks, both
private and the internet. It can also allow broadcast communication private and the internet. It can also allow broadcast communication
over IP networks, so it can provide an easy way to enable connectivity over IP networks, so it can provide an easy way to enable connectivity
with all other peers on a local area network.</p> with all other peers on a local area network.</p>
<p><em>Please Note!</em> Using broadcast UDP traffic has performance implications,
especially on WiFi. If your goal is simply to enable easy communication
with all peers in your local ethernet broadcast domain, the
<a class="reference internal" href="#interfaces-auto"><span class="std std-ref">Auto Interface</span></a> performs better, and is just as
easy to use.</p>
<p>The below example is enabled by default on new Reticulum installations, <p>The below example is enabled by default on new Reticulum installations,
as it provides an easy way to get started and to test Reticulum on a as it provides an easy way to get started and to test Reticulum on a
pre-existing LAN.</p> pre-existing LAN.</p>
@ -76,9 +129,7 @@ pre-existing LAN.</p>
<span class="c1"># The above configuration will allow communication</span> <span class="c1"># The above configuration will allow communication</span>
<span class="c1"># within the local broadcast domains of all local</span> <span class="c1"># within the local broadcast domains of all local</span>
<span class="c1"># IP interfaces. This is enabled by default as an</span> <span class="c1"># IP interfaces.</span>
<span class="c1"># easy way to get started, but you might want to</span>
<span class="c1"># consider altering it to something more specific.</span>
<span class="c1"># Instead of specifying listen_ip, listen_port,</span> <span class="c1"># Instead of specifying listen_ip, listen_port,</span>
<span class="c1"># forward_ip and forward_port, you can also bind</span> <span class="c1"># forward_ip and forward_port, you can also bind</span>
@ -384,6 +435,7 @@ beaconing functionality described above.</p>
<h3><a href="index.html">Table of Contents</a></h3> <h3><a href="index.html">Table of Contents</a></h3>
<ul> <ul>
<li><a class="reference internal" href="#">Supported Interfaces</a><ul> <li><a class="reference internal" href="#">Supported Interfaces</a><ul>
<li><a class="reference internal" href="#auto-interface">Auto Interface</a></li>
<li><a class="reference internal" href="#udp-interface">UDP Interface</a></li> <li><a class="reference internal" href="#udp-interface">UDP Interface</a></li>
<li><a class="reference internal" href="#tcp-server-interface">TCP Server Interface</a></li> <li><a class="reference internal" href="#tcp-server-interface">TCP Server Interface</a></li>
<li><a class="reference internal" href="#tcp-client-interface">TCP Client Interface</a></li> <li><a class="reference internal" href="#tcp-client-interface">TCP Client Interface</a></li>

Binary file not shown.

File diff suppressed because one or more lines are too long

View File

@ -43,7 +43,7 @@
<div class="section" id="what-is-reticulum"> <div class="section" id="what-is-reticulum">
<h1>What is Reticulum?<a class="headerlink" href="#what-is-reticulum" title="Permalink to this headline"></a></h1> <h1>What is Reticulum?<a class="headerlink" href="#what-is-reticulum" title="Permalink to this headline"></a></h1>
<p>Reticulum is a cryptography-based networking stack for wide-area networks built on readily available hardware, and can operate even with very high latency and extremely low bandwidth.</p> <p>Reticulum is a cryptography-based networking stack for wide-area networks built on readily available hardware, that can operate even with very high latency and extremely low bandwidth.</p>
<p>Reticulum allows you to build very wide-area networks with off-the-shelf tools, and offers end-to-end encryption, autoconfiguring cryptographically backed multi-hop transport, efficient addressing, unforgeable packet acknowledgements and more.</p> <p>Reticulum allows you to build very wide-area networks with off-the-shelf tools, and offers end-to-end encryption, autoconfiguring cryptographically backed multi-hop transport, efficient addressing, unforgeable packet acknowledgements and more.</p>
<p>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 carrier for Reticulum. It is therefore trivial to tunnel Reticulum over the Internet or private IP networks. Reticulum is built directly on cryptographic principles, allowing resilience and stable functionality in open and trustless networks.</p> <p>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 carrier for Reticulum. It is therefore trivial to tunnel Reticulum over the Internet or private IP networks. Reticulum is built directly on cryptographic principles, allowing resilience and stable functionality in open and trustless networks.</p>
<p>No kernel modules or drivers are required. Reticulum runs completely in userland, and can run on practically any system that runs Python 3. Reticulum runs well even on small single-board computers like the Pi Zero.</p> <p>No kernel modules or drivers are required. Reticulum runs completely in userland, and can run on practically any system that runs Python 3. Reticulum runs well even on small single-board computers like the Pi Zero.</p>

View File

@ -18,6 +18,62 @@ For a high-level overview of how networks can be formed over different interface
types, have a look at the :ref:`Building Networks<networks-main>` chapter of this types, have a look at the :ref:`Building Networks<networks-main>` chapter of this
manual. manual.
.. _interfaces-auto:
Auto Interface
==============
The Auto Interface enables communication with other discoverable Reticulum
nodes over UDP. It does not need any functional IP infrastructure like
routers or DHCP servers, but will require at least some sort of switching
medium between peers (a wired switch, a WiFi access point or similar), and
that link-local IPv6 is enabled in your operating system, which should be
enabled by default in almost all OSes.
.. code::
# This example demonstrates a TCP server interface.
# It will listen for incoming connections on the
# specified IP address and port number.
[[Default Interface]]
type = AutoInterface
interface_enabled = True
outgoing = True
# You can create multiple isolated Reticulum
# networks on the same physical LAN by
# specifying different Group IDs.
group_id = reticulum
If you are connected to the Internet with IPv6, and your provider will route
IPv6 multicast, you can potentially configure the Auto Interface to globally
autodiscover other Reticulum nodes within your selected Group ID. You can specify
the discovery scope by setting it to one of ``link``, ``admin``, ``site``,
``organisation`` or ``global``.
.. code::
[[Default Interface]]
type = AutoInterface
interface_enabled = True
outgoing = True
# Configure global discovery
group_id = custom_network_name
discovery_scope = global
# Other configuration options
discovery_port = 48555
data_port = 49555
*Please Note!* If you use the Auto Interface, you will need the Python module
``netifaces`` installed on your system. You can install it with ``pip3 install netifaces``.
.. _interfaces-udp: .. _interfaces-udp:
UDP Interface UDP Interface
@ -28,6 +84,12 @@ private and the internet. It can also allow broadcast communication
over IP networks, so it can provide an easy way to enable connectivity over IP networks, so it can provide an easy way to enable connectivity
with all other peers on a local area network. with all other peers on a local area network.
*Please Note!* Using broadcast UDP traffic has performance implications,
especially on WiFi. If your goal is simply to enable easy communication
with all peers in your local ethernet broadcast domain, the
:ref:`Auto Interface<interfaces-auto>` performs better, and is just as
easy to use.
The below example is enabled by default on new Reticulum installations, The below example is enabled by default on new Reticulum installations,
as it provides an easy way to get started and to test Reticulum on a as it provides an easy way to get started and to test Reticulum on a
pre-existing LAN. pre-existing LAN.
@ -48,9 +110,7 @@ pre-existing LAN.
# The above configuration will allow communication # The above configuration will allow communication
# within the local broadcast domains of all local # within the local broadcast domains of all local
# IP interfaces. This is enabled by default as an # IP interfaces.
# easy way to get started, but you might want to
# consider altering it to something more specific.
# Instead of specifying listen_ip, listen_port, # Instead of specifying listen_ip, listen_port,
# forward_ip and forward_port, you can also bind # forward_ip and forward_port, you can also bind