Git-Mirrors/Reticulum
1
0
Fork 0
mirror of https://github.com/markqvist/Reticulum.git synced 2025-08-07 05:52:41 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Updated interface documentation

Browse source
This commit is contained in:
Mark Qvist 2025-04-09 23:45:14 +02:00
parent 3049049d5b
commit 6125c835f7
8 changed files with 686 additions and 348 deletions
Download patch file Download diff file Expand all files Collapse all files

BIN
docs/Reticulum Manual.epub
View file

Binary file not shown.

BIN
docs/Reticulum Manual.pdf
View file

Binary file not shown.

332
docs/manual/_sources/interfaces.rst.txt
View file

@ -35,11 +35,25 @@ Auto Interface
============== ==============
The Auto Interface enables communication with other discoverable Reticulum The Auto Interface enables communication with other discoverable Reticulum
nodes over autoconfigured IPv6 and UDP. It does not need any functional IP nodes over autoconfigured IPv6 and UDP. Even though it uses IPv6 for peer
infrastructure like routers or DHCP servers, but will require at least some discovery, and UDP for packet transport, it **does not** need any functional IP
sort of switching medium between peers (a wired switch, a hub, a WiFi access infrastructure like routers or DHCP servers, on your physical network.
point or similar), and that link-local IPv6 is enabled in your operating
system, which should be enabled by default in almost all OSes. As long as there is at least some sort of switching medium present between peers (a
wired switch, a hub, a WiFi access point or similar), it will work without
any configuration, setup or intermediary devices.
For ``AutoInterface`` peer discovery to work, it's also required that link-local
IPv6 support is available on your system, which it should be by default in all
current operating systems, both desktop and mobile.
.. note::
Almost all current Ethernet and WiFi hardware will work without any kind
of configuration or setup with ``AutoInterface``, but a small subset of
devices turn on options that limit device-to-device communication by default,
resulting in ``AutoInterface`` peer discovery being blocked. This issue is
most commonly seen on very cheap, ISP-supplied WiFi routers, and can sometimes
be turned off in the router configuration.
.. code:: .. code::
@ -48,40 +62,34 @@ system, which should be enabled by default in almost all OSes.
# tion with all other reachable devices on all # tion with all other reachable devices on all
# usable physical ethernet-based devices that # usable physical ethernet-based devices that
# are available on the system. # are available on the system.
[[Default Interface]] [[Default Interface]]
type = AutoInterface type = AutoInterface
interface_enabled = True enabled = yes
# This example demonstrates an more specifically # This example demonstrates an more specifically
# configured Auto Interface, that only uses spe- # configured Auto Interface, that only uses spe-
# cific physical interfaces, and has a number of # cific physical interfaces, and has a number of
# other configuration options set. # other configuration options set.
[[Default Interface]] [[Default Interface]]
type = AutoInterface type = AutoInterface
interface_enabled = True enabled = yes
# You can create multiple isolated Reticulum # You can create multiple isolated Reticulum
# networks on the same physical LAN by # networks on the same physical LAN by
# specifying different Group IDs. # specifying different Group IDs.
group_id = reticulum group_id = reticulum
# You can also choose the multicast address type: # You can also choose the multicast address type:
# temporary (default, Temporary Multicast Address) # temporary (default, Temporary Multicast Address)
# or permanent (Permanent Multicast Address) # or permanent (Permanent Multicast Address)
multicast_address_type = permanent multicast_address_type = permanent
# You can also select specifically which # You can also select specifically which
# kernel networking devices to use. # kernel networking devices to use.
devices = wlan0,eth1 devices = wlan0,eth1
# Or let AutoInterface use all suitable # Or let AutoInterface use all suitable
# devices except for a list of ignored ones. # devices except for a list of ignored ones.
ignored_devices = tun0,eth0 ignored_devices = tun0,eth0
@ -95,7 +103,7 @@ the discovery scope by setting it to one of ``link``, ``admin``, ``site``,
[[Default Interface]] [[Default Interface]]
type = AutoInterface type = AutoInterface
interface_enabled = True enabled = yes
# Configure global discovery # Configure global discovery
@ -108,73 +116,114 @@ the discovery scope by setting it to one of ``link``, ``admin``, ``site``,
data_port = 49555 data_port = 49555
.. _interfaces-i2p: .. _interfaces-backbone:
I2P Interface Backbone Interface
============= ====================
The I2P interface lets you connect Reticulum instances over the The Backbone interface is a very fast and resource efficient interface type, primarily
`Invisible Internet Protocol <https://i2pd.website>`_. This can be intended for interconnecting Reticulum instances over many different types of mediums.
especially useful in cases where you want to host a globally reachable It uses a kernel-event I/O backend, and can handle thousands of interfaces and/or clients
Reticulum instance, but do not have access to any public IP addresses, with relatively low system resource utilisation. **This interface type is currently only
have a frequently changing IP address, or have firewalls blocking supported on Linux and Android**.
inbound traffic.
Using the I2P interface, you will get a globally reachable, portable
and persistent I2P address that your Reticulum instance can be reached
at.
To use the I2P interface, you must have an I2P router running
on your system. The easiest way to achieve this is to download and
install the `latest release <https://github.com/PurpleI2P/i2pd/releases/latest>`_
of the ``i2pd`` package. For more details about I2P, see the
`geti2p.net website <https://geti2p.net/en/about/intro>`_.
When an I2P router is running on your system, you can simply add
an I2P interface to Reticulum:
.. code::
[[I2P]]
type = I2PInterface
interface_enabled = yes
connectable = yes
On the first start, Reticulum will generate a new I2P address for the
interface and start listening for inbound traffic on it. This can take
a while the first time, especially if your I2P router was also just
started, and is not yet well-connected to the I2P network. When ready,
you should see I2P base32 address printed to your log file. You can
also inspect the status of the interface using the ``rnstatus`` utility.
To connect to other Reticulum instances over I2P, just add a comma-separated
list of I2P base32 addresses to the ``peers`` option of the interface:
.. code::
[[I2P]]
type = I2PInterface
interface_enabled = yes
connectable = yes
peers = 5urvjicpzi7q3ybztsef4i5ow2aq4soktfj7zedz53s47r54jnqq.b32.i2p
It can take anywhere from a few seconds to a few minutes to establish
I2P connections to the desired peers, so Reticulum handles the process
in the background, and will output relevant events to the log.
.. note:: .. note::
While the I2P interface is the simplest way to use The Backbone Interface is fully compatible with the ``TCPServerInterface`` and ``TCPClientInterface``
Reticulum over I2P, it is also possible to tunnel the TCP server and types, and they can be used interchangably, and cross-connect with each other. On systems that support
client interfaces over I2P manually. This can be useful in situations ``BackboneInterface``, it is generally recommended to use it, unless you need specific options or
where more control is needed, but requires manual tunnel setup through features that the TCP server and client interfaces provide.
the I2P daemon configuration.
It is important to note that the two methods are *interchangably compatible*. While the goal is to support *all* socket types and I/O devices provided by the underlying
You can use the I2PInterface to connect to a TCPServerInterface that operating system, the initial release only provides support for TCP connections over IPv4
was manually tunneled over I2P, for example. This offers a high degree and IPv6.
of flexibility in network setup, while retaining ease of use in simpler
use-cases.
For all types of connections over a ``BackboneInterface``, Reticulum will gracefully
handle intermittency, link loss, and connections that come and go.
Listeners
---------
The following examples illustrates various ways to set up ``BackboneInterface`` listeners.
.. code::
# This example demonstrates a backbone interface
# that listens for incoming connections on the
# specified IP address and port number.
[[Backbone Listener]]
type = BackboneInterface
enabled = yes
listen_on = 0.0.0.0
port = 4242
# Alternatively you can bind to a specific IP
[[Backbone Listener]]
type = BackboneInterface
enabled = yes
listen_on = 10.0.0.88
port = 4242
# Or a specific network device
[[Backbone Listener]]
type = BackboneInterface
enabled = yes
device = eth0
port = 4242
If you are using the interface on a device which has both IPv4 and IPv6 addresses available,
you can use the ``prefer_ipv6`` option to bind to the IPv6 address:
.. code::
# This example demonstrates a backbone interface
# listening on the IPv6 address of a specified
# kernel networking device.
[[Backbone Listener]]
type = BackboneInterface
enabled = yes
prefer_ipv6 = yes
device = eth0
port = 4242
To use the ``BackboneInterface`` over `Yggdrasil <https://yggdrasil-network.github.io/>`_, you
can simply specify the Yggdrasil ``tun`` device and a listening port, like so:
.. code::
# This example demonstrates a backbone interface
# listening for connections over Yggdrasil.
[[Yggdrasil Backbone Interface]]
type = BackboneInterface
enabled = yes
device = tun0
port = 4343
Connecting Remotes
------------------
The following examples illustrates various ways to connect to remote ``BackboneInterface`` listeners.
As noted above, ``BackboneInterface`` interfaces can also connect to remote ``TCPServerInterface``,
and as such these interface types can be used interchangably.
.. code::
# Here's an example of a backbone interface that
# connects to a remote listener.
[[Backbone Remote]]
type = BackboneInterface
enabled = yes
remote = amsterdam.connect.reticulum.network
target_port = 4251
To connect to remotes over `Yggdrasil <https://yggdrasil-network.github.io/>`_, simply
specify the target Yggdrasil IPv6 address and port, like so:
.. code::
[[Yggdrasil Remote]]
type = BackboneInterface
enabled = yes
target_host = 201:5d78:af73:5caf:a4de:a79f:3278:71e5
target_port = 4343
.. _interfaces-tcps: .. _interfaces-tcps:
@ -188,28 +237,27 @@ configured, other Reticulum peers can connect to it with a TCP Client interface.
.. code:: .. code::
# This example demonstrates a TCP server interface. # This example demonstrates a TCP server interface.
# It will listen for incoming connections on the # It will listen for incoming connections on all IP
# specified IP address and port number. # interfaces on port 4242.
[[TCP Server Interface]] [[TCP Server Interface]]
type = TCPServerInterface type = TCPServerInterface
interface_enabled = True enabled = yes
# This configuration will listen on all IP
# interfaces on port 4242
listen_ip = 0.0.0.0 listen_ip = 0.0.0.0
listen_port = 4242 listen_port = 4242
# Alternatively you can bind to a specific IP # Alternatively you can bind to a specific IP
[[TCP Server Interface]]
# listen_ip = 10.0.0.88 type = TCPServerInterface
# listen_port = 4242 enabled = yes
listen_ip = 10.0.0.88
listen_port = 4242
# Or a specific network device # Or a specific network device
[[TCP Server Interface]]
# device = eth0 type = TCPServerInterface
# port = 4242 enabled = yes
device = eth0
listen_port = 4242
If you are using the interface on a device which has both IPv4 and IPv6 addresses available, If you are using the interface on a device which has both IPv4 and IPv6 addresses available,
you can use the ``prefer_ipv6`` option to bind to the IPv6 address: you can use the ``prefer_ipv6`` option to bind to the IPv6 address:
@ -222,11 +270,10 @@ you can use the ``prefer_ipv6`` option to bind to the IPv6 address:
[[TCP Server Interface]] [[TCP Server Interface]]
type = TCPServerInterface type = TCPServerInterface
interface_enabled = True enabled = yes
prefer_ipv6 = True
device = eth0 device = eth0
port = 4242 port = 4242
prefer_ipv6 = True
To use the TCP Server Interface over `Yggdrasil <https://yggdrasil-network.github.io/>`_, you To use the TCP Server Interface over `Yggdrasil <https://yggdrasil-network.github.io/>`_, you
can simply specify the Yggdrasil ``tun`` device and a listening port, like so: can simply specify the Yggdrasil ``tun`` device and a listening port, like so:
@ -235,7 +282,7 @@ can simply specify the Yggdrasil ``tun`` device and a listening port, like so:
[[Yggdrasil TCP Server Interface]] [[Yggdrasil TCP Server Interface]]
type = TCPServerInterface type = TCPServerInterface
interface_enabled = yes enabled = yes
device = tun0 device = tun0
listen_port = 4343 listen_port = 4343
@ -247,7 +294,7 @@ can simply specify the Yggdrasil ``tun`` device and a listening port, like so:
[[TCP Server on I2P]] [[TCP Server on I2P]]
type = TCPServerInterface type = TCPServerInterface
interface_enabled = yes enabled = yes
listen_ip = 127.0.0.1 listen_ip = 127.0.0.1
listen_port = 5001 listen_port = 5001
i2p_tunneled = yes i2p_tunneled = yes
@ -260,7 +307,7 @@ control, and using I2P routers running on external systems, this option also exi
TCP Client Interface TCP Client Interface
==================== ====================
To connect to a TCP server interface, you would naturally use the TCP client To connect to a TCP server interface, you can use the TCP client
interface. Many TCP Client interfaces from different peers can connect to the interface. Many TCP Client interfaces from different peers can connect to the
same TCP Server interface at the same time. same TCP Server interface at the same time.
@ -272,10 +319,9 @@ and restore connectivity after a failure, once the other end of a TCP interface
# Here's an example of a TCP Client interface. The # Here's an example of a TCP Client interface. The
# target_host can be a hostname or an IPv4 or IPv6 address. # target_host can be a hostname or an IPv4 or IPv6 address.
[[TCP Client Interface]] [[TCP Client Interface]]
type = TCPClientInterface type = TCPClientInterface
interface_enabled = True enabled = yes
target_host = 127.0.0.1 target_host = 127.0.0.1
target_port = 4242 target_port = 4242
@ -286,7 +332,7 @@ specify the target Yggdrasil IPv6 address and port, like so:
[[Yggdrasil TCP Client Interface]] [[Yggdrasil TCP Client Interface]]
type = TCPClientInterface type = TCPClientInterface
interface_enabled = yes enabled = yes
target_host = 201:5d78:af73:5caf:a4de:a79f:3278:71e5 target_host = 201:5d78:af73:5caf:a4de:a79f:3278:71e5
target_port = 4343 target_port = 4343
@ -301,7 +347,7 @@ software-based soundmodems. To do this, use the ``kiss_framing`` option:
[[TCP KISS Interface]] [[TCP KISS Interface]]
type = TCPClientInterface type = TCPClientInterface
interface_enabled = True enabled = yes
kiss_framing = True kiss_framing = True
target_host = 127.0.0.1 target_host = 127.0.0.1
target_port = 8001 target_port = 8001
@ -321,7 +367,7 @@ intermittent TCP links.
[[TCP Client over I2P]] [[TCP Client over I2P]]
type = TCPClientInterface type = TCPClientInterface
interface_enabled = yes enabled = yes
target_host = 127.0.0.1 target_host = 127.0.0.1
target_port = 5001 target_port = 5001
i2p_tunneled = yes i2p_tunneled = yes
@ -351,7 +397,7 @@ with all other peers on a local area network.
[[UDP Interface]] [[UDP Interface]]
type = UDPInterface type = UDPInterface
interface_enabled = True enabled = yes
listen_ip = 0.0.0.0 listen_ip = 0.0.0.0
listen_port = 4242 listen_port = 4242
@ -389,6 +435,74 @@ with all other peers on a local area network.
# forward_port = 4242 # forward_port = 4242
.. _interfaces-i2p:
I2P Interface
=============
The I2P interface lets you connect Reticulum instances over the
`Invisible Internet Protocol <https://i2pd.website>`_. This can be
especially useful in cases where you want to host a globally reachable
Reticulum instance, but do not have access to any public IP addresses,
have a frequently changing IP address, or have firewalls blocking
inbound traffic.
Using the I2P interface, you will get a globally reachable, portable
and persistent I2P address that your Reticulum instance can be reached
at.
To use the I2P interface, you must have an I2P router running
on your system. The easiest way to achieve this is to download and
install the `latest release <https://github.com/PurpleI2P/i2pd/releases/latest>`_
of the ``i2pd`` package. For more details about I2P, see the
`geti2p.net website <https://geti2p.net/en/about/intro>`_.
When an I2P router is running on your system, you can simply add
an I2P interface to Reticulum:
.. code::
[[I2P]]
type = I2PInterface
enabled = yes
connectable = yes
On the first start, Reticulum will generate a new I2P address for the
interface and start listening for inbound traffic on it. This can take
a while the first time, especially if your I2P router was also just
started, and is not yet well-connected to the I2P network. When ready,
you should see I2P base32 address printed to your log file. You can
also inspect the status of the interface using the ``rnstatus`` utility.
To connect to other Reticulum instances over I2P, just add a comma-separated
list of I2P base32 addresses to the ``peers`` option of the interface:
.. code::
[[I2P]]
type = I2PInterface
enabled = yes
connectable = yes
peers = 5urvjicpzi7q3ybztsef4i5ow2aq4soktfj7zedz53s47r54jnqq.b32.i2p
It can take anywhere from a few seconds to a few minutes to establish
I2P connections to the desired peers, so Reticulum handles the process
in the background, and will output relevant events to the log.
.. note::
While the I2P interface is the simplest way to use
Reticulum over I2P, it is also possible to tunnel the TCP server and
client interfaces over I2P manually. This can be useful in situations
where more control is needed, but requires manual tunnel setup through
the I2P daemon configuration.
It is important to note that the two methods are *interchangably compatible*.
You can use the I2PInterface to connect to a TCPServerInterface that
was manually tunneled over I2P, for example. This offers a high degree
of flexibility in network setup, while retaining ease of use in simpler
use-cases.
.. _interfaces-rnode: .. _interfaces-rnode:
RNode LoRa Interface RNode LoRa Interface
@ -411,7 +525,7 @@ can be used, and offers full control over LoRa parameters.
type = RNodeInterface type = RNodeInterface
# Enable interface if you want use it! # Enable interface if you want use it!
interface_enabled = True enabled = yes
# Serial port for the device # Serial port for the device
port = /dev/ttyUSB0 port = /dev/ttyUSB0
@ -503,7 +617,7 @@ Multi interface can be used to configure sub-interfaces individually.
type = RNodeMultiInterface type = RNodeMultiInterface
# Enable interface if you want to use it! # Enable interface if you want to use it!
interface_enabled = True enabled = yes
# Serial port for the device # Serial port for the device
port = /dev/ttyACM0 port = /dev/ttyACM0
@ -519,7 +633,7 @@ Multi interface can be used to configure sub-interfaces individually.
# A subinterface # A subinterface
[[[High Datarate]]] [[[High Datarate]]]
# Subinterfaces can be enabled and disabled in of themselves # Subinterfaces can be enabled and disabled in of themselves
interface_enabled = True enabled = yes
# Set frequency to 2.4GHz # Set frequency to 2.4GHz
frequency = 2400000000 frequency = 2400000000
@ -561,7 +675,7 @@ Multi interface can be used to configure sub-interfaces individually.
[[[Low Datarate]]] [[[Low Datarate]]]
# Subinterfaces can be enabled and disabled in of themselves # Subinterfaces can be enabled and disabled in of themselves
interface_enabled = True enabled = yes
# Set frequency to 865.6 MHz # Set frequency to 865.6 MHz
frequency = 865600000 frequency = 865600000
@ -614,7 +728,7 @@ directly over a wire-pair, or for using devices such as data radios and lasers.
[[Serial Interface]] [[Serial Interface]]
type = SerialInterface type = SerialInterface
interface_enabled = True enabled = yes
# Serial port for the device # Serial port for the device
port = /dev/ttyUSB0 port = /dev/ttyUSB0
@ -639,7 +753,7 @@ custom hardware or other systems.
[[Pipe Interface]] [[Pipe Interface]]
type = PipeInterface type = PipeInterface
interface_enabled = True enabled = yes
# External command to execute # External command to execute
command = netcat -l 5757 command = netcat -l 5757
@ -670,7 +784,7 @@ for station identification purposes.
[[Packet Radio KISS Interface]] [[Packet Radio KISS Interface]]
type = KISSInterface type = KISSInterface
interface_enabled = True enabled = yes
# Serial port for the device # Serial port for the device
port = /dev/ttyUSB1 port = /dev/ttyUSB1
@ -744,7 +858,7 @@ beaconing functionality described above.
ssid = 0 ssid = 0
# Enable interface if you want use it! # Enable interface if you want use it!
interface_enabled = True enabled = yes
# Serial port for the device # Serial port for the device
port = /dev/ttyUSB2 port = /dev/ttyUSB2

7
docs/manual/index.html
View file

@ -342,10 +342,15 @@ to participate in the development of Reticulum itself.</p>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a><ul> <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a><ul>
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#custom-interfaces">Custom Interfaces</a></li> <li class="toctree-l2"><a class="reference internal" href="interfaces.html#custom-interfaces">Custom Interfaces</a></li>
<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#auto-interface">Auto Interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#i2p-interface">I2P Interface</a></li> <li class="toctree-l2"><a class="reference internal" href="interfaces.html#backbone-interface">Backbone Interface</a><ul>
<li class="toctree-l3"><a class="reference internal" href="interfaces.html#listeners">Listeners</a></li>
<li class="toctree-l3"><a class="reference internal" href="interfaces.html#connecting-remotes">Connecting Remotes</a></li>
</ul>
</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>
<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#i2p-interface">I2P Interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#rnode-lora-interface">RNode LoRa Interface</a></li> <li class="toctree-l2"><a class="reference internal" href="interfaces.html#rnode-lora-interface">RNode LoRa Interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#rnode-multi-interface">RNode Multi Interface</a></li> <li class="toctree-l2"><a class="reference internal" href="interfaces.html#rnode-multi-interface">RNode Multi Interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="interfaces.html#serial-interface">Serial Interface</a></li> <li class="toctree-l2"><a class="reference internal" href="interfaces.html#serial-interface">Serial Interface</a></li>

307
docs/manual/interfaces.html
View file

@ -243,50 +243,57 @@ example for basic interface code to build upon.</p>
<section id="auto-interface"> <section id="auto-interface">
<span id="interfaces-auto"></span><h2>Auto Interface<a class="headerlink" href="#auto-interface" title="Permalink to this heading">#</a></h2> <span id="interfaces-auto"></span><h2>Auto Interface<a class="headerlink" href="#auto-interface" title="Permalink to this heading">#</a></h2>
<p>The Auto Interface enables communication with other discoverable Reticulum <p>The Auto Interface enables communication with other discoverable Reticulum
nodes over autoconfigured IPv6 and UDP. It does not need any functional IP nodes over autoconfigured IPv6 and UDP. Even though it uses IPv6 for peer
infrastructure like routers or DHCP servers, but will require at least some discovery, and UDP for packet transport, it <strong>does not</strong> need any functional IP
sort of switching medium between peers (a wired switch, a hub, a WiFi access infrastructure like routers or DHCP servers, on your physical network.</p>
point or similar), and that link-local IPv6 is enabled in your operating <p>As long as there is at least some sort of switching medium present between peers (a
system, which should be enabled by default in almost all OSes.</p> wired switch, a hub, a WiFi access point or similar), it will work without
any configuration, setup or intermediary devices.</p>
<p>For <code class="docutils literal notranslate"><span class="pre">AutoInterface</span></code> peer discovery to work, it’s also required that link-local
IPv6 support is available on your system, which it should be by default in all
current operating systems, both desktop and mobile.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Almost all current Ethernet and WiFi hardware will work without any kind
of configuration or setup with <code class="docutils literal notranslate"><span class="pre">AutoInterface</span></code>, but a small subset of
devices turn on options that limit device-to-device communication by default,
resulting in <code class="docutils literal notranslate"><span class="pre">AutoInterface</span></code> peer discovery being blocked. This issue is
most commonly seen on very cheap, ISP-supplied WiFi routers, and can sometimes
be turned off in the router configuration.</p>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a bare-minimum setup</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a bare-minimum setup</span>
<span class="c1"># of an Auto Interface. It will allow communica-</span> <span class="c1"># of an Auto Interface. It will allow communica-</span>
<span class="c1"># tion with all other reachable devices on all</span> <span class="c1"># tion with all other reachable devices on all</span>
<span class="c1"># usable physical ethernet-based devices that</span> <span class="c1"># usable physical ethernet-based devices that</span>
<span class="c1"># are available on the system.</span> <span class="c1"># are available on the system.</span>
<span class="p">[[</span><span class="n">Default</span> <span class="n">Interface</span><span class="p">]]</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="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">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="c1"># This example demonstrates an more specifically</span> <span class="c1"># This example demonstrates an more specifically</span>
<span class="c1"># configured Auto Interface, that only uses spe-</span> <span class="c1"># configured Auto Interface, that only uses spe-</span>
<span class="c1"># cific physical interfaces, and has a number of</span> <span class="c1"># cific physical interfaces, and has a number of</span>
<span class="c1"># other configuration options set.</span> <span class="c1"># other configuration options set.</span>
<span class="p">[[</span><span class="n">Default</span> <span class="n">Interface</span><span class="p">]]</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="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">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="c1"># You can create multiple isolated Reticulum</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"># networks on the same physical LAN by</span>
<span class="c1"># specifying different Group IDs.</span> <span class="c1"># specifying different Group IDs.</span>
<span class="n">group_id</span> <span class="o">=</span> <span class="n">reticulum</span> <span class="n">group_id</span> <span class="o">=</span> <span class="n">reticulum</span>
<span class="c1"># You can also choose the multicast address type:</span> <span class="c1"># You can also choose the multicast address type:</span>
<span class="c1"># temporary (default, Temporary Multicast Address)</span> <span class="c1"># temporary (default, Temporary Multicast Address)</span>
<span class="c1"># or permanent (Permanent Multicast Address)</span> <span class="c1"># or permanent (Permanent Multicast Address)</span>
<span class="n">multicast_address_type</span> <span class="o">=</span> <span class="n">permanent</span> <span class="n">multicast_address_type</span> <span class="o">=</span> <span class="n">permanent</span>
<span class="c1"># You can also select specifically which</span> <span class="c1"># You can also select specifically which</span>
<span class="c1"># kernel networking devices to use.</span> <span class="c1"># kernel networking devices to use.</span>
<span class="n">devices</span> <span class="o">=</span> <span class="n">wlan0</span><span class="p">,</span><span class="n">eth1</span> <span class="n">devices</span> <span class="o">=</span> <span class="n">wlan0</span><span class="p">,</span><span class="n">eth1</span>
<span class="c1"># Or let AutoInterface use all suitable</span> <span class="c1"># Or let AutoInterface use all suitable</span>
<span class="c1"># devices except for a list of ignored ones.</span> <span class="c1"># devices except for a list of ignored ones.</span>
<span class="n">ignored_devices</span> <span class="o">=</span> <span class="n">tun0</span><span class="p">,</span><span class="n">eth0</span> <span class="n">ignored_devices</span> <span class="o">=</span> <span class="n">tun0</span><span class="p">,</span><span class="n">eth0</span>
</pre></div> </pre></div>
</div> </div>
@ -297,7 +304,7 @@ the discovery scope by setting it to one of <code class="docutils literal notran
<code class="docutils literal notranslate"><span class="pre">organisation</span></code> or <code class="docutils literal notranslate"><span class="pre">global</span></code>.</p> <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> <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="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">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="c1"># Configure global discovery</span> <span class="c1"># Configure global discovery</span>
@ -311,61 +318,101 @@ the discovery scope by setting it to one of <code class="docutils literal notran
</pre></div> </pre></div>
</div> </div>
</section> </section>
<section id="i2p-interface"> <section id="backbone-interface">
<span id="interfaces-i2p"></span><h2>I2P Interface<a class="headerlink" href="#i2p-interface" title="Permalink to this heading">#</a></h2> <span id="interfaces-backbone"></span><h2>Backbone Interface<a class="headerlink" href="#backbone-interface" title="Permalink to this heading">#</a></h2>
<p>The I2P interface lets you connect Reticulum instances over the <p>The Backbone interface is a very fast and resource efficient interface type, primarily
<a class="reference external" href="https://i2pd.website">Invisible Internet Protocol</a>. This can be intended for interconnecting Reticulum instances over many different types of mediums.
especially useful in cases where you want to host a globally reachable It uses a kernel-event I/O backend, and can handle thousands of interfaces and/or clients
Reticulum instance, but do not have access to any public IP addresses, with relatively low system resource utilisation. <strong>This interface type is currently only
have a frequently changing IP address, or have firewalls blocking supported on Linux and Android</strong>.</p>
inbound traffic.</p>
<p>Using the I2P interface, you will get a globally reachable, portable
and persistent I2P address that your Reticulum instance can be reached
at.</p>
<p>To use the I2P interface, you must have an I2P router running
on your system. The easiest way to achieve this is to download and
install the <a class="reference external" href="https://github.com/PurpleI2P/i2pd/releases/latest">latest release</a>
of the <code class="docutils literal notranslate"><span class="pre">i2pd</span></code> package. For more details about I2P, see the
<a class="reference external" href="https://geti2p.net/en/about/intro">geti2p.net website</a>.</p>
<p>When an I2P router is running on your system, you can simply add
an I2P interface to Reticulum:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">I2P</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">I2PInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">connectable</span> <span class="o">=</span> <span class="n">yes</span>
</pre></div>
</div>
<p>On the first start, Reticulum will generate a new I2P address for the
interface and start listening for inbound traffic on it. This can take
a while the first time, especially if your I2P router was also just
started, and is not yet well-connected to the I2P network. When ready,
you should see I2P base32 address printed to your log file. You can
also inspect the status of the interface using the <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code> utility.</p>
<p>To connect to other Reticulum instances over I2P, just add a comma-separated
list of I2P base32 addresses to the <code class="docutils literal notranslate"><span class="pre">peers</span></code> option of the interface:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">I2P</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">I2PInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">connectable</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">peers</span> <span class="o">=</span> <span class="mi">5</span><span class="n">urvjicpzi7q3ybztsef4i5ow2aq4soktfj7zedz53s47r54jnqq</span><span class="o">.</span><span class="n">b32</span><span class="o">.</span><span class="n">i2p</span>
</pre></div>
</div>
<p>It can take anywhere from a few seconds to a few minutes to establish
I2P connections to the desired peers, so Reticulum handles the process
in the background, and will output relevant events to the log.</p>
<div class="admonition note"> <div class="admonition note">
<p class="admonition-title">Note</p> <p class="admonition-title">Note</p>
<p>While the I2P interface is the simplest way to use <p>The Backbone Interface is fully compatible with the <code class="docutils literal notranslate"><span class="pre">TCPServerInterface</span></code> and <code class="docutils literal notranslate"><span class="pre">TCPClientInterface</span></code>
Reticulum over I2P, it is also possible to tunnel the TCP server and types, and they can be used interchangably, and cross-connect with each other. On systems that support
client interfaces over I2P manually. This can be useful in situations <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code>, it is generally recommended to use it, unless you need specific options or
where more control is needed, but requires manual tunnel setup through features that the TCP server and client interfaces provide.</p>
the I2P daemon configuration.</p>
</div> </div>
<p>It is important to note that the two methods are <em>interchangably compatible</em>. <p>While the goal is to support <em>all</em> socket types and I/O devices provided by the underlying
You can use the I2PInterface to connect to a TCPServerInterface that operating system, the initial release only provides support for TCP connections over IPv4
was manually tunneled over I2P, for example. This offers a high degree and IPv6.</p>
of flexibility in network setup, while retaining ease of use in simpler <p>For all types of connections over a <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code>, Reticulum will gracefully
use-cases.</p> handle intermittency, link loss, and connections that come and go.</p>
<section id="listeners">
<h3>Listeners<a class="headerlink" href="#listeners" title="Permalink to this heading">#</a></h3>
<p>The following examples illustrates various ways to set up <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code> listeners.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a backbone interface</span>
<span class="c1"># that listens for incoming connections on the</span>
<span class="c1"># specified IP address and port number.</span>
<span class="p">[[</span><span class="n">Backbone</span> <span class="n">Listener</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">BackboneInterface</span>
<span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">listen_on</span> <span class="o">=</span> <span class="mf">0.0.0.0</span>
<span class="n">port</span> <span class="o">=</span> <span class="mi">4242</span>
<span class="c1"># Alternatively you can bind to a specific IP</span>
<span class="p">[[</span><span class="n">Backbone</span> <span class="n">Listener</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">BackboneInterface</span>
<span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">listen_on</span> <span class="o">=</span> <span class="mf">10.0.0.88</span>
<span class="n">port</span> <span class="o">=</span> <span class="mi">4242</span>
<span class="c1"># Or a specific network device</span>
<span class="p">[[</span><span class="n">Backbone</span> <span class="n">Listener</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">BackboneInterface</span>
<span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">device</span> <span class="o">=</span> <span class="n">eth0</span>
<span class="n">port</span> <span class="o">=</span> <span class="mi">4242</span>
</pre></div>
</div>
<p>If you are using the interface on a device which has both IPv4 and IPv6 addresses available,
you can use the <code class="docutils literal notranslate"><span class="pre">prefer_ipv6</span></code> option to bind to the IPv6 address:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a backbone interface</span>
<span class="c1"># listening on the IPv6 address of a specified</span>
<span class="c1"># kernel networking device.</span>
<span class="p">[[</span><span class="n">Backbone</span> <span class="n">Listener</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">BackboneInterface</span>
<span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">prefer_ipv6</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">device</span> <span class="o">=</span> <span class="n">eth0</span>
<span class="n">port</span> <span class="o">=</span> <span class="mi">4242</span>
</pre></div>
</div>
<p>To use the <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code> over <a class="reference external" href="https://yggdrasil-network.github.io/">Yggdrasil</a>, you
can simply specify the Yggdrasil <code class="docutils literal notranslate"><span class="pre">tun</span></code> device and a listening port, like so:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a backbone interface</span>
<span class="c1"># listening for connections over Yggdrasil.</span>
<span class="p">[[</span><span class="n">Yggdrasil</span> <span class="n">Backbone</span> <span class="n">Interface</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">BackboneInterface</span>
<span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">device</span> <span class="o">=</span> <span class="n">tun0</span>
<span class="n">port</span> <span class="o">=</span> <span class="mi">4343</span>
</pre></div>
</div>
</section>
<section id="connecting-remotes">
<h3>Connecting Remotes<a class="headerlink" href="#connecting-remotes" title="Permalink to this heading">#</a></h3>
<p>The following examples illustrates various ways to connect to remote <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code> listeners.
As noted above, <code class="docutils literal notranslate"><span class="pre">BackboneInterface</span></code> interfaces can also connect to remote <code class="docutils literal notranslate"><span class="pre">TCPServerInterface</span></code>,
and as such these interface types can be used interchangably.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Here&#39;s an example of a backbone interface that</span>
<span class="c1"># connects to a remote listener.</span>
<span class="p">[[</span><span class="n">Backbone</span> <span class="n">Remote</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">BackboneInterface</span>
<span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">remote</span> <span class="o">=</span> <span class="n">amsterdam</span><span class="o">.</span><span class="n">connect</span><span class="o">.</span><span class="n">reticulum</span><span class="o">.</span><span class="n">network</span>
<span class="n">target_port</span> <span class="o">=</span> <span class="mi">4251</span>
</pre></div>
</div>
<p>To connect to remotes over <a class="reference external" href="https://yggdrasil-network.github.io/">Yggdrasil</a>, simply
specify the target Yggdrasil IPv6 address and port, like so:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Yggdrasil</span> <span class="n">Remote</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">BackboneInterface</span>
<span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">target_host</span> <span class="o">=</span> <span class="mi">201</span><span class="p">:</span><span class="mi">5</span><span class="n">d78</span><span class="p">:</span><span class="n">af73</span><span class="p">:</span><span class="mi">5</span><span class="n">caf</span><span class="p">:</span><span class="n">a4de</span><span class="p">:</span><span class="n">a79f</span><span class="p">:</span><span class="mi">3278</span><span class="p">:</span><span class="mf">71e5</span>
<span class="n">target_port</span> <span class="o">=</span> <span class="mi">4343</span>
</pre></div>
</div>
</section>
</section> </section>
<section id="tcp-server-interface"> <section id="tcp-server-interface">
<span id="interfaces-tcps"></span><h2>TCP Server Interface<a class="headerlink" href="#tcp-server-interface" title="Permalink to this heading">#</a></h2> <span id="interfaces-tcps"></span><h2>TCP Server Interface<a class="headerlink" href="#tcp-server-interface" title="Permalink to this heading">#</a></h2>
@ -373,28 +420,27 @@ use-cases.</p>
the Internet or private IPv4 and IPv6 networks. When a TCP server interface has been the Internet or private IPv4 and IPv6 networks. When a TCP server interface has been
configured, other Reticulum peers can connect to it with a TCP Client interface.</p> configured, other Reticulum peers can connect to it with a TCP Client interface.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a TCP server interface.</span> <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"># It will listen for incoming connections on all IP</span>
<span class="c1"># specified IP address and port number.</span> <span class="c1"># interfaces on port 4242.</span>
<span class="p">[[</span><span class="n">TCP</span> <span class="n">Server</span> <span class="n">Interface</span><span class="p">]]</span> <span class="p">[[</span><span class="n">TCP</span> <span class="n">Server</span> <span class="n">Interface</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">TCPServerInterface</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPServerInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span> <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="c1"># This configuration will listen on all IP</span>
<span class="c1"># interfaces on port 4242</span>
<span class="n">listen_ip</span> <span class="o">=</span> <span class="mf">0.0.0.0</span> <span class="n">listen_ip</span> <span class="o">=</span> <span class="mf">0.0.0.0</span>
<span class="n">listen_port</span> <span class="o">=</span> <span class="mi">4242</span> <span class="n">listen_port</span> <span class="o">=</span> <span class="mi">4242</span>
<span class="c1"># Alternatively you can bind to a specific IP</span> <span class="c1"># Alternatively you can bind to a specific IP</span>
<span class="p">[[</span><span class="n">TCP</span> <span class="n">Server</span> <span class="n">Interface</span><span class="p">]]</span>
<span class="c1"># listen_ip = 10.0.0.88</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPServerInterface</span>
<span class="c1"># listen_port = 4242</span> <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">listen_ip</span> <span class="o">=</span> <span class="mf">10.0.0.88</span>
<span class="n">listen_port</span> <span class="o">=</span> <span class="mi">4242</span>
<span class="c1"># Or a specific network device</span> <span class="c1"># Or a specific network device</span>
<span class="p">[[</span><span class="n">TCP</span> <span class="n">Server</span> <span class="n">Interface</span><span class="p">]]</span>
<span class="c1"># device = eth0</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPServerInterface</span>
<span class="c1"># port = 4242</span> <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">device</span> <span class="o">=</span> <span class="n">eth0</span>
<span class="n">listen_port</span> <span class="o">=</span> <span class="mi">4242</span>
</pre></div> </pre></div>
</div> </div>
<p>If you are using the interface on a device which has both IPv4 and IPv6 addresses available, <p>If you are using the interface on a device which has both IPv4 and IPv6 addresses available,
@ -405,18 +451,17 @@ you can use the <code class="docutils literal notranslate"><span class="pre">pre
<span class="p">[[</span><span class="n">TCP</span> <span class="n">Server</span> <span class="n">Interface</span><span class="p">]]</span> <span class="p">[[</span><span class="n">TCP</span> <span class="n">Server</span> <span class="n">Interface</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">TCPServerInterface</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPServerInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span> <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">prefer_ipv6</span> <span class="o">=</span> <span class="kc">True</span>
<span class="n">device</span> <span class="o">=</span> <span class="n">eth0</span> <span class="n">device</span> <span class="o">=</span> <span class="n">eth0</span>
<span class="n">port</span> <span class="o">=</span> <span class="mi">4242</span> <span class="n">port</span> <span class="o">=</span> <span class="mi">4242</span>
<span class="n">prefer_ipv6</span> <span class="o">=</span> <span class="kc">True</span>
</pre></div> </pre></div>
</div> </div>
<p>To use the TCP Server Interface over <a class="reference external" href="https://yggdrasil-network.github.io/">Yggdrasil</a>, you <p>To use the TCP Server Interface over <a class="reference external" href="https://yggdrasil-network.github.io/">Yggdrasil</a>, you
can simply specify the Yggdrasil <code class="docutils literal notranslate"><span class="pre">tun</span></code> device and a listening port, like so:</p> can simply specify the Yggdrasil <code class="docutils literal notranslate"><span class="pre">tun</span></code> device and a listening port, like so:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Yggdrasil</span> <span class="n">TCP</span> <span class="n">Server</span> <span class="n">Interface</span><span class="p">]]</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Yggdrasil</span> <span class="n">TCP</span> <span class="n">Server</span> <span class="n">Interface</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">TCPServerInterface</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPServerInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="n">yes</span> <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">device</span> <span class="o">=</span> <span class="n">tun0</span> <span class="n">device</span> <span class="o">=</span> <span class="n">tun0</span>
<span class="n">listen_port</span> <span class="o">=</span> <span class="mi">4343</span> <span class="n">listen_port</span> <span class="o">=</span> <span class="mi">4343</span>
</pre></div> </pre></div>
@ -428,7 +473,7 @@ you must use the i2p_tunneled option:</p>
</div> </div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">TCP</span> <span class="n">Server</span> <span class="n">on</span> <span class="n">I2P</span><span class="p">]]</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">TCP</span> <span class="n">Server</span> <span class="n">on</span> <span class="n">I2P</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">TCPServerInterface</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPServerInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="n">yes</span> <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">listen_ip</span> <span class="o">=</span> <span class="mf">127.0.0.1</span> <span class="n">listen_ip</span> <span class="o">=</span> <span class="mf">127.0.0.1</span>
<span class="n">listen_port</span> <span class="o">=</span> <span class="mi">5001</span> <span class="n">listen_port</span> <span class="o">=</span> <span class="mi">5001</span>
<span class="n">i2p_tunneled</span> <span class="o">=</span> <span class="n">yes</span> <span class="n">i2p_tunneled</span> <span class="o">=</span> <span class="n">yes</span>
@ -439,7 +484,7 @@ control, and using I2P routers running on external systems, this option also exi
</section> </section>
<section id="tcp-client-interface"> <section id="tcp-client-interface">
<span id="interfaces-tcpc"></span><h2>TCP Client Interface<a class="headerlink" href="#tcp-client-interface" title="Permalink to this heading">#</a></h2> <span id="interfaces-tcpc"></span><h2>TCP Client Interface<a class="headerlink" href="#tcp-client-interface" title="Permalink to this heading">#</a></h2>
<p>To connect to a TCP server interface, you would naturally use the TCP client <p>To connect to a TCP server interface, you can use the TCP client
interface. Many TCP Client interfaces from different peers can connect to the interface. Many TCP Client interfaces from different peers can connect to the
same TCP Server interface at the same time.</p> same TCP Server interface at the same time.</p>
<p>The TCP interface types can also tolerate intermittency in the IP link layer. <p>The TCP interface types can also tolerate intermittency in the IP link layer.
@ -447,10 +492,9 @@ This means that Reticulum will gracefully handle IP links that go up and down,
and restore connectivity after a failure, once the other end of a TCP interface reappears.</p> and restore connectivity after a failure, once the other end of a TCP interface reappears.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Here&#39;s an example of a TCP Client interface. The</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Here&#39;s an example of a TCP Client interface. The</span>
<span class="c1"># target_host can be a hostname or an IPv4 or IPv6 address.</span> <span class="c1"># target_host can be a hostname or an IPv4 or IPv6 address.</span>
<span class="p">[[</span><span class="n">TCP</span> <span class="n">Client</span> <span class="n">Interface</span><span class="p">]]</span> <span class="p">[[</span><span class="n">TCP</span> <span class="n">Client</span> <span class="n">Interface</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span> <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">target_host</span> <span class="o">=</span> <span class="mf">127.0.0.1</span> <span class="n">target_host</span> <span class="o">=</span> <span class="mf">127.0.0.1</span>
<span class="n">target_port</span> <span class="o">=</span> <span class="mi">4242</span> <span class="n">target_port</span> <span class="o">=</span> <span class="mi">4242</span>
</pre></div> </pre></div>
@ -459,7 +503,7 @@ and restore connectivity after a failure, once the other end of a TCP interface
specify the target Yggdrasil IPv6 address and port, like so:</p> specify the target Yggdrasil IPv6 address and port, like so:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Yggdrasil</span> <span class="n">TCP</span> <span class="n">Client</span> <span class="n">Interface</span><span class="p">]]</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Yggdrasil</span> <span class="n">TCP</span> <span class="n">Client</span> <span class="n">Interface</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="n">yes</span> <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">target_host</span> <span class="o">=</span> <span class="mi">201</span><span class="p">:</span><span class="mi">5</span><span class="n">d78</span><span class="p">:</span><span class="n">af73</span><span class="p">:</span><span class="mi">5</span><span class="n">caf</span><span class="p">:</span><span class="n">a4de</span><span class="p">:</span><span class="n">a79f</span><span class="p">:</span><span class="mi">3278</span><span class="p">:</span><span class="mf">71e5</span> <span class="n">target_host</span> <span class="o">=</span> <span class="mi">201</span><span class="p">:</span><span class="mi">5</span><span class="n">d78</span><span class="p">:</span><span class="n">af73</span><span class="p">:</span><span class="mi">5</span><span class="n">caf</span><span class="p">:</span><span class="n">a4de</span><span class="p">:</span><span class="n">a79f</span><span class="p">:</span><span class="mi">3278</span><span class="p">:</span><span class="mf">71e5</span>
<span class="n">target_port</span> <span class="o">=</span> <span class="mi">4343</span> <span class="n">target_port</span> <span class="o">=</span> <span class="mi">4343</span>
</pre></div> </pre></div>
@ -472,7 +516,7 @@ software-based soundmodems. To do this, use the <code class="docutils literal no
<span class="p">[[</span><span class="n">TCP</span> <span class="n">KISS</span> <span class="n">Interface</span><span class="p">]]</span> <span class="p">[[</span><span class="n">TCP</span> <span class="n">KISS</span> <span class="n">Interface</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span> <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">kiss_framing</span> <span class="o">=</span> <span class="kc">True</span> <span class="n">kiss_framing</span> <span class="o">=</span> <span class="kc">True</span>
<span class="n">target_host</span> <span class="o">=</span> <span class="mf">127.0.0.1</span> <span class="n">target_host</span> <span class="o">=</span> <span class="mf">127.0.0.1</span>
<span class="n">target_port</span> <span class="o">=</span> <span class="mi">8001</span> <span class="n">target_port</span> <span class="o">=</span> <span class="mi">8001</span>
@ -491,7 +535,7 @@ you must use the i2p_tunneled option:</p>
</div> </div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">TCP</span> <span class="n">Client</span> <span class="n">over</span> <span class="n">I2P</span><span class="p">]]</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">TCP</span> <span class="n">Client</span> <span class="n">over</span> <span class="n">I2P</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="n">yes</span> <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">target_host</span> <span class="o">=</span> <span class="mf">127.0.0.1</span> <span class="n">target_host</span> <span class="o">=</span> <span class="mf">127.0.0.1</span>
<span class="n">target_port</span> <span class="o">=</span> <span class="mi">5001</span> <span class="n">target_port</span> <span class="o">=</span> <span class="mi">5001</span>
<span class="n">i2p_tunneled</span> <span class="o">=</span> <span class="n">yes</span> <span class="n">i2p_tunneled</span> <span class="o">=</span> <span class="n">yes</span>
@ -517,7 +561,7 @@ easier to use.</p>
<span class="p">[[</span><span class="n">UDP</span> <span class="n">Interface</span><span class="p">]]</span> <span class="p">[[</span><span class="n">UDP</span> <span class="n">Interface</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">UDPInterface</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">UDPInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span> <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">listen_ip</span> <span class="o">=</span> <span class="mf">0.0.0.0</span> <span class="n">listen_ip</span> <span class="o">=</span> <span class="mf">0.0.0.0</span>
<span class="n">listen_port</span> <span class="o">=</span> <span class="mi">4242</span> <span class="n">listen_port</span> <span class="o">=</span> <span class="mi">4242</span>
@ -556,6 +600,62 @@ easier to use.</p>
</pre></div> </pre></div>
</div> </div>
</section> </section>
<section id="i2p-interface">
<span id="interfaces-i2p"></span><h2>I2P Interface<a class="headerlink" href="#i2p-interface" title="Permalink to this heading">#</a></h2>
<p>The I2P interface lets you connect Reticulum instances over the
<a class="reference external" href="https://i2pd.website">Invisible Internet Protocol</a>. This can be
especially useful in cases where you want to host a globally reachable
Reticulum instance, but do not have access to any public IP addresses,
have a frequently changing IP address, or have firewalls blocking
inbound traffic.</p>
<p>Using the I2P interface, you will get a globally reachable, portable
and persistent I2P address that your Reticulum instance can be reached
at.</p>
<p>To use the I2P interface, you must have an I2P router running
on your system. The easiest way to achieve this is to download and
install the <a class="reference external" href="https://github.com/PurpleI2P/i2pd/releases/latest">latest release</a>
of the <code class="docutils literal notranslate"><span class="pre">i2pd</span></code> package. For more details about I2P, see the
<a class="reference external" href="https://geti2p.net/en/about/intro">geti2p.net website</a>.</p>
<p>When an I2P router is running on your system, you can simply add
an I2P interface to Reticulum:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">I2P</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">I2PInterface</span>
<span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">connectable</span> <span class="o">=</span> <span class="n">yes</span>
</pre></div>
</div>
<p>On the first start, Reticulum will generate a new I2P address for the
interface and start listening for inbound traffic on it. This can take
a while the first time, especially if your I2P router was also just
started, and is not yet well-connected to the I2P network. When ready,
you should see I2P base32 address printed to your log file. You can
also inspect the status of the interface using the <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code> utility.</p>
<p>To connect to other Reticulum instances over I2P, just add a comma-separated
list of I2P base32 addresses to the <code class="docutils literal notranslate"><span class="pre">peers</span></code> option of the interface:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">I2P</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">I2PInterface</span>
<span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">connectable</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">peers</span> <span class="o">=</span> <span class="mi">5</span><span class="n">urvjicpzi7q3ybztsef4i5ow2aq4soktfj7zedz53s47r54jnqq</span><span class="o">.</span><span class="n">b32</span><span class="o">.</span><span class="n">i2p</span>
</pre></div>
</div>
<p>It can take anywhere from a few seconds to a few minutes to establish
I2P connections to the desired peers, so Reticulum handles the process
in the background, and will output relevant events to the log.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>While the I2P interface is the simplest way to use
Reticulum over I2P, it is also possible to tunnel the TCP server and
client interfaces over I2P manually. This can be useful in situations
where more control is needed, but requires manual tunnel setup through
the I2P daemon configuration.</p>
</div>
<p>It is important to note that the two methods are <em>interchangably compatible</em>.
You can use the I2PInterface to connect to a TCPServerInterface that
was manually tunneled over I2P, for example. This offers a high degree
of flexibility in network setup, while retaining ease of use in simpler
use-cases.</p>
</section>
<section id="rnode-lora-interface"> <section id="rnode-lora-interface">
<span id="interfaces-rnode"></span><h2>RNode LoRa Interface<a class="headerlink" href="#rnode-lora-interface" title="Permalink to this heading">#</a></h2> <span id="interfaces-rnode"></span><h2>RNode LoRa Interface<a class="headerlink" href="#rnode-lora-interface" title="Permalink to this heading">#</a></h2>
<p>To use Reticulum over LoRa, the <a class="reference external" href="https://unsigned.io/rnode/">RNode</a> interface <p>To use Reticulum over LoRa, the <a class="reference external" href="https://unsigned.io/rnode/">RNode</a> interface
@ -573,7 +673,7 @@ relevant regulation for your location, and to make decisions accordingly.</p>
<span class="nb">type</span> <span class="o">=</span> <span class="n">RNodeInterface</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">RNodeInterface</span>
<span class="c1"># Enable interface if you want use it!</span> <span class="c1"># Enable interface if you want use it!</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span> <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="c1"># Serial port for the device</span> <span class="c1"># Serial port for the device</span>
<span class="n">port</span> <span class="o">=</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">ttyUSB0</span> <span class="n">port</span> <span class="o">=</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">ttyUSB0</span>
@ -661,7 +761,7 @@ relevant regulation for your location, and to make decisions accordingly.</p>
<span class="nb">type</span> <span class="o">=</span> <span class="n">RNodeMultiInterface</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">RNodeMultiInterface</span>
<span class="c1"># Enable interface if you want to use it!</span> <span class="c1"># Enable interface if you want to use it!</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span> <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="c1"># Serial port for the device</span> <span class="c1"># Serial port for the device</span>
<span class="n">port</span> <span class="o">=</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">ttyACM0</span> <span class="n">port</span> <span class="o">=</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">ttyACM0</span>
@ -677,7 +777,7 @@ relevant regulation for your location, and to make decisions accordingly.</p>
<span class="c1"># A subinterface</span> <span class="c1"># A subinterface</span>
<span class="p">[[[</span><span class="n">High</span> <span class="n">Datarate</span><span class="p">]]]</span> <span class="p">[[[</span><span class="n">High</span> <span class="n">Datarate</span><span class="p">]]]</span>
<span class="c1"># Subinterfaces can be enabled and disabled in of themselves</span> <span class="c1"># Subinterfaces can be enabled and disabled in of themselves</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span> <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="c1"># Set frequency to 2.4GHz</span> <span class="c1"># Set frequency to 2.4GHz</span>
<span class="n">frequency</span> <span class="o">=</span> <span class="mi">2400000000</span> <span class="n">frequency</span> <span class="o">=</span> <span class="mi">2400000000</span>
@ -719,7 +819,7 @@ relevant regulation for your location, and to make decisions accordingly.</p>
<span class="p">[[[</span><span class="n">Low</span> <span class="n">Datarate</span><span class="p">]]]</span> <span class="p">[[[</span><span class="n">Low</span> <span class="n">Datarate</span><span class="p">]]]</span>
<span class="c1"># Subinterfaces can be enabled and disabled in of themselves</span> <span class="c1"># Subinterfaces can be enabled and disabled in of themselves</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span> <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="c1"># Set frequency to 865.6 MHz</span> <span class="c1"># Set frequency to 865.6 MHz</span>
<span class="n">frequency</span> <span class="o">=</span> <span class="mi">865600000</span> <span class="n">frequency</span> <span class="o">=</span> <span class="mi">865600000</span>
@ -768,7 +868,7 @@ serial port, that will transparently pass data. Useful for communicating
directly over a wire-pair, or for using devices such as data radios and lasers.</p> directly over a wire-pair, or for using devices such as data radios and lasers.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Serial</span> <span class="n">Interface</span><span class="p">]]</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Serial</span> <span class="n">Interface</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">SerialInterface</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">SerialInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span> <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="c1"># Serial port for the device</span> <span class="c1"># Serial port for the device</span>
<span class="n">port</span> <span class="o">=</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">ttyUSB0</span> <span class="n">port</span> <span class="o">=</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">ttyUSB0</span>
@ -789,7 +889,7 @@ directly over a wire-pair, or for using devices such as data radios and lasers.<
custom hardware or other systems.</p> custom hardware or other systems.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Pipe</span> <span class="n">Interface</span><span class="p">]]</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Pipe</span> <span class="n">Interface</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">PipeInterface</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">PipeInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span> <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="c1"># External command to execute</span> <span class="c1"># External command to execute</span>
<span class="n">command</span> <span class="o">=</span> <span class="n">netcat</span> <span class="o">-</span><span class="n">l</span> <span class="mi">5757</span> <span class="n">command</span> <span class="o">=</span> <span class="n">netcat</span> <span class="o">-</span><span class="n">l</span> <span class="mi">5757</span>
@ -816,7 +916,7 @@ relevant regulation for your location, and to make decisions accordingly.</p>
</div> </div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Packet</span> <span class="n">Radio</span> <span class="n">KISS</span> <span class="n">Interface</span><span class="p">]]</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Packet</span> <span class="n">Radio</span> <span class="n">KISS</span> <span class="n">Interface</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">KISSInterface</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">KISSInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span> <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="c1"># Serial port for the device</span> <span class="c1"># Serial port for the device</span>
<span class="n">port</span> <span class="o">=</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">ttyUSB1</span> <span class="n">port</span> <span class="o">=</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">ttyUSB1</span>
@ -885,7 +985,7 @@ relevant regulation for your location, and to make decisions accordingly.</p>
<span class="n">ssid</span> <span class="o">=</span> <span class="mi">0</span> <span class="n">ssid</span> <span class="o">=</span> <span class="mi">0</span>
<span class="c1"># Enable interface if you want use it!</span> <span class="c1"># Enable interface if you want use it!</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span> <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="c1"># Serial port for the device</span> <span class="c1"># Serial port for the device</span>
<span class="n">port</span> <span class="o">=</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">ttyUSB2</span> <span class="n">port</span> <span class="o">=</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">ttyUSB2</span>
@ -1304,10 +1404,15 @@ to <code class="docutils literal notranslate"><span class="pre">30</span></code>
<li><a class="reference internal" href="#">Configuring Interfaces</a><ul> <li><a class="reference internal" href="#">Configuring Interfaces</a><ul>
<li><a class="reference internal" href="#custom-interfaces">Custom Interfaces</a></li> <li><a class="reference internal" href="#custom-interfaces">Custom Interfaces</a></li>
<li><a class="reference internal" href="#auto-interface">Auto Interface</a></li> <li><a class="reference internal" href="#auto-interface">Auto Interface</a></li>
<li><a class="reference internal" href="#i2p-interface">I2P Interface</a></li> <li><a class="reference internal" href="#backbone-interface">Backbone Interface</a><ul>
<li><a class="reference internal" href="#listeners">Listeners</a></li>
<li><a class="reference internal" href="#connecting-remotes">Connecting Remotes</a></li>
</ul>
</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>
<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="#i2p-interface">I2P Interface</a></li>
<li><a class="reference internal" href="#rnode-lora-interface">RNode LoRa Interface</a></li> <li><a class="reference internal" href="#rnode-lora-interface">RNode LoRa Interface</a></li>
<li><a class="reference internal" href="#rnode-multi-interface">RNode Multi Interface</a></li> <li><a class="reference internal" href="#rnode-multi-interface">RNode Multi Interface</a></li>
<li><a class="reference internal" href="#serial-interface">Serial Interface</a></li> <li><a class="reference internal" href="#serial-interface">Serial Interface</a></li>

BIN
docs/manual/objects.inv
View file

Binary file not shown.

2
docs/manual/searchindex.js
View file

File diff suppressed because one or more lines are too long

332
docs/source/interfaces.rst
View file

@ -35,11 +35,25 @@ Auto Interface
============== ==============
The Auto Interface enables communication with other discoverable Reticulum The Auto Interface enables communication with other discoverable Reticulum
nodes over autoconfigured IPv6 and UDP. It does not need any functional IP nodes over autoconfigured IPv6 and UDP. Even though it uses IPv6 for peer
infrastructure like routers or DHCP servers, but will require at least some discovery, and UDP for packet transport, it **does not** need any functional IP
sort of switching medium between peers (a wired switch, a hub, a WiFi access infrastructure like routers or DHCP servers, on your physical network.
point or similar), and that link-local IPv6 is enabled in your operating
system, which should be enabled by default in almost all OSes. As long as there is at least some sort of switching medium present between peers (a
wired switch, a hub, a WiFi access point or similar), it will work without
any configuration, setup or intermediary devices.
For ``AutoInterface`` peer discovery to work, it's also required that link-local
IPv6 support is available on your system, which it should be by default in all
current operating systems, both desktop and mobile.
.. note::
Almost all current Ethernet and WiFi hardware will work without any kind
of configuration or setup with ``AutoInterface``, but a small subset of
devices turn on options that limit device-to-device communication by default,
resulting in ``AutoInterface`` peer discovery being blocked. This issue is
most commonly seen on very cheap, ISP-supplied WiFi routers, and can sometimes
be turned off in the router configuration.
.. code:: .. code::
@ -48,40 +62,34 @@ system, which should be enabled by default in almost all OSes.
# tion with all other reachable devices on all # tion with all other reachable devices on all
# usable physical ethernet-based devices that # usable physical ethernet-based devices that
# are available on the system. # are available on the system.
[[Default Interface]] [[Default Interface]]
type = AutoInterface type = AutoInterface
interface_enabled = True enabled = yes
# This example demonstrates an more specifically # This example demonstrates an more specifically
# configured Auto Interface, that only uses spe- # configured Auto Interface, that only uses spe-
# cific physical interfaces, and has a number of # cific physical interfaces, and has a number of
# other configuration options set. # other configuration options set.
[[Default Interface]] [[Default Interface]]
type = AutoInterface type = AutoInterface
interface_enabled = True enabled = yes
# You can create multiple isolated Reticulum # You can create multiple isolated Reticulum
# networks on the same physical LAN by # networks on the same physical LAN by
# specifying different Group IDs. # specifying different Group IDs.
group_id = reticulum group_id = reticulum
# You can also choose the multicast address type: # You can also choose the multicast address type:
# temporary (default, Temporary Multicast Address) # temporary (default, Temporary Multicast Address)
# or permanent (Permanent Multicast Address) # or permanent (Permanent Multicast Address)
multicast_address_type = permanent multicast_address_type = permanent
# You can also select specifically which # You can also select specifically which
# kernel networking devices to use. # kernel networking devices to use.
devices = wlan0,eth1 devices = wlan0,eth1
# Or let AutoInterface use all suitable # Or let AutoInterface use all suitable
# devices except for a list of ignored ones. # devices except for a list of ignored ones.
ignored_devices = tun0,eth0 ignored_devices = tun0,eth0
@ -95,7 +103,7 @@ the discovery scope by setting it to one of ``link``, ``admin``, ``site``,
[[Default Interface]] [[Default Interface]]
type = AutoInterface type = AutoInterface
interface_enabled = True enabled = yes
# Configure global discovery # Configure global discovery
@ -108,73 +116,114 @@ the discovery scope by setting it to one of ``link``, ``admin``, ``site``,
data_port = 49555 data_port = 49555
.. _interfaces-i2p: .. _interfaces-backbone:
I2P Interface Backbone Interface
============= ====================
The I2P interface lets you connect Reticulum instances over the The Backbone interface is a very fast and resource efficient interface type, primarily
`Invisible Internet Protocol <https://i2pd.website>`_. This can be intended for interconnecting Reticulum instances over many different types of mediums.
especially useful in cases where you want to host a globally reachable It uses a kernel-event I/O backend, and can handle thousands of interfaces and/or clients
Reticulum instance, but do not have access to any public IP addresses, with relatively low system resource utilisation. **This interface type is currently only
have a frequently changing IP address, or have firewalls blocking supported on Linux and Android**.
inbound traffic.
Using the I2P interface, you will get a globally reachable, portable
and persistent I2P address that your Reticulum instance can be reached
at.
To use the I2P interface, you must have an I2P router running
on your system. The easiest way to achieve this is to download and
install the `latest release <https://github.com/PurpleI2P/i2pd/releases/latest>`_
of the ``i2pd`` package. For more details about I2P, see the
`geti2p.net website <https://geti2p.net/en/about/intro>`_.
When an I2P router is running on your system, you can simply add
an I2P interface to Reticulum:
.. code::
[[I2P]]
type = I2PInterface
interface_enabled = yes
connectable = yes
On the first start, Reticulum will generate a new I2P address for the
interface and start listening for inbound traffic on it. This can take
a while the first time, especially if your I2P router was also just
started, and is not yet well-connected to the I2P network. When ready,
you should see I2P base32 address printed to your log file. You can
also inspect the status of the interface using the ``rnstatus`` utility.
To connect to other Reticulum instances over I2P, just add a comma-separated
list of I2P base32 addresses to the ``peers`` option of the interface:
.. code::
[[I2P]]
type = I2PInterface
interface_enabled = yes
connectable = yes
peers = 5urvjicpzi7q3ybztsef4i5ow2aq4soktfj7zedz53s47r54jnqq.b32.i2p
It can take anywhere from a few seconds to a few minutes to establish
I2P connections to the desired peers, so Reticulum handles the process
in the background, and will output relevant events to the log.
.. note:: .. note::
While the I2P interface is the simplest way to use The Backbone Interface is fully compatible with the ``TCPServerInterface`` and ``TCPClientInterface``
Reticulum over I2P, it is also possible to tunnel the TCP server and types, and they can be used interchangably, and cross-connect with each other. On systems that support
client interfaces over I2P manually. This can be useful in situations ``BackboneInterface``, it is generally recommended to use it, unless you need specific options or
where more control is needed, but requires manual tunnel setup through features that the TCP server and client interfaces provide.
the I2P daemon configuration.
It is important to note that the two methods are *interchangably compatible*. While the goal is to support *all* socket types and I/O devices provided by the underlying
You can use the I2PInterface to connect to a TCPServerInterface that operating system, the initial release only provides support for TCP connections over IPv4
was manually tunneled over I2P, for example. This offers a high degree and IPv6.
of flexibility in network setup, while retaining ease of use in simpler
use-cases.
For all types of connections over a ``BackboneInterface``, Reticulum will gracefully
handle intermittency, link loss, and connections that come and go.
Listeners
---------
The following examples illustrates various ways to set up ``BackboneInterface`` listeners.
.. code::
# This example demonstrates a backbone interface
# that listens for incoming connections on the
# specified IP address and port number.
[[Backbone Listener]]
type = BackboneInterface
enabled = yes
listen_on = 0.0.0.0
port = 4242
# Alternatively you can bind to a specific IP
[[Backbone Listener]]
type = BackboneInterface
enabled = yes
listen_on = 10.0.0.88
port = 4242
# Or a specific network device
[[Backbone Listener]]
type = BackboneInterface
enabled = yes
device = eth0
port = 4242
If you are using the interface on a device which has both IPv4 and IPv6 addresses available,
you can use the ``prefer_ipv6`` option to bind to the IPv6 address:
.. code::
# This example demonstrates a backbone interface
# listening on the IPv6 address of a specified
# kernel networking device.
[[Backbone Listener]]
type = BackboneInterface
enabled = yes
prefer_ipv6 = yes
device = eth0
port = 4242
To use the ``BackboneInterface`` over `Yggdrasil <https://yggdrasil-network.github.io/>`_, you
can simply specify the Yggdrasil ``tun`` device and a listening port, like so:
.. code::
# This example demonstrates a backbone interface
# listening for connections over Yggdrasil.
[[Yggdrasil Backbone Interface]]
type = BackboneInterface
enabled = yes
device = tun0
port = 4343
Connecting Remotes
------------------
The following examples illustrates various ways to connect to remote ``BackboneInterface`` listeners.
As noted above, ``BackboneInterface`` interfaces can also connect to remote ``TCPServerInterface``,
and as such these interface types can be used interchangably.
.. code::
# Here's an example of a backbone interface that
# connects to a remote listener.
[[Backbone Remote]]
type = BackboneInterface
enabled = yes
remote = amsterdam.connect.reticulum.network
target_port = 4251
To connect to remotes over `Yggdrasil <https://yggdrasil-network.github.io/>`_, simply
specify the target Yggdrasil IPv6 address and port, like so:
.. code::
[[Yggdrasil Remote]]
type = BackboneInterface
enabled = yes
target_host = 201:5d78:af73:5caf:a4de:a79f:3278:71e5
target_port = 4343
.. _interfaces-tcps: .. _interfaces-tcps:
@ -188,28 +237,27 @@ configured, other Reticulum peers can connect to it with a TCP Client interface.
.. code:: .. code::
# This example demonstrates a TCP server interface. # This example demonstrates a TCP server interface.
# It will listen for incoming connections on the # It will listen for incoming connections on all IP
# specified IP address and port number. # interfaces on port 4242.
[[TCP Server Interface]] [[TCP Server Interface]]
type = TCPServerInterface type = TCPServerInterface
interface_enabled = True enabled = yes
# This configuration will listen on all IP
# interfaces on port 4242
listen_ip = 0.0.0.0 listen_ip = 0.0.0.0
listen_port = 4242 listen_port = 4242
# Alternatively you can bind to a specific IP # Alternatively you can bind to a specific IP
[[TCP Server Interface]]
# listen_ip = 10.0.0.88 type = TCPServerInterface
# listen_port = 4242 enabled = yes
listen_ip = 10.0.0.88
listen_port = 4242
# Or a specific network device # Or a specific network device
[[TCP Server Interface]]
# device = eth0 type = TCPServerInterface
# port = 4242 enabled = yes
device = eth0
listen_port = 4242
If you are using the interface on a device which has both IPv4 and IPv6 addresses available, If you are using the interface on a device which has both IPv4 and IPv6 addresses available,
you can use the ``prefer_ipv6`` option to bind to the IPv6 address: you can use the ``prefer_ipv6`` option to bind to the IPv6 address:
@ -222,11 +270,10 @@ you can use the ``prefer_ipv6`` option to bind to the IPv6 address:
[[TCP Server Interface]] [[TCP Server Interface]]
type = TCPServerInterface type = TCPServerInterface
interface_enabled = True enabled = yes
prefer_ipv6 = True
device = eth0 device = eth0
port = 4242 port = 4242
prefer_ipv6 = True
To use the TCP Server Interface over `Yggdrasil <https://yggdrasil-network.github.io/>`_, you To use the TCP Server Interface over `Yggdrasil <https://yggdrasil-network.github.io/>`_, you
can simply specify the Yggdrasil ``tun`` device and a listening port, like so: can simply specify the Yggdrasil ``tun`` device and a listening port, like so:
@ -235,7 +282,7 @@ can simply specify the Yggdrasil ``tun`` device and a listening port, like so:
[[Yggdrasil TCP Server Interface]] [[Yggdrasil TCP Server Interface]]
type = TCPServerInterface type = TCPServerInterface
interface_enabled = yes enabled = yes
device = tun0 device = tun0
listen_port = 4343 listen_port = 4343
@ -247,7 +294,7 @@ can simply specify the Yggdrasil ``tun`` device and a listening port, like so:
[[TCP Server on I2P]] [[TCP Server on I2P]]
type = TCPServerInterface type = TCPServerInterface
interface_enabled = yes enabled = yes
listen_ip = 127.0.0.1 listen_ip = 127.0.0.1
listen_port = 5001 listen_port = 5001
i2p_tunneled = yes i2p_tunneled = yes
@ -260,7 +307,7 @@ control, and using I2P routers running on external systems, this option also exi
TCP Client Interface TCP Client Interface
==================== ====================
To connect to a TCP server interface, you would naturally use the TCP client To connect to a TCP server interface, you can use the TCP client
interface. Many TCP Client interfaces from different peers can connect to the interface. Many TCP Client interfaces from different peers can connect to the
same TCP Server interface at the same time. same TCP Server interface at the same time.
@ -272,10 +319,9 @@ and restore connectivity after a failure, once the other end of a TCP interface
# Here's an example of a TCP Client interface. The # Here's an example of a TCP Client interface. The
# target_host can be a hostname or an IPv4 or IPv6 address. # target_host can be a hostname or an IPv4 or IPv6 address.
[[TCP Client Interface]] [[TCP Client Interface]]
type = TCPClientInterface type = TCPClientInterface
interface_enabled = True enabled = yes
target_host = 127.0.0.1 target_host = 127.0.0.1
target_port = 4242 target_port = 4242
@ -286,7 +332,7 @@ specify the target Yggdrasil IPv6 address and port, like so:
[[Yggdrasil TCP Client Interface]] [[Yggdrasil TCP Client Interface]]
type = TCPClientInterface type = TCPClientInterface
interface_enabled = yes enabled = yes
target_host = 201:5d78:af73:5caf:a4de:a79f:3278:71e5 target_host = 201:5d78:af73:5caf:a4de:a79f:3278:71e5
target_port = 4343 target_port = 4343
@ -301,7 +347,7 @@ software-based soundmodems. To do this, use the ``kiss_framing`` option:
[[TCP KISS Interface]] [[TCP KISS Interface]]
type = TCPClientInterface type = TCPClientInterface
interface_enabled = True enabled = yes
kiss_framing = True kiss_framing = True
target_host = 127.0.0.1 target_host = 127.0.0.1
target_port = 8001 target_port = 8001
@ -321,7 +367,7 @@ intermittent TCP links.
[[TCP Client over I2P]] [[TCP Client over I2P]]
type = TCPClientInterface type = TCPClientInterface
interface_enabled = yes enabled = yes
target_host = 127.0.0.1 target_host = 127.0.0.1
target_port = 5001 target_port = 5001
i2p_tunneled = yes i2p_tunneled = yes
@ -351,7 +397,7 @@ with all other peers on a local area network.
[[UDP Interface]] [[UDP Interface]]
type = UDPInterface type = UDPInterface
interface_enabled = True enabled = yes
listen_ip = 0.0.0.0 listen_ip = 0.0.0.0
listen_port = 4242 listen_port = 4242
@ -389,6 +435,74 @@ with all other peers on a local area network.
# forward_port = 4242 # forward_port = 4242
.. _interfaces-i2p:
I2P Interface
=============
The I2P interface lets you connect Reticulum instances over the
`Invisible Internet Protocol <https://i2pd.website>`_. This can be
especially useful in cases where you want to host a globally reachable
Reticulum instance, but do not have access to any public IP addresses,
have a frequently changing IP address, or have firewalls blocking
inbound traffic.
Using the I2P interface, you will get a globally reachable, portable
and persistent I2P address that your Reticulum instance can be reached
at.
To use the I2P interface, you must have an I2P router running
on your system. The easiest way to achieve this is to download and
install the `latest release <https://github.com/PurpleI2P/i2pd/releases/latest>`_
of the ``i2pd`` package. For more details about I2P, see the
`geti2p.net website <https://geti2p.net/en/about/intro>`_.
When an I2P router is running on your system, you can simply add
an I2P interface to Reticulum:
.. code::
[[I2P]]
type = I2PInterface
enabled = yes
connectable = yes
On the first start, Reticulum will generate a new I2P address for the
interface and start listening for inbound traffic on it. This can take
a while the first time, especially if your I2P router was also just
started, and is not yet well-connected to the I2P network. When ready,
you should see I2P base32 address printed to your log file. You can
also inspect the status of the interface using the ``rnstatus`` utility.
To connect to other Reticulum instances over I2P, just add a comma-separated
list of I2P base32 addresses to the ``peers`` option of the interface:
.. code::
[[I2P]]
type = I2PInterface
enabled = yes
connectable = yes
peers = 5urvjicpzi7q3ybztsef4i5ow2aq4soktfj7zedz53s47r54jnqq.b32.i2p
It can take anywhere from a few seconds to a few minutes to establish
I2P connections to the desired peers, so Reticulum handles the process
in the background, and will output relevant events to the log.
.. note::
While the I2P interface is the simplest way to use
Reticulum over I2P, it is also possible to tunnel the TCP server and
client interfaces over I2P manually. This can be useful in situations
where more control is needed, but requires manual tunnel setup through
the I2P daemon configuration.
It is important to note that the two methods are *interchangably compatible*.
You can use the I2PInterface to connect to a TCPServerInterface that
was manually tunneled over I2P, for example. This offers a high degree
of flexibility in network setup, while retaining ease of use in simpler
use-cases.
.. _interfaces-rnode: .. _interfaces-rnode:
RNode LoRa Interface RNode LoRa Interface
@ -411,7 +525,7 @@ can be used, and offers full control over LoRa parameters.
type = RNodeInterface type = RNodeInterface
# Enable interface if you want use it! # Enable interface if you want use it!
interface_enabled = True enabled = yes
# Serial port for the device # Serial port for the device
port = /dev/ttyUSB0 port = /dev/ttyUSB0
@ -503,7 +617,7 @@ Multi interface can be used to configure sub-interfaces individually.
type = RNodeMultiInterface type = RNodeMultiInterface
# Enable interface if you want to use it! # Enable interface if you want to use it!
interface_enabled = True enabled = yes
# Serial port for the device # Serial port for the device
port = /dev/ttyACM0 port = /dev/ttyACM0
@ -519,7 +633,7 @@ Multi interface can be used to configure sub-interfaces individually.
# A subinterface # A subinterface
[[[High Datarate]]] [[[High Datarate]]]
# Subinterfaces can be enabled and disabled in of themselves # Subinterfaces can be enabled and disabled in of themselves
interface_enabled = True enabled = yes
# Set frequency to 2.4GHz # Set frequency to 2.4GHz
frequency = 2400000000 frequency = 2400000000
@ -561,7 +675,7 @@ Multi interface can be used to configure sub-interfaces individually.
[[[Low Datarate]]] [[[Low Datarate]]]
# Subinterfaces can be enabled and disabled in of themselves # Subinterfaces can be enabled and disabled in of themselves
interface_enabled = True enabled = yes
# Set frequency to 865.6 MHz # Set frequency to 865.6 MHz
frequency = 865600000 frequency = 865600000
@ -614,7 +728,7 @@ directly over a wire-pair, or for using devices such as data radios and lasers.
[[Serial Interface]] [[Serial Interface]]
type = SerialInterface type = SerialInterface
interface_enabled = True enabled = yes
# Serial port for the device # Serial port for the device
port = /dev/ttyUSB0 port = /dev/ttyUSB0
@ -639,7 +753,7 @@ custom hardware or other systems.
[[Pipe Interface]] [[Pipe Interface]]
type = PipeInterface type = PipeInterface
interface_enabled = True enabled = yes
# External command to execute # External command to execute
command = netcat -l 5757 command = netcat -l 5757
@ -670,7 +784,7 @@ for station identification purposes.
[[Packet Radio KISS Interface]] [[Packet Radio KISS Interface]]
type = KISSInterface type = KISSInterface
interface_enabled = True enabled = yes
# Serial port for the device # Serial port for the device
port = /dev/ttyUSB1 port = /dev/ttyUSB1
@ -744,7 +858,7 @@ beaconing functionality described above.
ssid = 0 ssid = 0
# Enable interface if you want use it! # Enable interface if you want use it!
interface_enabled = True enabled = yes
# Serial port for the device # Serial port for the device
port = /dev/ttyUSB2 port = /dev/ttyUSB2