<p>For a high-level overview of how networks can be formed over different interface
types, have a look at the <aclass="reference internal"href="networks.html#networks-main"><spanclass="std std-ref">Building Networks</span></a> chapter of this
<spanid="interfaces-options"></span><h2>Common Interface Options<aclass="headerlink"href="#common-interface-options"title="Permalink to this headline">¶</a></h2>
<p>A number of general configuration options are available on most interfaces.
These can be used to control various aspects of interface behaviour.</p>
<blockquote>
<div><ul>
<li><divclass="line-block">
<divclass="line">The <codeclass="docutils literal notranslate"><spanclass="pre">enabled</span></code> option tells Reticulum whether or not
to bring up the interface. Defaults to <codeclass="docutils literal notranslate"><spanclass="pre">False</span></code>. For any
interface to be brought up, the <codeclass="docutils literal notranslate"><spanclass="pre">enabled</span></code> option
must be set to <codeclass="docutils literal notranslate"><spanclass="pre">True</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">Yes</span></code>.</div>
</div>
</li>
<li><divclass="line-block">
<divclass="line">The <codeclass="docutils literal notranslate"><spanclass="pre">mode</span></code> option allows selecting the high-level behaviour
of the interface from a number of options.</div>
</div>
<blockquote>
<div><ulclass="simple">
<li><p>The default value is <codeclass="docutils literal notranslate"><spanclass="pre">full</span></code>. In this mode, all discovery,
meshing and transport functionality is available.</p></li>
<li><p>In the <codeclass="docutils literal notranslate"><spanclass="pre">access_point</span></code> (or shorthand <codeclass="docutils literal notranslate"><spanclass="pre">ap</span></code>) mode, the
interface will operate as a network access point. In this
mode, announces will not be automatically broadcasted on
the interface, and paths to destinations on the interface
will have a much shorter expiry time. This mode is useful
for creating interfaces that are mostly quiet, unless when
someone is actually using them. An example of this could
be a radio interface serving a wide area, where users are
expected to connect momentarily, use the network, and then
disappear again.</p></li>
</ul>
</div></blockquote>
</li>
<li><divclass="line-block">
<divclass="line">The <codeclass="docutils literal notranslate"><spanclass="pre">outgoing</span></code> option sets whether an interface is allowed
to transmit. Defaults to <codeclass="docutils literal notranslate"><spanclass="pre">True</span></code>. If set to <codeclass="docutils literal notranslate"><spanclass="pre">False</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">No</span></code>
the interface will only receive data, and never transmit.</div>
</div>
</li>
<li><divclass="line-block">
<divclass="line">The <codeclass="docutils literal notranslate"><spanclass="pre">network_name</span></code> option sets the virtual network name for
the interface. This allows multiple separate network segments
to exist on the same physical channel or medium.</div>
</div>
</li>
<li><divclass="line-block">
<divclass="line">The <codeclass="docutils literal notranslate"><spanclass="pre">passphrase</span></code> option sets an authentication passphrase on
the interface. This option can be used in conjunction with the
<codeclass="docutils literal notranslate"><spanclass="pre">network_name</span></code> option, or be used alone.</div>
</div>
</li>
<li><divclass="line-block">
<divclass="line">The <codeclass="docutils literal notranslate"><spanclass="pre">ifac_size</span></code> option allows customising the length of the
Interface Authentication Codes carried by each packet on named
and/or authenticated network segments. It is set by default to
a size suitable for the interface in question, but can be set
to a custom size between 8 and 512 bits by using this option.
In normal usage, this option should not be changed from the
default.</div>
</div>
</li>
<li><divclass="line-block">
<divclass="line">The <codeclass="docutils literal notranslate"><spanclass="pre">announce_cap</span></code> option lets you configure the maximum
bandwidth to allocate, at any given time, to propagating
announces and other network upkeep traffic. It is configured at
2% by default, and should normally not need to be changed. Can
be set to any value between <codeclass="docutils literal notranslate"><spanclass="pre">1</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">100</span></code>.</div>
</div>
</li>
<li><divclass="line-block">
<divclass="line">The <codeclass="docutils literal notranslate"><spanclass="pre">bitrate</span></code> option configures the interface bitrate.
Reticulum will use interface speeds reported by hardware, or
try to guess a suitable rate when the hardware doesn’t report
any. In most cases, the automatically found rate should be
sufficient, but it can be configured by using the <codeclass="docutils literal notranslate"><spanclass="pre">bitrate</span></code>
option, to set the interface speed in <em>bits per second</em>.</div>
<spanid="interfaces-modes"></span><h2>Interface Modes<aclass="headerlink"href="#interface-modes"title="Permalink to this headline">¶</a></h2>
<p>The optional <codeclass="docutils literal notranslate"><spanclass="pre">mode</span></code> option is available on all interfaces, and allows
selecting the high-level behaviour of the interface from a number of modes.
These modes affect how Reticulum selects paths in the network, how announces
are propagated and how long paths are valid.</p>
<p>Configuring modes on interfaces is not strictly necessary, but can be useful
when building or connecting to more complex networks. When not running a
Transport Node, it is rarely useful to configure an interface mode.</p>
<blockquote>
<div><ul>
<li><divclass="line-block">
<divclass="line">The default value is <codeclass="docutils literal notranslate"><spanclass="pre">full</span></code>. In this mode, all discovery,
meshing and transport functionality is activated.</div>
</div>
</li>
<li><divclass="line-block">
<divclass="line">In the <codeclass="docutils literal notranslate"><spanclass="pre">access_point</span></code> (or shorthand <codeclass="docutils literal notranslate"><spanclass="pre">ap</span></code>) mode, the
interface will operate as a network access point. In this
mode, announces will not be automatically broadcasted on
the interface, and paths to destinations on the interface
will have a much shorter expiry time. This mode is useful
for creating interfaces that are mostly quiet, unless when
someone is actually using them. An example of this could
be a radio interface serving a wide area, where users are
expected to connect momentarily, use the network, and then
disappear again.</div>
</div>
</li>
<li><divclass="line-block">
<divclass="line">The <codeclass="docutils literal notranslate"><spanclass="pre">roaming</span></code> mode should be used on interfaces that are
roaming (physically mobile), seen from the perspective of
other nodes in the network. As an example, if a vehicle is
equipped with an external LoRa interface, and an internal,
WiFi-based interface, that serves devices that are moving
_with_ the vehicle, the external LoRa interface should be
configured as <codeclass="docutils literal notranslate"><spanclass="pre">roaming</span></code>, and the internal interface can
be left in the default mode. With transport enabled, such
a setup will allow all internal devices to reach each other,
and all other devices that are available on the LoRa side
of the network, when they are in range. Devices on the LoRa
side of the network will also be able to reach devices
internal to the vehicle, when it is in range. Paths via
<codeclass="docutils literal notranslate"><spanclass="pre">roaming</span></code> interfaces also expire faster.</div>
</div>
</li>
<li><divclass="line-block">
<divclass="line">The purpose of the <codeclass="docutils literal notranslate"><spanclass="pre">boundary</span></code> mode is to specify interfaces
that establish connectivity with network segments that are
significantly different than the one this node exists on.
As an example, if a Reticulum instance is part of a LoRa-based
network, but also has a high-speed connection to a
public Transport Node available on the Internet, the interface
connecting over the Internet should be set to <codeclass="docutils literal notranslate"><spanclass="pre">boundary</span></code> mode.</div>
</div>
</li>
</ul>
</div></blockquote>
<p>For a table describing the impact of all modes on announce propagation,
please see the <aclass="reference internal"href="understanding.html#understanding-announcepropagation"><spanclass="std std-ref">Announce Propagation Rules</span></a> section.</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># This example demonstrates a TCP server interface.</span>
<spanclass="c1"># It will listen for incoming connections on the</span>
<spanclass="c1"># specified IP address and port number.</span>
<p>If you are connected to the Internet with IPv6, and your provider will route
IPv6 multicast, you can potentially configure the Auto Interface to globally
autodiscover other Reticulum nodes within your selected Group ID. You can specify
the discovery scope by setting it to one of <codeclass="docutils literal notranslate"><spanclass="pre">link</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">admin</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">site</span></code>,
<codeclass="docutils literal notranslate"><spanclass="pre">organisation</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">global</span></code>.</p>
<spanid="interfaces-tcps"></span><h2>TCP Server Interface<aclass="headerlink"href="#tcp-server-interface"title="Permalink to this headline">¶</a></h2>
<p>The TCP Server interface is suitable for allowing other peers to connect over
the Internet or private IP networks. When a TCP server interface has been
configured, other Reticulum peers can connect to it with a TCP Client interface.</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># This example demonstrates a TCP server interface.</span>
<spanclass="c1"># It will listen for incoming connections on the</span>
<spanclass="c1"># specified IP address and port number.</span>
<spanid="interfaces-tcpc"></span><h2>TCP Client Interface<aclass="headerlink"href="#tcp-client-interface"title="Permalink to this headline">¶</a></h2>
<p>To connect to a TCP server interface, you would naturally use the TCP client
interface. Many TCP Client interfaces from different peers can connect to the
same TCP Server interface at the same time.</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># Here's an example of a TCP Client interface. The</span>
<spanclass="c1"># target_host can either be an IP address or a hostname.</span>
<p>It is also possible to use this interface type to connect via other programs
or hardware devices that expose a KISS interface on a TCP port, for example
software-based soundmodems. To do this, use the <codeclass="docutils literal notranslate"><spanclass="pre">kiss_framing</span></code> option:</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># Here's an example of a TCP Client interface that connects</span>
<spanclass="c1"># to a software TNC soundmodem on a KISS over TCP port.</span>
<p><strong>Caution!</strong> Only use the KISS framing option when connecting to external devices
and programs like soundmodems and similar over TCP. When using the
<codeclass="docutils literal notranslate"><spanclass="pre">TCPClientInterface</span></code> in conjunction with the <codeclass="docutils literal notranslate"><spanclass="pre">TCPServerInterface</span></code> you should
never enable <codeclass="docutils literal notranslate"><spanclass="pre">kiss_framing</span></code>, since this will disable internal reliability and
recovery mechanisms that greatly improves performance over unreliable and
<spanid="interfaces-udp"></span><h2>UDP Interface<aclass="headerlink"href="#udp-interface"title="Permalink to this headline">¶</a></h2>
<p>A UDP interface can be useful for communicating over IP networks, both
private and the internet. It can also allow broadcast communication
over IP networks, so it can provide an easy way to enable connectivity
with all other peers on a local area network.</p>
<p><em>Please Note!</em> Using broadcast UDP traffic has performance implications,
especially on WiFi. If your goal is simply to enable easy communication
with all peers in your local ethernet broadcast domain, the
<aclass="reference internal"href="#interfaces-auto"><spanclass="std std-ref">Auto Interface</span></a> performs better, and is just as
easy to use.</p>
<p>The below example is enabled by default on new Reticulum installations,
as it provides an easy way to get started and to test Reticulum on a
pre-existing LAN.</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># This example enables communication with other</span>
<spanclass="c1"># local Reticulum peers over UDP.</span>
<spanid="interfaces-rnode"></span><h2>RNode LoRa Interface<aclass="headerlink"href="#rnode-lora-interface"title="Permalink to this headline">¶</a></h2>
<p>To use Reticulum over LoRa, the <aclass="reference external"href="https://unsigned.io/rnode/">RNode</a> interface
can be used, and offers full control over LoRa parameters.</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># Here's an example of how to add a LoRa interface</span>
<spanclass="c1"># using the RNode LoRa transceiver.</span>
