<spanid="interfaces-main"></span><h1>Configuring Interfaces<aclass="headerlink"href="#configuring-interfaces"title="Permalink to this heading">#</a></h1>
<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-custom"></span><h2>Custom Interfaces<aclass="headerlink"href="#custom-interfaces"title="Permalink to this heading">#</a></h2>
<p>In addition to the built-in interface types, Reticulum is <strong>fully extensible</strong> with
custom, user- or community-supplied interfaces, and creating custom interface
modules is straightforward. Please see the <aclass="reference internal"href="examples.html#example-custominterface"><spanclass="std std-ref">custom interface</span></a>
example for basic interface code to build upon.</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># This example demonstrates a bare-minimum setup</span>
<spanclass="c1"># of an Auto Interface. It will allow communica-</span>
<spanclass="c1"># tion with all other reachable devices on all</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>
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>
<p>If you are using the interface on a device which has both IPv4 and IPv6 addresses available,
you can use the <codeclass="docutils literal notranslate"><spanclass="pre">prefer_ipv6</span></code> option to bind to the IPv6 address:</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>To use the TCP Server Interface over <aclass="reference external"href="https://yggdrasil-network.github.io/">Yggdrasil</a>, you
can simply specify the Yggdrasil <codeclass="docutils literal notranslate"><spanclass="pre">tun</span></code> device and a listening port, like so:</p>
<p>In almost all cases, it is easier to use the dedicated <codeclass="docutils literal notranslate"><spanclass="pre">I2PInterface</span></code>, but for complete
control, and using I2P routers running on external systems, this option also exists.</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># Here's an example of a TCP Client interface. The</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
<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>
<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>
<spanid="interfaces-rnode-multi"></span><h2>RNode Multi Interface<aclass="headerlink"href="#rnode-multi-interface"title="Permalink to this heading">#</a></h2>
<p>For RNodes that support multiple LoRa transceivers, the RNode
Multi interface can be used to configure sub-interfaces individually.</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># Here's an example of how to add an RNode Multi interface</span>
<spanclass="c1"># using the RNode LoRa transceiver.</span>
<p>Reticulum will write all packets to <cite>stdin</cite> of the <codeclass="docutils literal notranslate"><spanclass="pre">command</span></code> option, and will
continuously read and scan its <cite>stdout</cite> for Reticulum packets. If <codeclass="docutils literal notranslate"><spanclass="pre">EOF</span></code> is reached,
Reticulum will try to respawn the program after waiting for <codeclass="docutils literal notranslate"><spanclass="pre">respawn_interval</span></code> seconds.</p>
<spanid="interfaces-options"></span><h2>Common Interface Options<aclass="headerlink"href="#common-interface-options"title="Permalink to this heading">#</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>
<blockquote>
<div><p><em>If an interface exceeds its announce cap, it will queue announces
for later transmission. Reticulum will always prioritise propagating
announces from nearby nodes first. This ensures that the local
topology is prioritised, and that slow networks are not overwhelmed
by interconnected fast networks.</em></p>
<p><em>Destinations that are rapidly re-announcing will be down-prioritised
further. Trying to get “first-in-line” by announce spamming will have
the exact opposite effect: Getting moved to the back of the queue every
time a new announce from the excessively announcing destination is received.</em></p>
<p><em>This means that it is always beneficial to select a balanced
announce rate, and not announce more often than is actually necesarry
for your application to function.</em></p>
</div></blockquote>
</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>
<divclass="line">The <codeclass="docutils literal notranslate"><spanclass="pre">gateway</span></code> mode (or shorthand <codeclass="docutils literal notranslate"><spanclass="pre">gw</span></code>) also has all
discovery, meshing and transport functionality available,
but will additionally try to discover unknown paths on
behalf of other nodes residing on the <codeclass="docutils literal notranslate"><spanclass="pre">gateway</span></code> interface.
If Reticulum receives a path request for an unknown
destination, from a node on a <codeclass="docutils literal notranslate"><spanclass="pre">gateway</span></code> interface, it
will try to discover this path via all other active interfaces,
and forward the discovered path to the requestor if one is
found.</div>
</div>
<divclass="line-block">
<divclass="line">If you want to allow other nodes to widely resolve paths or connect
to a network via an interface, it might be useful to put it in this
mode. By creating a chain of <codeclass="docutils literal notranslate"><spanclass="pre">gateway</span></code> interfaces, other
nodes will be able to immediately discover paths to any
destination along the chain.</div>
</div>
<divclass="line-block">
<divclass="line"><em>Please note!</em> It is the interface <em>facing the clients</em> that
must be put into <codeclass="docutils literal notranslate"><spanclass="pre">gateway</span></code> mode for this to work, not
the interface facing the wider network (for this, the <codeclass="docutils literal notranslate"><spanclass="pre">boundary</span></code>
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>
<spanid="interfaces-announcerates"></span><h2>Announce Rate Control<aclass="headerlink"href="#announce-rate-control"title="Permalink to this heading">#</a></h2>
<p>The built-in announce control mechanisms and the default <codeclass="docutils literal notranslate"><spanclass="pre">announce_cap</span></code>
option described above are sufficient most of the time, but in some cases, especially on fast
interfaces, it may be useful to control the target announce rate. Using the
<codeclass="docutils literal notranslate"><spanclass="pre">announce_rate_target</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">announce_rate_grace</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">announce_rate_penalty</span></code>
options, this can be done on a per-interface basis, and moderates the <em>rate at
which received announces are re-broadcasted to other interfaces</em>.</p>
<blockquote>
<div><ul>
<li><divclass="line-block">
<divclass="line">The <codeclass="docutils literal notranslate"><spanclass="pre">announce_rate_target</span></code> option sets the minimum amount of time,
in seconds, that should pass between received announces, for any one
destination. As an example, setting this value to <codeclass="docutils literal notranslate"><spanclass="pre">3600</span></code> means that
announces <em>received</em> on this interface will only be re-transmitted and
propagated to other interfaces once every hour, no matter how often they
are received.</div>
</div>
</li>
<li><divclass="line-block">
<divclass="line">The optional <codeclass="docutils literal notranslate"><spanclass="pre">announce_rate_grace</span></code> defines the number of times a destination
can violate the announce rate before the target rate is enforced.</div>
</div>
</li>
<li><divclass="line-block">
<divclass="line">The optional <codeclass="docutils literal notranslate"><spanclass="pre">announce_rate_penalty</span></code> configures an extra amount of
time that is added to the normal rate target. As an example, if a penalty
of <codeclass="docutils literal notranslate"><spanclass="pre">7200</span></code> seconds is defined, once the rate target is enforced, the
destination in question will only have its announces propagated every
3 hours, until it lowers its actual announce rate to within the target.</div>
</div>
</li>
</ul>
</div></blockquote>
<p>These mechanisms, in conjunction with the <codeclass="docutils literal notranslate"><spanclass="pre">annouce_cap</span></code> mechanisms mentioned
above means that it is essential to select a balanced announce strategy for
your destinations. The more balanced you can make this decision, the easier
it will be for your destinations to make it into slower networks that many hops
away. Or you can prioritise only reaching high-capacity networks with more frequent
announces.</p>
<p>Current statistics and information about announce rates can be viewed using the
<spanid="interfaces-ingress-control"></span><h2>New Destination Rate Limiting<aclass="headerlink"href="#new-destination-rate-limiting"title="Permalink to this heading">#</a></h2>
occur within a short amount of time, Reticulum will place these announces on hold,
so that announce traffic for known and previously established destinations can
continue to be processed without interruptions.</p>
<p>After the burst subsides, and an additional waiting period has passed, the held
announces will be released at a slow rate, until the hold queue is cleared. This
also means, that should a node decide to connect to a public interface, announce
a large amount of bogus destinations, and then disconnect, these destination will
never make it into path tables and waste network bandwidth on retransmitted
announces.</p>
<p><strong>It’s important to note</strong> that the ingress control works at the level of <em>individual
sub-interfaces</em>. As an example, this means that one client on a <aclass="reference internal"href="#interfaces-tcps"><spanclass="std std-ref">TCP Server Interface</span></a>
cannot disrupt processing of incoming announces for other connected clients on the same
<aclass="reference internal"href="#interfaces-tcps"><spanclass="std std-ref">TCP Server Interface</span></a>. All other clients on the same interface will still have new announces
<divclass="line">The <codeclass="docutils literal notranslate"><spanclass="pre">ic_burst_freq_new</span></code> option sets the maximum announce ingress
frequency for other interfaces. Defaults to <codeclass="docutils literal notranslate"><spanclass="pre">12</span></code> announces
per second.</div>
</div>
<blockquote>
<div><p><em>If an interface exceeds its burst frequency, incoming announces
for unknown destinations will be temporarily held in a queue, and
not processed until later.</em></p>
</div></blockquote>
</li>
<li><divclass="line-block">
<divclass="line">The <codeclass="docutils literal notranslate"><spanclass="pre">ic_max_held_announces</span></code> option sets the maximum amount of
unique announces that will be held in the queue. Any additional
unique announces will be dropped. Defaults to <codeclass="docutils literal notranslate"><spanclass="pre">256</span></code> announces.</div>
</div>
</li>
<li><divclass="line-block">
<divclass="line">The <codeclass="docutils literal notranslate"><spanclass="pre">ic_burst_hold</span></code> option sets how much time (in seconds) must
pass after the burst frequency drops below its threshold, for the
announce burst to be considered cleared. Defaults to <codeclass="docutils literal notranslate"><spanclass="pre">60</span></code>
seconds.</div>
</div>
</li>
<li><divclass="line-block">
<divclass="line">The <codeclass="docutils literal notranslate"><spanclass="pre">ic_burst_penalty</span></code> option sets how much time (in seconds) must
pass after the burst is considered cleared, before held announces can
start being released from the queue. Defaults to <codeclass="docutils literal notranslate"><spanclass="pre">5*60</span></code>
seconds.</div>
</div>
</li>
<li><divclass="line-block">
<divclass="line">The <codeclass="docutils literal notranslate"><spanclass="pre">ic_held_release_interval</span></code> option sets how much time (in seconds)
must pass between releasing each held announce from the queue. Defaults
to <codeclass="docutils literal notranslate"><spanclass="pre">30</span></code> seconds.</div>
