
.. _interfaces-main:

**********************
Configuring Interfaces
**********************

Reticulum supports using many kinds of devices as networking interfaces, and
allows you to mix and match them in any way you choose. The number of distinct
network topologies you can create with Reticulum is more or less endless, but
common to them all is that you will need to define one or more *interfaces*
for Reticulum to use.

The following sections describe the interfaces currently available in Reticulum,
and gives example configurations for the respective interface types.

For a high-level overview of how networks can be formed over different interface
types, have a look at the :ref:`Building Networks<networks-main>` chapter of this
manual.


.. _interfaces-custom:

Custom Interfaces
=================

In addition to the built-in interface types, Reticulum is **fully extensible** with
custom, user- or community-supplied interfaces, and creating custom interface
modules is straightforward. Please see the :ref:`custom interface<example-custominterface>`
example for basic interface code to build upon.

.. _interfaces-auto:

Auto Interface
==============

The ``AutoInterface`` enables communication with other discoverable Reticulum
nodes over any kind of local Ethernet or WiFi-based medium. Even though it uses IPv6 for peer
discovery, and UDP for packet transport, it **does not** need any functional IP
infrastructure like routers or DHCP servers, on your physical network.

.. warning::
  If you have **firewall** software running on your computer, it may block traffic
  required for ``AutoInterface`` to work. If this is the case, you will have to
  allow UDP traffic on port ``29716`` and ``42671``.

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, or simply two devices connected
directly by Ethernet cable), 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:: ini

  # This example demonstrates a bare-minimum setup
  # of an Auto Interface. It will allow communica-
  # tion with all other reachable devices on all
  # usable physical ethernet-based devices that
  # are available on the system.
  [[Default Interface]]
    type = AutoInterface
    enabled = yes

  # This example demonstrates an more specifically
  # configured Auto Interface, that only uses spe-
  # cific physical interfaces, and has a number of
  # other configuration options set.
  [[Default Interface]]
    type = AutoInterface
    enabled = yes

    # You can create multiple isolated Reticulum
    # networks on the same physical LAN by
    # specifying different Group IDs.
    group_id = reticulum

    # You can also choose the multicast address type:
    # temporary (default, Temporary Multicast Address)
    # or permanent (Permanent Multicast Address)
    multicast_address_type = permanent

    # You can also select specifically which
    # kernel networking devices to use.
    devices = wlan0,eth1

    # Or let AutoInterface use all suitable
    # devices except for a list of ignored ones.
    ignored_devices = tun0,eth0


If you are connected to the Internet with IPv6, and your provider will route
IPv6 multicast, you can potentially configure the Auto Interface to globally
autodiscover other Reticulum nodes within your selected Group ID. You can specify
the discovery scope by setting it to one of ``link``, ``admin``, ``site``,
``organisation`` or ``global``.

.. code:: ini
  
  [[Default Interface]]
    type = AutoInterface
    enabled = yes

    # Configure global discovery

    group_id = custom_network_name
    discovery_scope = global

    # Other configuration options

    discovery_port = 48555
    data_port = 49555


.. _interfaces-backbone:

Backbone Interface
====================

The Backbone interface is a very fast and resource efficient interface type, primarily
intended for interconnecting Reticulum instances over many different types of mediums.
It uses a kernel-event I/O backend, and can handle thousands of interfaces and/or clients
with relatively low system resource utilisation. **This interface type is currently only
supported on Linux and Android**.

.. note::
  The Backbone Interface is fully compatible with the ``TCPServerInterface`` and ``TCPClientInterface``
  types, and they can be used interchangably, and cross-connect with each other. On systems that support
  ``BackboneInterface``, it is generally recommended to use it, unless you need specific options or
  features that the TCP server and client interfaces provide.

While the goal is to support *all* socket types and I/O devices provided by the underlying
operating system, the initial release only provides support for TCP connections over IPv4
and IPv6.

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:: ini

  # 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:: ini

  # 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:: ini

  # 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:: ini

  # 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:: ini

  [[Yggdrasil Remote]]
      type = BackboneInterface
      enabled = yes
      target_host = 201:5d78:af73:5caf:a4de:a79f:3278:71e5
      target_port = 4343

Automated Blocking
------------------
Listener instances of ``BackboneInterface`` will automatically block fast-flapping clients,
that repeatedly connect for a short amount of time, and then disconnect. Such behavior usually
occurs from clients trying to spam the network with announces or path requests, by connecting, dumping
a massive amount of requests, and then disconnecting in an attempt to bypass rate limits.

While such bypass attempts only have very limited effect on the amount of spam actually dumped (ingress limits
trigger immediately once a client exceeds rate limits), the behavior is often seen anyways, and
causes log noise and needless interface rotation. The fast-flapping block ensures such clients
are never allocated an interface on the transport instance.

Another common cause can simply be clients using implementations that are broken, or automated
scanning tools attempting to connect to the instance.

.. code:: ini

  [[Backbone Listener]]
    type = BackboneInterface
    enabled = yes    
    listen_on = 0.0.0.0
    port = 4242

    # Whether to enable blocking
    block_fast_flapping = yes

    # How long an IP address stays
    # blocked, in minutes. Set to
    # 12 hours by default.
    fast_flapping_block_time = 720

    # The minimum time, in seconds,
    # an interface must stay connected
    # to be considered not fast-flapping.
    fast_flapping_threshold = 20

    # Amount of fast flaps a remote
    # IP can perform before having
    # blocking triggered.
    fast_flapping_grace = 5

The configuration options listed in the example above are the *default values*, and you do
not need to add them for automated blocking to work, but you can use them to change the
behavior from the defaults, if necessary.

.. _interfaces-tcps:

TCP Server Interface
====================

The TCP Server interface is suitable for allowing other peers to connect over
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.

.. code:: ini

  # This example demonstrates a TCP server interface.
  # It will listen for incoming connections on all IP
  # interfaces on port 4242.  
  [[TCP Server Interface]]
    type = TCPServerInterface
    enabled = yes
    listen_ip = 0.0.0.0
    listen_port = 4242

  # Alternatively you can bind to a specific IP
  [[TCP Server Interface]]
    type = TCPServerInterface
    enabled = yes
    listen_ip = 10.0.0.88
    listen_port = 4242

  # Or a specific network device
  [[TCP Server Interface]]
    type = TCPServerInterface
    enabled = yes    
    device = eth0
    listen_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:: ini

  # This example demonstrates a TCP server interface.
  # It will listen for incoming connections on the
  # specified IP address and port number.
  
  [[TCP Server Interface]]
    type = TCPServerInterface
    enabled = yes
    prefer_ipv6 = True
    device = eth0
    port = 4242

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:

.. code:: ini

  [[Yggdrasil TCP Server Interface]]
    type = TCPServerInterface
    enabled = yes
    device = tun0
    listen_port = 4343

.. note::
   The TCP interfaces support tunneling over I2P, but to do so reliably,
   you must use the i2p_tunneled option:

.. code::

  [[TCP Server on I2P]]
    type = TCPServerInterface
    enabled = yes
    listen_ip = 127.0.0.1
    listen_port = 5001
    i2p_tunneled = yes

In almost all cases, it is easier to use the dedicated ``I2PInterface``, but for complete
control, and using I2P routers running on external systems, this option also exists.

.. _interfaces-tcpc:

TCP Client Interface
====================

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
same TCP Server interface at the same time.

The TCP interface types can also tolerate intermittency in the IP link layer.
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.

.. code:: ini

  # Here's an example of a TCP Client interface. The
  # target_host can be a hostname or an IPv4 or IPv6 address.
  [[TCP Client Interface]]
    type = TCPClientInterface
    enabled = yes
    target_host = 127.0.0.1
    target_port = 4242

To use the TCP Client Interface over `Yggdrasil <https://yggdrasil-network.github.io/>`_, simply
specify the target Yggdrasil IPv6 address and port, like so:

.. code:: ini

  [[Yggdrasil TCP Client Interface]]
      type = TCPClientInterface
      enabled = yes
      target_host = 201:5d78:af73:5caf:a4de:a79f:3278:71e5
      target_port = 4343

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 ``kiss_framing`` option:

.. code:: ini

  # Here's an example of a TCP Client interface that connects
  # to a software TNC soundmodem on a KISS over TCP port.

  [[TCP KISS Interface]]
    type = TCPClientInterface
    enabled = yes
    kiss_framing = True
    target_host = 127.0.0.1
    target_port = 8001
    fixed_mtu = 500

**Caution!** Only use the KISS framing option when connecting to external devices
and programs like soundmodems and similar over TCP. When using the
``TCPClientInterface`` in conjunction with the ``TCPServerInterface`` you should
never enable ``kiss_framing``, since this will disable internal reliability and
recovery mechanisms that greatly improves performance over unreliable and
intermittent TCP links.

For KISS devices that need only supports a particular MTU, you can use the
``fixed_mtu`` option.

.. note::
   The TCP interfaces support tunneling over I2P, but to do so reliably,
   you must use the i2p_tunneled option:

.. code:: ini

  [[TCP Client over I2P]]
      type = TCPClientInterface
      enabled = yes
      target_host = 127.0.0.1
      target_port = 5001
      i2p_tunneled = yes


.. _interfaces-udp:

UDP Interface
=============

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.

.. warning::
   Using broadcast UDP traffic has performance implications,
   especially on WiFi. If your goal is simply to enable easy communication
   with all peers in your local Ethernet broadcast domain, the
   :ref:`Auto Interface<interfaces-auto>` performs *much* better, and is even
   easier to use.

.. code:: ini

  # This example enables communication with other
  # local Reticulum peers over UDP.
  
  [[UDP Interface]]
    type = UDPInterface
    enabled = yes

    listen_ip = 0.0.0.0
    listen_port = 4242
    forward_ip = 255.255.255.255
    forward_port = 4242

    # The above configuration will allow communication
    # within the local broadcast domains of all local
    # IP interfaces.

    # Instead of specifying listen_ip, listen_port,
    # forward_ip and forward_port, you can also bind
    # to a specific network device like below.

    # device = eth0
    # port = 4242

    # Assuming the eth0 device has the address
    # 10.55.0.72/24, the above configuration would
    # be equivalent to the following manual setup.
    # Note that we are both listening and forwarding to
    # the broadcast address of the network segments.

    # listen_ip = 10.55.0.255
    # listen_port = 4242
    # forward_ip = 10.55.0.255
    # forward_port = 4242

    # You can of course also communicate only with
    # a single IP address

    # listen_ip = 10.55.0.15
    # listen_port = 4242
    # forward_ip = 10.55.0.16
    # 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:: ini

  [[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:: ini

  [[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:

RNode LoRa Interface
====================

To use Reticulum over LoRa, the `RNode <https://unsigned.io/rnode/>`_ interface
can be used, and offers full control over LoRa parameters.

.. warning::
   Radio frequency spectrum is a legally controlled resource, and legislation
   varies widely around the world. It is your responsibility to be aware of any
   relevant regulation for your location, and to make decisions accordingly.

.. code:: ini

  # Here's an example of how to add a LoRa interface
  # using the RNode LoRa transceiver.

  [[RNode LoRa Interface]]
    type = RNodeInterface

    # Enable interface if you want use it!
    enabled = yes

    # Serial port for the device
    port = /dev/ttyUSB0

    # You can connect wirelessly to the
    # RNode device if it supports WiFi.

    # Connect by IP address
    # port = tcp://10.0.0.1

    # Or, connect by hostname
    # port = tcp://rnodef3b9.local

    # It is also possible to use BLE devices
    # instead of wired serial ports. The
    # target RNode must be paired with the
    # host device before connecting. BLE
    # devices can be connected by name,
    # BLE MAC address or by any available.
    
    # Connect to specific device by name
    # port = ble://RNode 3B87

    # Or by BLE MAC address
    # port = ble://F4:12:73:29:4E:89

    # Or connect to the first available,
    # paired device
    # port = ble://

    # Set frequency to 867.2 MHz
    frequency = 867200000

    # Set LoRa bandwidth to 125 KHz
    bandwidth = 125000

    # Set TX power to 7 dBm (5 mW)
    txpower = 7

    # Select spreading factor 8. Valid 
    # range is 7 through 12, with 7
    # being the fastest and 12 having
    # the longest range.
    spreadingfactor = 8

    # Select coding rate 5. Valid range
    # is 5 throough 8, with 5 being the
    # fastest, and 8 the longest range.
    codingrate = 5

    # You can configure the RNode to send
    # out identification on the channel with
    # a set interval by configuring the
    # following two parameters.
    
    # id_callsign = MYCALL-0
    # id_interval = 600

    # For certain homebrew RNode interfaces
    # with low amounts of RAM, using packet
    # flow control can be useful. By default
    # it is disabled.
    
    # flow_control = False

    # It is possible to limit the airtime
    # utilisation of an RNode by using the
    # following two configuration options.
    # The short-term limit is applied in a
    # window of approximately 15 seconds,
    # and the long-term limit is enforced
    # over a rolling 60 minute window. Both
    # options are specified in percent.
    
    # airtime_limit_long = 1.5
    # airtime_limit_short = 33


.. _interfaces-rnode-multi:

RNode Multi Interface
=====================

For RNodes that support multiple LoRa transceivers, the RNode
Multi interface can be used to configure sub-interfaces individually.

.. warning::
   Radio frequency spectrum is a legally controlled resource, and legislation
   varies widely around the world. It is your responsibility to be aware of any
   relevant regulation for your location, and to make decisions accordingly.

.. code:: ini

  # Here's an example of how to add an RNode Multi interface
  # using the RNode LoRa transceiver.

  [[RNode Multi Interface]]
  type = RNodeMultiInterface

  # Enable interface if you want to use it!
  enabled = yes

  # Serial port for the device
  port = /dev/ttyACM0

  # You can configure the RNode to send
  # out identification on the channel with
  # a set interval by configuring the
  # following two parameters.

  # id_callsign = MYCALL-0
  # id_interval = 600

    # A subinterface
    [[[High Datarate]]]
      # Subinterfaces can be enabled and disabled in of themselves
      enabled = yes

      # Set frequency to 2.4GHz
      frequency = 2400000000

      # Set LoRa bandwidth to 1625 KHz
      bandwidth = 1625000

      # Set TX power to 0 dBm (0.12 mW)
      txpower = 0

      # The virtual port, only the manufacturer
      # or the person who wrote the board config
      # can tell you what it will be for which
      # physical hardware interface
      vport = 1

      # Select spreading factor 5. Valid
      # range is 5 through 12, with 5 
      # being the fastest and 12 having
      # the longest range.
      spreadingfactor = 5

      # Select coding rate 5. Valid range
      # is 5 throough 8, with 5 being the
      # fastest, and 8 the longest range.
      codingrate = 5

      # It is possible to limit the airtime
      # utilisation of an RNode by using the
      # following two configuration options.
      # The short-term limit is applied in a
      # window of approximately 15 seconds,
      # and the long-term limit is enforced
      # over a rolling 60 minute window. Both
      # options are specified in percent.

      # airtime_limit_long = 100
      # airtime_limit_short = 100

    [[[Low Datarate]]]
      # Subinterfaces can be enabled and disabled in of themselves
      enabled = yes

      # Set frequency to 865.6 MHz
      frequency = 865600000

      # The virtual port, only the manufacturer
      # or the person who wrote the board config
      # can tell you what it will be for which
      # physical hardware interface
      vport = 0

      # Set LoRa bandwidth to 125 KHz
      bandwidth = 125000

      # Set TX power to 0 dBm (0.12 mW)
      txpower = 0

      # Select spreading factor 7. Valid
      # range is 5 through 12, with 5 
      # being the fastest and 12 having
      # the longest range.
      spreadingfactor = 7

      # Select coding rate 5. Valid range
      # is 5 throough 8, with 5 being the
      # fastest, and 8 the longest range.
      codingrate = 5

      # It is possible to limit the airtime
      # utilisation of an RNode by using the
      # following two configuration options.
      # The short-term limit is applied in a
      # window of approximately 15 seconds,
      # and the long-term limit is enforced
      # over a rolling 60 minute window. Both
      # options are specified in percent.

      # airtime_limit_long = 100
      # airtime_limit_short = 100

.. _interfaces-serial:

Serial Interface
================

Reticulum can be used over serial ports directly, or over any device with a
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.

.. code:: ini

  [[Serial Interface]]
    type = SerialInterface
    enabled = yes

    # Serial port for the device
    port = /dev/ttyUSB0

    # Set the serial baud-rate and other
    # configuration parameters.
    speed = 115200
    databits = 8
    parity = none
    stopbits = 1

.. _interfaces-pipe:

Pipe Interface
==============

Using this interface, Reticulum can use any program as an interface via `stdin` and
`stdout`. This can be used to easily create virtual interfaces, or to interface with
custom hardware or other systems.

.. code:: ini

  [[Pipe Interface]]
    type = PipeInterface
    enabled = yes

    # External command to execute
    command = netcat -l 5757

    # Optional respawn delay, in seconds
    respawn_delay = 5

Reticulum will write all packets to `stdin` of the ``command`` option, and will
continuously read and scan its `stdout` for Reticulum packets. If ``EOF`` is reached,
Reticulum will try to respawn the program after waiting for ``respawn_interval`` seconds.

.. _interfaces-kiss:

KISS Interface
==============

With the KISS interface, you can use Reticulum over a variety of packet
radio modems and TNCs, including `OpenModem <https://unsigned.io/openmodem/>`_.
KISS interfaces can also be configured to periodically send out beacons
for station identification purposes.

.. warning::
   Radio frequency spectrum is a legally controlled resource, and legislation
   varies widely around the world. It is your responsibility to be aware of any
   relevant regulation for your location, and to make decisions accordingly.

.. code:: ini

  [[Packet Radio KISS Interface]]
    type = KISSInterface
    enabled = yes

    # Serial port for the device
    port = /dev/ttyUSB1

    # Set the serial baud-rate and other
    # configuration parameters.
    speed = 115200    
    databits = 8
    parity = none
    stopbits = 1

    # Set the modem preamble.
    preamble = 150

    # Set the modem TX tail.
    txtail = 10

    # Configure CDMA parameters. These
    # settings are reasonable defaults.
    persistence = 200
    slottime = 20

    # You can configure the interface to send
    # out identification on the channel with
    # a set interval by configuring the
    # following two parameters. The KISS
    # interface will only ID if the set
    # interval has elapsed since it's last
    # actual transmission. The interval is
    # configured in seconds.
    # This option is commented out and not
    # used by default.
    # id_callsign = MYCALL-0
    # id_interval = 600

    # Whether to use KISS flow-control.
    # This is useful for modems that have
    # a small internal packet buffer, but
    # support packet flow control instead.
    flow_control = false

.. _interfaces-ax25:

AX.25 KISS Interface
====================

If you're using Reticulum on amateur radio spectrum, you might want to
use the AX.25 KISS interface. This way, Reticulum will automatically
encapsulate it's traffic in AX.25 and also identify your stations
transmissions with your callsign and SSID. 

Only do this if you really need to! Reticulum doesn't need the AX.25
layer for anything, and it incurs extra overhead on every packet to
encapsulate in AX.25.

A more efficient way is to use the plain KISS interface with the
beaconing functionality described above.

.. warning::
   Radio frequency spectrum is a legally controlled resource, and legislation
   varies widely around the world. It is your responsibility to be aware of any
   relevant regulation for your location, and to make decisions accordingly.

.. code:: ini

  [[Packet Radio AX.25 KISS Interface]]
    type = AX25KISSInterface

    # Set the station callsign and SSID
    callsign = NO1CLL
    ssid = 0

    # Enable interface if you want use it!
    enabled = yes

    # Serial port for the device
    port = /dev/ttyUSB2

    # Set the serial baud-rate and other
    # configuration parameters.
    speed = 115200    
    databits = 8
    parity = none
    stopbits = 1

    # Set the modem preamble. A 150ms
    # preamble should be a reasonable
    # default, but may need to be
    # increased for radios with slow-
    # opening squelch and long TX/RX
    # turnaround
    preamble = 150

    # Set the modem TX tail. In most
    # cases this should be kept as low
    # as possible to not waste airtime.
    txtail = 10

    # Configure CDMA parameters. These
    # settings are reasonable defaults.
    persistence = 200
    slottime = 20

    # Whether to use KISS flow-control.
    # This is useful for modems with a
    # small internal packet buffer.
    flow_control = false

.. _interfaces-discoverable:

Discoverable Interfaces
=======================

Reticulum includes a powerful system for publishing your local interfaces to the wider network, allowing other peers to :ref:`discover, validate, and automatically connect to them<using-interface_discovery>`. This feature is particularly useful for creating decentralized networks where peers can dynamically find entrypoints, such as public Internet gateways or local radio access points, without relying on static configuration files or centralized directories.

When an interface is made **discoverable**, your Reticulum instance will periodically broadcast an announce packet containing the connection details and parameters required for other peers to establish a connection. These announces are propagated over the network using the standard Reticulum announce mechanism using the ``rnstransport.discovery.interface`` destination type.

.. note::
   To use the interface discovery functionality, the ``LXMF`` module must be installed in your Python environment. You can install it using pip:

   .. code:: sh

     pip install lxmf


Enabling Discovery
------------------

Interface discovery is enabled on a per-interface basis. To make a specific interface discoverable, you must add the ``discoverable`` option to that interface's configuration block and set it to ``yes``.

.. code:: ini

  [[My Public Gateway]]
    type = BackboneInterface
    ...
    discoverable = yes

Once enabled, Reticulum will automatically handle the generation, signing, stamping, and broadcasting of the discovery announces. It is not *required* to enable Transport to publish interface discovery information, but for most use cases where you want others to connect to you, you will likely want ``enable_transport`` set to ``yes`` in the ``[reticulum]`` section of your configuration.


Discovery Parameters
--------------------

When ``discoverable`` is enabled, a variety of additional options become available to control how the interface is presented to the network. These parameters allow you to fine-tune the metadata, security requirements, and visibility of your interface.

**Basic Metadata**

``discovery_name``
  A human-readable name for the interface. This name will be displayed to users on remote systems when they list discovered interfaces. If not specified, the interface name (the section header) will be used.

``announce_interval``
  The interval in minutes between successive discovery announces for this interface. Default is 360 minutes (6 hours). For stable, long-running infrastructure, higher intervals (12 to 22 hours) are usually sufficient and reduce network load. Minimum allowed value is 5 minutes (but expect to have your announces throttled if using intervals below one hour).

**Connectivity Specification**

``reachable_on``
  Specifies the address that remote peers should use to connect to this interface. 
  
  *   For TCP and Backbone interfaces, this is typically the public IP address or hostname. Do not include the port, this is fetched automatically from the interface.
  *   For I2P interfaces, this is usually the I2P ``b32`` address. This value is fetched automatically from the ``I2PInterface`` once it is up and connected to the I2P network, so you should not set this manually, unless you absolutely know what you're doing.
  
  **Dynamic Resolution:** This option also accepts a path to an external executable script or binary. If a path is provided, Reticulum will execute the script and use its ``stdout`` as the reachability address. This is useful for devices behind dynamic DNS, NATs, or complex cloud environments where the external IP is not known locally. The script must simply print the address to stdout and exit.

.. note::
  When using an executable script for ``reachable_on``, Reticulum expects the script to output only the IP address or hostname to ``stdout``, followed by a newline character. Any additional output or errors may cause the resolution to fail. Ensure the script has executable permissions and is robust against temporary network failures.

A minimal example of a script that resolves the externally available, public IP of an internet-connected system could look like this:

.. code:: bash

  #!/bin/bash
  curl -s ip.me
  exit $?

On a real system, you should make the script robust enough to deal with intermittent Internet or service failures, such that the script *always* returns a sensible value, or if not possible at least exits with a non-zero exit return code, so Reticulum knows the output is invalid.

**Security & Cost**

``discovery_stamp_value``
  Defines the proof-of-work difficulty for the cryptographic stamp included in the announce. This value acts as a cost barrier to prevent network flooding. The default value is ``14``. Increasing this value makes it computationally more expensive to generate an announce, which can be useful to prevent spam on very large networks, but it also increases CPU load on your system when generating announces. Stamps are cached, and only generated if interface information changes, or at instance restart. If you have the computational resources, it is generally advisable to use as high a stamp value as possible.

**Privacy & Encryption**

``discovery_encrypt``
  If set to ``yes``, the discovery announce payload will be encrypted. To decrypt the announce, remote peers must possess the *network identity* configured for your instance (see ``network_identity`` in the ``[reticulum]`` section). This allows you to publish private interfaces that are only discoverable to specific trusted networks.

.. important::
   If you enable ``discovery_encrypt`` but do not configure a valid ``network_identity`` in the ``[reticulum]`` section of your configuration, Reticulum will abort the interface discovery announce. Encryption requires a valid network identity key to function.

``publish_ifac``
  If set to ``yes``, the Interface Access Code (IFAC) name and passphrase for this interface will be included in the discovery announce. This allows peers to automatically configure the correct authentication parameters when connecting to the interface.

**Physical Location**

``latitude``, ``longitude``, ``height``
  Optional physical coordinates for the interface. These are useful for mapping discovered interfaces geographically or for clients to automatically select the nearest access point. Coordinates should be in decimal degrees, height in meters above mean sea level.

``location_cmd``
  Optional path to executable or script that returns the physical coordinates for the interface. This can be used instead of manually setting ``latitude``, ``longitude`` and ``height``. Reticulum expects the script to output the location data to ``stdout`` on a single line, separated by commas, with values as floating point numbers in the format ``LAT, LON, HEIGHT``. Coordinates should be in decimal degrees, height in meters above mean sea level.

.. note::
   The height value for interface discovery is specified in *height above mean sea level*! This is the geoid-corrected height value, and is distinct from GPS altitude. If you manually specify height, it will typically be set to what you find on a topographical map. If you are using a script to output the location data, make sure that you are using the geoid-corrected altitude, not height above the GPS ellipsoid. Most GPS systems will make both figures available.

**Radio Parameters**

For physical radio interfaces like ``RNodeInterface`` or ``KISSInterface``, the following optional parameters allow you to broadcast the operating frequency and characteristics, allowing clients to verify compatibility before connecting:

``discovery_frequency``
  The operating frequency in Hz. Auto-configured on RNode interfaces. Necessary on KISS-based radio interfaces and ``TCPClientInterfaces`` connecting to radio modems.

``discovery_bandwidth``
  The signal bandwidth in Hz. Auto-configured on RNode interfaces. Useful on KISS-based radio interfaces and ``TCPClientInterfaces`` connecting to radio modems.

``discovery_modulation``
  The modulation type or scheme. Auto-configured on RNode interfaces, but highly advisable to include on other radio-based interfaces.


Interface Modes
---------------

When you enable discovery on an interface, Reticulum enforces certain interface modes to ensure the interface is actually useful for remote peers. 

If an interface is configured as ``discoverable``, but its mode is not explicitly set to ``gateway`` (for server-style interfaces like ``BackboneInterface`` or ``TCPServerInterface``) or ``access_point`` (for radio interfaces like ``RNodeInterface``), Reticulum will automatically configure the appropriate mode and log a notice. 

For example, if you enable discovery on a ``RNodeInterface`` without specifying the mode, Reticulum will automatically set it to ``access_point`` mode.

Security Considerations
-----------------------

When making interfaces discoverable, you are effectively broadcasting an invitation to connect to your system. It is important to understand the security implications of the configuration options you choose.

**Publishing Credentials**

If you enable ``publish_ifac = yes``, your interface's authentication passphrase will be included in the announce. If you are operating a public network and want anyone to connect, this is acceptable. However, if you wish to restrict access to a specific group of users, you **must** enable ``discovery_encrypt = yes``. This ensures that only peers possessing the correct ``network_identity`` can decode the passphrase.

**Topology Exposure**

A discoverable interface announces its presence, location (if configured), and capabilities to the network. Even if the connection details are encrypted, the *fact* that a connectable node exists within a certain network becomes public information. In high-security or scenarios requiring operational secrecy, consider the implications of advertising your infrastructure's existence.

Example Configuration
---------------------

Below is an example configuration for a public backbone gateway. This configuration publishes a high-value, publicly discoverable interface, that anyone can connect to.

.. code:: ini

  [[My Public Gateway]]
    type = BackboneInterface
    mode = gateway
    listen_on = 0.0.0.0
    port = 4242

    # Enable Discovery
    discoverable = yes

    # Interface Details
    discovery_name = Region A Public Entrypoint
    announce_interval = 720

    # Use external script to resolve dynamic IP
    reachable_on = /usr/local/bin/get_external_ip.sh

    # Generate high stamp value
    discovery_stamp_value = 24

    # Optional location data
    latitude = 51.99714
    longitude = -0.74195
    height = 15

The next example create an encrypted discovery-enabled interface, requiring a specific network identity to decode, and includes IFAC credentials for seamless authentication.

.. code:: ini

  [[My Private Gateway]]
    type = BackboneInterface
    mode = gateway
    listen_on = 0.0.0.0
    port = 5858
    network_name = internal_1
    passphrase = Mevpekyafshak5Wr

    # Enable Discovery
    discoverable = yes

    # Interface Details
    discovery_name = Region A Private Backbone
    announce_interval = 720

    # Use external script to resolve dynamic IP
    reachable_on = /usr/local/bin/get_external_ip.sh

    # Target stamp value
    discovery_stamp_value = 22

    # Encrypt announces for our network only
    discovery_encrypt = yes

    # Include credentials so trusted
    # peers can connect automatically
    publish_ifac = yes

    # Optional location data
    latitude = 34.06915
    longitude = -118.44318
    height = 15

In the ``[reticulum]`` section of your configuration, you would define the network identity used for encryption as follows:

.. code:: ini

  [reticulum]
  ...
  # The identity used to sign/encrypt discovery announces
  network_identity = ~/.reticulum/storage/identities/my_network_identity
  ...

With these configuration options applied, your Reticulum instance will actively participate in the network's discovery ecosystem. Other peers running Reticulum with discovery enabled will be able to see your interface, validate its cryptographic stamp, and (depending on their configuration) automatically connect to it.

For information on how to use these discovered interfaces and configure your system to auto-connect to them, refer to the :ref:`Discovering Interfaces<using-interface_discovery>` chapter.

.. _interfaces-options:

Common Interface Options
========================

A number of general configuration options are available on most interfaces.
These can be used to control various aspects of interface behaviour.


 * | The ``enabled`` option tells Reticulum whether or not
     to bring up the interface. Defaults to ``False``. For any
     interface to be brought up, the ``enabled`` option
     must be set to ``True`` or ``Yes``.

 * | The ``mode`` option allows selecting the high-level behaviour
     of the interface from a number of options.

     - The default value is ``full``. In this mode, all discovery,
       meshing and transport functionality is available.

     - In the ``access_point`` (or shorthand ``ap``) 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.

 * | The ``outgoing`` option sets whether an interface is allowed
     to transmit. Defaults to ``True``. If set to ``False`` or ``No``
     the interface will only receive data, and never transmit.

 * | The ``network_name`` option sets the virtual network name for
     the interface. This allows multiple separate network segments
     to exist on the same physical channel or medium.

 * | The ``passphrase`` option sets an authentication passphrase on
     the interface. This option can be used in conjunction with the
     ``network_name`` option, or be used alone.

 * | The ``ifac_size`` 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.

 * | The ``announce_cap`` 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 ``1`` and ``100``.

     *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.*

     *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.*

     *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.*

 * | The ``bitrate`` 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 ``bitrate``
     option, to set the interface speed in *bits per second*.


 * | The ``bootstrap_only`` option designates an interface as a temporary
     bridge for initial connectivity. If this option is enabled, the
     interface will be monitored and automatically detached once the
     number of auto-connected interfaces reaches the limit configured by
     ``autoconnect_discovered_interfaces``. This is particularly useful
     for using a slow or expensive connection (such as a single LoRa
     link or a remote TCP tunnel) solely to discover better local
     infrastructure, which then supersedes the bootstrap interface.


 * | The ``recursive_prs`` option allows you to enable recursive path
     discovery on an interface regardless of its configured interface
     mode. When this option is enabled, Reticulum will attempt to
     recursively discover paths for path requests received on this
     interface.


 * | The ``announces_from_internal`` option controls whether any
     announces *received on* an ``internal`` mode interface will
     propagate *out* on the interface this option is set on. Note
     that this controls *announce propagation*; even if announces
     do not propagate out when received, paths to destinations on
     ``internal`` mode interfaces may still be resolvable by means
     of path requests.

.. _interfaces-modes:

Interface Modes
===============

The optional ``mode`` setting 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, how long paths are valid and how paths are discovered.

Configuring modes on interfaces is **not** strictly necessary, but can be useful
when building or connecting to more complex networks. If your Reticulum
instance is not running a Transport Node, it is rarely useful to configure
interface modes, and in such cases interfaces should generally be left in
the default mode.

 * | The default mode is ``full``. In this mode, all discovery,
     meshing and transport functionality is activated.

 * | The ``gateway`` mode (or shorthand ``gw``) 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 ``gateway`` interface.
     If Reticulum receives a path request for an unknown
     destination, from a node on a ``gateway`` 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.

   | 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 ``gateway`` interfaces, other
     nodes will be able to immediately discover paths to any
     destination along the chain.

   | *Please note!* It is the interface *facing the clients* that
     must be put into ``gateway`` mode for this to work, not
     the interface facing the wider network (for this, the ``boundary``
     mode can be useful, though).

 * | In the ``access_point`` (or shorthand ``ap``) 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. In addition, path
     requests from clients on the access point interface will
     be handled in the same way as the ``gateway`` interface.

   | This mode is useful for creating interfaces that remain
     quiet, until someone actually starts 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.

 * | The ``roaming`` 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 ``roaming``, 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
     ``roaming`` interfaces also expire faster.

 * | The purpose of the ``boundary`` 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 ``boundary`` mode.

 * | The ``internal`` mode designates interfaces that belong to a
     network different from any marked as ``boundary``. Announces from
     a ``boundary`` interface will not propagate to interfaces set as
     ``internal``, but announces *will* propagate from ``internal`` *to*
     ``boundary``. Devices on the ``internal`` side of the network will
     still be able to resolve paths to destinations across the boundary
     when needed, since recursive path requests are enabled for ``internal``
     mode interfaces by default.

For a table describing the impact of all modes on announce propagation,
please see the :ref:`Announce Propagation Rules<understanding-announcepropagation>` section.

.. _interfaces-announcerates:

Announce Rate Control
=====================

The built-in announce control mechanisms and the default ``announce_cap``
option described above are sufficient most of the time, but in some cases,
especially on fast interfaces, or when connecting to large public networks,
it may be useful to control the target announce rate.

Using the ``announce_rate_target``, ``announce_rate_grace`` and ``announce_rate_penalty``
options, this can be done on a per-interface basis, or by setting instance-wide defaults.
When configured, this moderates the *rate at which received announces are
re-broadcasted to other interfaces*.

 * | The ``announce_rate_target`` 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 ``3600`` means that
     announces *received* on this interface will only be re-transmitted and
     propagated to other interfaces once every hour, no matter how often they
     are received.

 * | The optional ``announce_rate_grace`` defines the number of times a destination
     can violate the announce rate before the target rate is enforced.

 * | The optional ``announce_rate_penalty`` configures an extra amount of
     time that is added to the normal rate target. As an example, if a penalty
     of ``7200`` 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.

You can also configure default announce rate parameters for all interfaces that
do not have these parameters set explicitly by setting the ``default_ar_target``
``default_ar_penalty`` and ``default_ar_grace`` options in the ``[reticulum]``
section of the configuration file. If any of these options are set, they will
automatically be applied to any interface if transport is enabled, and the
interface does not have the parameters set explicitly.

For auto-connected interfaces, sensible default announce rate control parameters
will **always** be set, even if the defaults are not configured explicitly, but
if you set the defaults, auto-connected interfaces will adhere to these as well.

These mechanisms, in conjunction with the ``annouce_cap`` 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, or networks that
are many hops away.

Statistics and information about announce rates can be viewed using the
``rnpath -r`` and ``rnstatus -A`` commands.

It is important to note, that while there is no one right or wrong way to set up announce
rates, it should generally not be necessary to announce any kind of destination.
more often than once every few hours. Most applications can announce simply when
the application starts, and then only once every 6 hours or so.

If you're designing an application where you think you need to annonuce more
often than once an hour, you're most likely doing something wrong.

Slower networks will naturally tend towards using less frequent announces to
conserve bandwidth, while very fast networks can support applications that
need more frequent announces. Reticulum implements these mechanisms to ensure
that a large span of network types can seamlessly *co-exist* and interconnect.

.. _interfaces-ingress-control:

New Destination Rate Limiting
=============================

On public interfaces, where anyone may connect and announce new destinations,
it can be useful to control the rate at which announces for *new*  destinations are
processed.

If a large influx of announces for newly created or previously unknown destinations
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.

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.

.. note::
   It's important to remember that the ingress control works at the level of *individual
   sub-interfaces*. As an example, this means that one client on a :ref:`TCP Server Interface<interfaces-tcps>`
   cannot disrupt processing of incoming announces for other connected clients on the same
   :ref:`TCP Server Interface<interfaces-tcps>`. All other clients on the same interface
   will still have new announces processed without interruption.

By default, Reticulum will handle this automatically, and ingress announce
control will be enabled on interface where it is sensible to do so. It should
generally not be neccessary to modify the ingress control configuration,
but all the parameters are exposed for configuration if needed.

 * | The ``ingress_control`` option tells Reticulum whether or not
     to enable ingress control on the interface. Defaults to ``True``.

 * | The ``ic_new_time`` option configures how long (in seconds) an
     interface is considered newly spawned. Defaults to ``2*60*60`` seconds. This
     option is useful on publicly accessible interfaces that spawn new
     sub-interfaces when a new client connects. 

 * | The ``ic_burst_freq_new`` option sets the maximum announce ingress
     frequency for newly spawned interfaces. Defaults to ``3.5``
     announces per second.

 * | The ``ic_burst_freq`` option sets the maximum announce ingress
     frequency for other interfaces. Defaults to ``12`` announces
     per second.

     *If an interface exceeds its burst frequency, incoming announces
     for unknown destinations will be temporarily held in a queue, and
     not processed until later.*

 * | The ``ic_max_held_announces`` option sets the maximum amount of
     unique announces that will be held in the queue. Any additional
     unique announces will be dropped. Defaults to ``256`` announces.

 * | The ``ic_burst_hold`` 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 ``60``
     seconds.

 * | The ``ic_burst_penalty`` 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 ``5*60``
     seconds.

 * | The ``ic_held_release_interval`` option sets how much time (in seconds)
     must pass between releasing each held announce from the queue. Defaults
     to ``30`` seconds.

All of the above settings can be configured both as instance-wide defaults
under the ``[reticulum]`` section of the configuration file, or on a per-
interface basis under the relevant interface configuration section.


Path Request Burst Control
==========================

In addition the announce controls for newly created destination, Reticulum will also 
monitor incoming path request activity, and enforce burst controls if per-client rates
exceed configured limits. Once path request burst control is activated on an
interface, path requests will no longer be propagated further on the network.
As with announce burst control, this happens on a per sub-interface basis. One
client connecting to a public gateway will not be able to disrupt path request
processing for other clients.

.. warning::
   Applications that send large amounts of unnecessary path requests will very
   quickly get rate limited by transport nodes, and the entire system they are
   running on will not be able to resolve any paths on the network, until the
   burst subsides and hold period expires. **Do not** write applications like
   this. Only request paths for destinations you need to communicate with.

By default, Reticulum will handle this automatically, and ingress path request
control will be enabled on interface where it is sensible to do so. It should
generally not be neccessary to modify the ingress control configuration,
but all the parameters are exposed for configuration if needed.

 * | The ``ingress_control`` option tells Reticulum whether or not
     to enable ingress control on the interface. Defaults to ``True``.

 * | The ``ic_new_time`` option configures how long (in seconds) an
     interface is considered newly spawned. Defaults to ``2*60*60`` seconds. This
     option is useful on publicly accessible interfaces that spawn new
     sub-interfaces when a new client connects.

 * | The ``ic_pr_burst_freq_new`` option sets the maximum path request
     ingress frequency for newly spawned interfaces. Defaults to ``3``
     path requests per second.

 * | The ``ic_pr_burst_freq`` option sets the maximum path request
     ingress frequency for other interfaces. Defaults to ``8`` path requests
     per second.

     *If an interface exceeds its burst frequency, incoming path requests
     from that system will not traverse the network further.*

 * | The ``egress_control`` option enables hard-limiting path request egress
     control per-interface. Defaults to ``False``

 * | The ``ec_pr_freq`` option sets the hard limit for outbound path requests
     per second on a given interface.

All of the above settings can be configured both as instance-wide defaults
under the ``[reticulum]`` section of the configuration file, or on a per-
interface basis under the relevant interface configuration section.