Updated manual

Fixed some typos

Changelog.md

@@ -1,4 +1,49 @@
-### 2023-09-21: RNS β 0.6.0
+### 2023-10-07: RNS β 0.6.2
+
+This maintenance release adds the ability to specify the shared instance RPC key in the Reticulum file, making it possible to use all Reticulum functionality in the terminal on Android.
+
+**Changes**
+- Added configuration option to specify shared instance RPC key
+- Reordered airtime stats in `rnstatus`
+- Updated log levels on Android
+
+**Bugfixes**
+- Adding missing superclass init on Android interfaces
+
+**Release Hashes**
+```
+a9958ad90f34f344003e18077f7abd3fa85666a39dc0cae8580071820dee13f9 rns-0.6.2-py3-none-any.whl
+e68e8837d35d1a07a82c4b0e9db50ceace737a650e6e7e9ce2d9a013fd28f529 rnspure-0.6.2-py3-none-any.whl
+```
+
+### 2023-10-01: RNS β 0.6.1
+
+This release brings a number of bugfixes, along with useful new mechanisms for ensuring network stability under high, non-constructive and unusual announce load situation.
+
+**Changes**
+- Added announce ingress rate control for new and unknown destinations
+- Added per-interface announce frequency monitoring to the transport engine
+- Added per-interface announce burst hold queues
+- Added announce frequency statistics to `rnstatus`
+- Added option to sort `rnstatus` output according to various metrics
+- Added timeout options to `rnprobe`
+- Added ability to drop all paths via a specific transport instance to `rnpath`
+- Added new options and features to documentation and manual
+
+**Bugfixes**
+- Fixed announce queue not clearing all announces with exceeded retry limit at the same time
+- Fixed a bug that caused local packet RSSI and SNR cache to get stuck
+- Fixed output formatting in `rncp`
+- Fixed `rnid` not allowing single-aspect destination names
+- Fixed a number of typos in the documentation
+
+**Release Hashes**
+```
+461e5cafa7560dcd3ec047141d10f0f48f151c36e1af1d65ec6c65f732cea46a rns-0.6.1-py3-none-any.whl
+be6a4a6069f2d050e21582f2cf9d3bb59ed4040a0f07761a540bd752d90ea591 rnspure-0.6.1-py3-none-any.whl
+```
+
+#### 2023-09-21: RNS β 0.6.0
 
 This release brings a few performance improvements, additions to the included utilities, and fixes a number of bugs.
 

Examples/Announce.py

@@ -32,7 +32,7 @@ def program_setup(configpath):
     # Destinations are endpoints in Reticulum, that can be addressed
     # and communicated with. Destinations can also announce their
     # existence, which will let the network know they are reachable
-    # and autoomatically create paths to them, from anywhere else
+    # and automatically create paths to them, from anywhere else
     # in the network.
     destination_1 = RNS.Destination(
         identity,
@@ -53,7 +53,7 @@ def program_setup(configpath):
     )
 
     # We configure the destinations to automatically prove all
-    # packets adressed to it. By doing this, RNS will automatically
+    # packets addressed to it. By doing this, RNS will automatically
     # generate a proof for each incoming packet and transmit it
     # back to the sender of that packet. This will let anyone that
     # tries to communicate with the destination know whether their

Examples/Echo.py

@@ -46,7 +46,7 @@ def server(configpath):
     )
 
     # We configure the destination to automatically prove all
-    # packets adressed to it. By doing this, RNS will automatically
+    # packets addressed to it. By doing this, RNS will automatically
     # generate a proof for each incoming packet and transmit it
     # back to the sender of that packet.
     echo_destination.set_proof_strategy(RNS.Destination.PROVE_ALL)

Examples/Minimal.py

@@ -25,7 +25,7 @@ def program_setup(configpath):
     # Destinations are endpoints in Reticulum, that can be addressed
     # and communicated with. Destinations can also announce their
     # existence, which will let the network know they are reachable
-    # and autoomatically create paths to them, from anywhere else
+    # and automatically create paths to them, from anywhere else
     # in the network.
     destination = RNS.Destination(
         identity,
@@ -36,7 +36,7 @@ def program_setup(configpath):
     )
 
     # We configure the destination to automatically prove all
-    # packets adressed to it. By doing this, RNS will automatically
+    # packets addressed to it. By doing this, RNS will automatically
     # generate a proof for each incoming packet and transmit it
     # back to the sender of that packet. This will let anyone that
     # tries to communicate with the destination know whether their

RNS/Buffer.py

@@ -1,3 +1,25 @@
+# MIT License
+#
+# Copyright (c) 2016-2023 Mark Qvist / unsigned.io and contributors.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
 from __future__ import annotations
 import bz2
 import sys

RNS/Destination.py

@@ -1,6 +1,6 @@
 # MIT License
 #
-# Copyright (c) 2016-2022 Mark Qvist / unsigned.io
+# Copyright (c) 2016-2023 Mark Qvist / unsigned.io and contributors
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal

RNS/Identity.py

@@ -1,6 +1,6 @@
 # MIT License
 #
-# Copyright (c) 2016-2022 Mark Qvist / unsigned.io
+# Copyright (c) 2016-2023 Mark Qvist / unsigned.io and contributors.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -217,7 +217,7 @@ class Identity:
         return Identity.truncated_hash(os.urandom(Identity.TRUNCATED_HASHLENGTH//8))
 
     @staticmethod
-    def validate_announce(packet):
+    def validate_announce(packet, only_validate_signature=False):
         try:
             if packet.packet_type == RNS.Packet.ANNOUNCE:
                 destination_hash = packet.destination_hash
@@ -238,6 +238,10 @@ class Identity:
                 announced_identity.load_public_key(public_key)
 
                 if announced_identity.pub != None and announced_identity.validate(signature, signed_data):
+                    if only_validate_signature:
+                        del announced_identity
+                        return True
+
                     hash_material = name_hash+announced_identity.hash
                     expected_hash = RNS.Identity.full_hash(hash_material)[:RNS.Reticulum.TRUNCATED_HASHLENGTH//8]
 

RNS/Interfaces/AX25KISSInterface.py

@@ -77,8 +77,7 @@ class AX25KISSInterface(Interface):
             RNS.log("You can install one with the command: python3 -m pip install pyserial", RNS.LOG_CRITICAL)
             RNS.panic()
 
-        self.rxb = 0
-        self.txb = 0
+        super().__init__()
 
         self.HW_MTU = 564
         
@@ -367,5 +366,8 @@ class AX25KISSInterface(Interface):
 
         RNS.log("Reconnected serial port for "+str(self))
 
+    def should_ingress_limit(self):
+        return False
+
     def __str__(self):
         return "AX25KISSInterface["+self.name+"]"

RNS/Interfaces/Android/KISSInterface.py

@@ -82,8 +82,7 @@ class KISSInterface(Interface):
         else:
             raise SystemError("Android-specific interface was used on non-Android OS")
 
-        self.rxb = 0
-        self.txb = 0
+        super().__init__()
         
         self.HW_MTU = 564
         
@@ -403,5 +402,8 @@ class KISSInterface(Interface):
 
         RNS.log("Reconnected serial port for "+str(self))
 
+    def should_ingress_limit(self):
+        return False
+
     def __str__(self):
         return "KISSInterface["+self.name+"]"

RNS/Interfaces/Android/RNodeInterface.py

@@ -166,8 +166,8 @@ class AndroidBluetoothManager():
                                 raise IOError("The Bluetooth RFcomm socket could not be connected: "+str(e))
 
                 except Exception as e:
-                    RNS.log("Could not create and connect Bluetooth RFcomm socket for "+str(device.getName())+" "+str(device.getAddress()), RNS.LOG_ERROR)
-                    RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
+                    RNS.log("Could not create and connect Bluetooth RFcomm socket for "+str(device.getName())+" "+str(device.getAddress()), RNS.LOG_DEBUG)
+                    RNS.log("The contained exception was: "+str(e), RNS.LOG_DEBUG)
 
     def close(self):
         if self.connected:
@@ -349,8 +349,7 @@ class RNodeInterface(Interface):
         else:
             raise SystemError("Android-specific interface was used on non-Android OS")
 
-        self.rxb = 0
-        self.txb = 0
+        super().__init__()
 
         self.HW_MTU = 508
         
@@ -1234,6 +1233,9 @@ class RNodeInterface(Interface):
         self.setRadioState(KISS.RADIO_STATE_OFF)
         self.leave()
 
+    def should_ingress_limit(self):
+        return False
+
     def __str__(self):
         return "RNodeInterface["+str(self.name)+"]"
 

RNS/Interfaces/Android/SerialInterface.py

@@ -72,8 +72,7 @@ class SerialInterface(Interface):
         else:
             raise SystemError("Android-specific interface was used on non-Android OS")
 
-        self.rxb = 0
-        self.txb = 0
+        super().__init__()
 
         self.HW_MTU = 564
         
@@ -254,5 +253,8 @@ class SerialInterface(Interface):
 
         RNS.log("Reconnected serial port for "+str(self))
 
+    def should_ingress_limit(self):
+        return False
+
     def __str__(self):
         return "SerialInterface["+self.name+"]"

RNS/Interfaces/AutoInterface.py

@@ -76,11 +76,9 @@ class AutoInterface(Interface):
 
     def __init__(self, owner, name, group_id=None, discovery_scope=None, discovery_port=None, data_port=None, allowed_interfaces=None, ignored_interfaces=None, configured_bitrate=None):
         from RNS.vendor.ifaddr import niwrapper
+        super().__init__()
         self.netinfo = niwrapper
 
-        self.rxb = 0
-        self.txb = 0
-
         self.HW_MTU = 1064
 
         self.IN  = True
@@ -433,6 +431,11 @@ class AutoInterface(Interface):
             self.txb += len(data)
             
 
+    # Until per-device sub-interfacing is implemented,
+    # ingress limiting should be disabled on AutoInterface
+    def should_ingress_limit(self):
+        return False
+
     def __str__(self):
         return "AutoInterface["+self.name+"]"
 

RNS/Interfaces/I2PInterface.py

@@ -390,8 +390,7 @@ class I2PInterfacePeer(Interface):
     TUNNEL_STATE_STALE   = 0x02
 
     def __init__(self, parent_interface, owner, name, target_i2p_dest=None, connected_socket=None, max_reconnect_tries=None):
-        self.rxb = 0
-        self.txb = 0
+        super().__init__()
 
         self.HW_MTU = 1064
         
@@ -832,8 +831,7 @@ class I2PInterface(Interface):
     BITRATE_GUESS      = 256*1000
 
     def __init__(self, owner, name, rns_storagepath, peers, connectable = False, ifac_size = 16, ifac_netname = None, ifac_netkey = None):
-        self.rxb = 0
-        self.txb = 0
+        super().__init__()
         
         self.HW_MTU = 1064
 
@@ -964,6 +962,12 @@ class I2PInterface(Interface):
     def processOutgoing(self, data):
         pass
 
+    def received_announce(self, from_spawned=False):
+        if from_spawned: self.ia_freq_deque.append(time.time())
+
+    def sent_announce(self, from_spawned=False):
+        if from_spawned: self.oa_freq_deque.append(time.time())
+
     def detach(self):
         RNS.log("Detaching "+str(self), RNS.LOG_DEBUG)
         self.i2p.stop()

RNS/Interfaces/Interface.py

@@ -1,6 +1,6 @@
 # MIT License
 #
-# Copyright (c) 2016-2022 Mark Qvist / unsigned.io
+# Copyright (c) 2016-2023 Mark Qvist / unsigned.io
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -23,6 +23,7 @@
 import RNS
 import time
 import threading
+from collections import deque
 
 class Interface:
     IN  = False
@@ -39,18 +40,160 @@ class Interface:
     MODE_BOUNDARY       = 0x05
     MODE_GATEWAY        = 0x06
 
-    # Which interface modes a Transport Node
-    # should actively discover paths for.
+    # Which interface modes a Transport Node should
+    # actively discover paths for.
     DISCOVER_PATHS_FOR  = [MODE_ACCESS_POINT, MODE_GATEWAY]
 
+    # How many samples to use for announce
+    # frequency calculations
+    IA_FREQ_SAMPLES     = 6
+    OA_FREQ_SAMPLES     = 6
+
+    # Maximum amount of ingress limited announces
+    # to hold at any given time.
+    MAX_HELD_ANNOUNCES  = 256
+
+    # How long a spawned interface will be
+    # considered to be newly created. Two
+    # hours by default.
+    IC_NEW_TIME              = 2*60*60
+    IC_BURST_FREQ_NEW        = 3.5
+    IC_BURST_FREQ            = 12
+    IC_BURST_HOLD            = 1*60
+    IC_BURST_PENALTY         = 5*60
+    IC_HELD_RELEASE_INTERVAL = 30
+
     def __init__(self):
         self.rxb = 0
         self.txb = 0
+        self.created = time.time()
         self.online = False
 
+        self.ingress_control = True
+        self.ic_max_held_announces = Interface.MAX_HELD_ANNOUNCES
+        self.ic_burst_hold = Interface.IC_BURST_HOLD
+        self.ic_burst_active = False
+        self.ic_burst_activated = 0
+        self.ic_held_release = 0
+        self.ic_burst_freq_new = Interface.IC_BURST_FREQ_NEW
+        self.ic_burst_freq = Interface.IC_BURST_FREQ
+        self.ic_new_time = Interface.IC_NEW_TIME
+        self.ic_burst_penalty = Interface.IC_BURST_PENALTY
+        self.ic_held_release_interval = Interface.IC_HELD_RELEASE_INTERVAL
+        self.held_announces = {}
+
+        self.ia_freq_deque = deque(maxlen=Interface.IA_FREQ_SAMPLES)
+        self.oa_freq_deque = deque(maxlen=Interface.OA_FREQ_SAMPLES)
+
     def get_hash(self):
         return RNS.Identity.full_hash(str(self).encode("utf-8"))
 
+    # This is a generic function for determining when an interface
+    # should activate ingress limiting. Since this can vary for
+    # different interface types, this function should be overwritten
+    # in case a particular interface requires a different approach.
+    def should_ingress_limit(self):
+        if self.ingress_control:
+            freq_threshold = self.ic_burst_freq_new if self.age() < self.ic_new_time else self.ic_burst_freq
+            ia_freq = self.incoming_announce_frequency()
+
+            if self.ic_burst_active:
+                if ia_freq < freq_threshold and time.time() > self.ic_burst_activated+self.ic_burst_hold:
+                    self.ic_burst_active = False
+                    self.ic_held_release = time.time() + self.ic_burst_penalty
+                return True
+
+            else:
+                if ia_freq > freq_threshold:
+                    self.ic_burst_active = True
+                    self.ic_burst_activated = time.time()
+                    return True
+
+                else:
+                    return False
+
+        else:
+            return False
+
+    def age(self):
+        return time.time()-self.created
+
+    def hold_announce(self, announce_packet):
+        if announce_packet.destination_hash in self.held_announces:
+            self.held_announces[announce_packet.destination_hash] = announce_packet
+        elif not len(self.held_announces) >= self.ic_max_held_announces:
+            self.held_announces[announce_packet.destination_hash] = announce_packet
+
+    def process_held_announces(self):
+        try:
+            if not self.should_ingress_limit() and len(self.held_announces) > 0 and time.time() > self.ic_held_release:
+                freq_threshold = self.ic_burst_freq_new if self.age() < self.ic_new_time else self.ic_burst_freq
+                ia_freq = self.incoming_announce_frequency()
+                if ia_freq < freq_threshold:
+                    selected_announce_packet = None
+                    min_hops = RNS.Transport.PATHFINDER_M
+                    for destination_hash in self.held_announces:
+                        announce_packet = self.held_announces[destination_hash]
+                        if announce_packet.hops < min_hops:
+                            min_hops = announce_packet.hops
+                            selected_announce_packet = announce_packet
+
+                    if selected_announce_packet != None:
+                        RNS.log("Releasing held announce packet "+str(selected_announce_packet)+" from "+str(self), RNS.LOG_EXTREME)
+                        self.ic_held_release = time.time() + self.ic_held_release_interval
+                        self.held_announces.pop(selected_announce_packet.destination_hash)
+                        def release():
+                            RNS.Transport.inbound(selected_announce_packet.raw, selected_announce_packet.receiving_interface)
+                        threading.Thread(target=release, daemon=True).start()
+        
+        except Exception as e:
+            RNS.log("An error occurred while processing held announces for "+str(self), RNS.LOG_ERROR)
+            RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
+
+    def received_announce(self):
+        self.ia_freq_deque.append(time.time())
+        if hasattr(self, "parent_interface") and self.parent_interface != None:
+            self.parent_interface.received_announce(from_spawned=True)
+
+    def sent_announce(self):
+        self.oa_freq_deque.append(time.time())
+        if hasattr(self, "parent_interface") and self.parent_interface != None:
+            self.parent_interface.sent_announce(from_spawned=True)
+
+    def incoming_announce_frequency(self):
+        if not len(self.ia_freq_deque) > 1:
+            return 0
+        else:
+            dq_len = len(self.ia_freq_deque)
+            delta_sum = 0
+            for i in range(1,dq_len):
+                delta_sum += self.ia_freq_deque[i]-self.ia_freq_deque[i-1]
+            delta_sum += time.time() - self.ia_freq_deque[dq_len-1]
+            
+            if delta_sum == 0:
+                avg = 0
+            else:
+                avg = 1/(delta_sum/(dq_len))
+
+            return avg
+
+    def outgoing_announce_frequency(self):
+        if not len(self.oa_freq_deque) > 1:
+            return 0
+        else:
+            dq_len = len(self.oa_freq_deque)
+            delta_sum = 0
+            for i in range(1,dq_len):
+                delta_sum += self.oa_freq_deque[i]-self.oa_freq_deque[i-1]
+            delta_sum += time.time() - self.oa_freq_deque[dq_len-1]
+            
+            if delta_sum == 0:
+                avg = 0
+            else:
+                avg = 1/(delta_sum/(dq_len))
+
+            return avg
+
     def process_announce_queue(self):
         if not hasattr(self, "announce_cap"):
             self.announce_cap = RNS.Reticulum.ANNOUNCE_CAP
@@ -79,6 +222,7 @@ class Interface:
                     self.announce_allowed_at = now + wait_time
 
                     self.processOutgoing(selected["raw"])
+                    self.sent_announce()
 
                     if selected in self.announce_queue:
                         self.announce_queue.remove(selected)

RNS/Interfaces/KISSInterface.py

@@ -70,8 +70,7 @@ class KISSInterface(Interface):
             RNS.log("You can install one with the command: python3 -m pip install pyserial", RNS.LOG_CRITICAL)
             RNS.panic()
 
-        self.rxb = 0
-        self.txb = 0
+        super().__init__()
         
         self.HW_MTU = 564
         
@@ -349,5 +348,8 @@ class KISSInterface(Interface):
 
         RNS.log("Reconnected serial port for "+str(self))
 
+    def should_ingress_limit(self):
+        return False
+
     def __str__(self):
         return "KISSInterface["+self.name+"]"

RNS/Interfaces/LocalInterface.py

@@ -1,6 +1,6 @@
 # MIT License
 #
-# Copyright (c) 2016-2022 Mark Qvist / unsigned.io
+# Copyright (c) 2016-2023 Mark Qvist / unsigned.io
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -53,8 +53,7 @@ class LocalClientInterface(Interface):
     RECONNECT_WAIT = 3
 
     def __init__(self, owner, name, target_port = None, connected_socket=None):
-        self.rxb = 0
-        self.txb = 0
+        super().__init__()
 
         # TODO: Remove at some point
         # self.rxptime = 0
@@ -103,6 +102,9 @@ class LocalClientInterface(Interface):
             thread.daemon = True
             thread.start()
 
+    def should_ingress_limit(self):
+        return False
+
     def connect(self):
         self.socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
         self.socket.connect((self.target_ip, self.target_port))
@@ -280,8 +282,7 @@ class LocalClientInterface(Interface):
 class LocalServerInterface(Interface):
 
     def __init__(self, owner, bindport=None):
-        self.rxb = 0
-        self.txb = 0
+        super().__init__()
         self.online = False
         self.clients = 0
         
@@ -329,7 +330,7 @@ class LocalServerInterface(Interface):
         spawned_interface.target_port = str(handler.client_address[1])
         spawned_interface.parent_interface = self
         spawned_interface.bitrate = self.bitrate
-        RNS.log("Accepting new connection to shared instance: "+str(spawned_interface), RNS.LOG_EXTREME)
+        # RNS.log("Accepting new connection to shared instance: "+str(spawned_interface), RNS.LOG_EXTREME)
         RNS.Transport.interfaces.append(spawned_interface)
         RNS.Transport.local_client_interfaces.append(spawned_interface)
         self.clients += 1
@@ -338,6 +339,12 @@ class LocalServerInterface(Interface):
     def processOutgoing(self, data):
         pass
 
+    def received_announce(self, from_spawned=False):
+        if from_spawned: self.ia_freq_deque.append(time.time())
+
+    def sent_announce(self, from_spawned=False):
+        if from_spawned: self.oa_freq_deque.append(time.time())
+
     def __str__(self):
         return "Shared Instance["+str(self.bind_port)+"]"
 

RNS/Interfaces/PipeInterface.py

@@ -54,8 +54,7 @@ class PipeInterface(Interface):
         if respawn_delay == None:
             respawn_delay = 5
 
-        self.rxb = 0
-        self.txb = 0
+        super().__init__()
 
         self.HW_MTU = 1064
         

RNS/Interfaces/RNodeInterface.py

@@ -1,6 +1,6 @@
 # MIT License
 #
-# Copyright (c) 2016-2022 Mark Qvist / unsigned.io
+# Copyright (c) 2016-2023 Mark Qvist / unsigned.io
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -114,8 +114,7 @@ class RNodeInterface(Interface):
             RNS.log("You can install one with the command: python3 -m pip install pyserial", RNS.LOG_CRITICAL)
             RNS.panic()
 
-        self.rxb = 0
-        self.txb = 0
+        super().__init__()
 
         self.HW_MTU = 508
         
@@ -838,5 +837,8 @@ class RNodeInterface(Interface):
         self.setRadioState(KISS.RADIO_STATE_OFF)
         self.leave()
 
+    def should_ingress_limit(self):
+        return False
+
     def __str__(self):
         return "RNodeInterface["+str(self.name)+"]"

RNS/Interfaces/SerialInterface.py

@@ -60,8 +60,7 @@ class SerialInterface(Interface):
             RNS.log("You can install one with the command: python3 -m pip install pyserial", RNS.LOG_CRITICAL)
             RNS.panic()
 
-        self.rxb = 0
-        self.txb = 0
+        super().__init__()
 
         self.HW_MTU = 564
         
@@ -201,5 +200,8 @@ class SerialInterface(Interface):
 
         RNS.log("Reconnected serial port for "+str(self))
 
+    def should_ingress_limit(self):
+        return False
+
     def __str__(self):
         return "SerialInterface["+self.name+"]"

RNS/Interfaces/TCPInterface.py

@@ -79,8 +79,7 @@ class TCPClientInterface(Interface):
     I2P_PROBES = 5
 
     def __init__(self, owner, name, target_ip=None, target_port=None, connected_socket=None, max_reconnect_tries=None, kiss_framing=False, i2p_tunneled = False, connect_timeout = None):
-        self.rxb = 0
-        self.txb = 0
+        super().__init__()
         
         self.HW_MTU = 1064
         
@@ -419,8 +418,7 @@ class TCPServerInterface(Interface):
         return ifaddr[netinfo.AF_INET][0]["broadcast"]
 
     def __init__(self, owner, name, device=None, bindip=None, bindport=None, i2p_tunneled=False):
-        self.rxb = 0
-        self.txb = 0
+        super().__init__()
 
         self.HW_MTU = 1064
 
@@ -505,6 +503,12 @@ class TCPServerInterface(Interface):
         self.clients += 1
         spawned_interface.read_loop()
 
+    def received_announce(self, from_spawned=False):
+        if from_spawned: self.ia_freq_deque.append(time.time())
+
+    def sent_announce(self, from_spawned=False):
+        if from_spawned: self.oa_freq_deque.append(time.time())
+
     def processOutgoing(self, data):
         pass
 

RNS/Interfaces/UDPInterface.py

@@ -45,8 +45,7 @@ class UDPInterface(Interface):
         return ifaddr[netinfo.AF_INET][0]["broadcast"]
 
     def __init__(self, owner, name, device=None, bindip=None, bindport=None, forwardip=None, forwardport=None):
-        self.rxb = 0
-        self.txb = 0
+        super().__init__()
 
         self.HW_MTU = 1064
 

RNS/Link.py

@@ -1,6 +1,6 @@
 # MIT License
 #
-# Copyright (c) 2016-2022 Mark Qvist / unsigned.io
+# Copyright (c) 2016-2023 Mark Qvist / unsigned.io and contributors.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal

RNS/Packet.py

@@ -1,6 +1,6 @@
 # MIT License
 #
-# Copyright (c) 2016-2022 Mark Qvist / unsigned.io
+# Copyright (c) 2016-2023 Mark Qvist / unsigned.io and contributors.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -30,7 +30,7 @@ class Packet:
     """
     The Packet class is used to create packet instances that can be sent
     over a Reticulum network. Packets will automatically be encrypted if
-    they are adressed to a ``RNS.Destination.SINGLE`` destination,
+    they are addressed to a ``RNS.Destination.SINGLE`` destination,
     ``RNS.Destination.GROUP`` destination or a :ref:`RNS.Link<api-link>`.
 
     For ``RNS.Destination.GROUP`` destinations, Reticulum will use the

RNS/Resolver.py

@@ -0,0 +1,27 @@
+# MIT License
+#
+# Copyright (c) 2016-2023 Mark Qvist / unsigned.io and contributors.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+class Resolver:
+  
+  @staticmethod
+  def resolve_identity(full_name):
+    pass

RNS/Resource.py

@@ -1,6 +1,6 @@
 # MIT License
 #
-# Copyright (c) 2016-2022 Mark Qvist / unsigned.io
+# Copyright (c) 2016-2023 Mark Qvist / unsigned.io and contributors.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal

RNS/Reticulum.py

@@ -1,6 +1,6 @@
 # MIT License
 #
-# Copyright (c) 2016-2022 Mark Qvist / unsigned.io
+# Copyright (c) 2016-2023 Mark Qvist / unsigned.io and contributors.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -209,6 +209,7 @@ class Reticulum:
         self.local_control_port   = 37429
         self.share_instance       = True
         self.rpc_listener         = None
+        self.rpc_key              = None
 
         self.ifac_salt = Reticulum.IFAC_SALT
 
@@ -262,7 +263,8 @@ class Reticulum:
         RNS.Transport.start(self)
 
         self.rpc_addr = ("127.0.0.1", self.local_control_port)
-        self.rpc_key  = RNS.Identity.full_hash(RNS.Transport.identity.get_private_key())
+        if self.rpc_key == None:
+            self.rpc_key  = RNS.Identity.full_hash(RNS.Transport.identity.get_private_key())
         
         if self.is_shared_instance:
             self.rpc_listener = multiprocessing.connection.Listener(self.rpc_addr, authkey=self.rpc_key)
@@ -359,6 +361,13 @@ class Reticulum:
                 if option == "instance_control_port":
                     value = int(self.config["reticulum"][option])
                     self.local_control_port = value
+                if option == "rpc_key":
+                    try:
+                        value = bytes.fromhex(self.config["reticulum"][option])
+                        self.rpc_key = value
+                    except Exception as e:
+                        RNS.log("Invalid shared instance RPC key specified, falling back to default key", RNS.LOG_ERROR)
+                        self.rpc_key = None
                 if option == "enable_transport":
                     v = self.config["reticulum"].as_bool(option)
                     if v == True:
@@ -447,6 +456,23 @@ class Reticulum:
                             if c["pass_phrase"] != "":
                                 ifac_netkey = c["pass_phrase"]
                                 
+                        ingress_control = True
+                        if "ingress_control" in c: ingress_control = c.as_bool("ingress_control")
+                        ic_max_held_announces = None
+                        if "ic_max_held_announces" in c: ic_max_held_announces = c.as_int("ic_max_held_announces")
+                        ic_burst_hold = None
+                        if "ic_burst_hold" in c: ic_burst_hold = c.as_float("ic_burst_hold")
+                        ic_burst_freq_new = None
+                        if "ic_burst_freq_new" in c: ic_burst_freq_new = c.as_float("ic_burst_freq_new")
+                        ic_burst_freq = None
+                        if "ic_burst_freq" in c: ic_burst_freq = c.as_float("ic_burst_freq")
+                        ic_new_time = None
+                        if "ic_new_time" in c: ic_new_time = c.as_float("ic_new_time")
+                        ic_burst_penalty = None
+                        if "ic_burst_penalty" in c: ic_burst_penalty = c.as_float("ic_burst_penalty")
+                        ic_held_release_interval = None
+                        if "ic_held_release_interval" in c: ic_held_release_interval = c.as_float("ic_held_release_interval")
+
                         configured_bitrate = None
                         if "bitrate" in c:
                             if c.as_int("bitrate") >= Reticulum.MINIMUM_BITRATE:
@@ -884,6 +910,14 @@ class Reticulum:
                                     interface.announce_rate_target = announce_rate_target
                                     interface.announce_rate_grace = announce_rate_grace
                                     interface.announce_rate_penalty = announce_rate_penalty
+                                    interface.ingress_control = ingress_control
+                                    if ic_max_held_announces != None: interface.ic_max_held_announces = ic_max_held_announces
+                                    if ic_burst_hold != None: interface.ic_burst_hold = ic_burst_hold
+                                    if ic_burst_freq_new != None: interface.ic_burst_freq_new = ic_burst_freq_new
+                                    if ic_burst_freq != None: interface.ic_burst_freq = ic_burst_freq
+                                    if ic_new_time != None: interface.ic_new_time = ic_new_time
+                                    if ic_burst_penalty != None: interface.ic_burst_penalty = ic_burst_penalty
+                                    if ic_held_release_interval != None: interface.ic_held_release_interval = ic_held_release_interval
 
                                     interface.ifac_netname = ifac_netname
                                     interface.ifac_netkey = ifac_netkey
@@ -1052,6 +1086,9 @@ class Reticulum:
                     if path == "path":
                         rpc_connection.send(self.drop_path(call["destination_hash"]))
 
+                    if path == "all_via":
+                        rpc_connection.send(self.drop_all_via(call["destination_hash"]))
+
                     if path == "announce_queues":
                         rpc_connection.send(self.drop_announce_queues())
 
@@ -1143,6 +1180,9 @@ class Reticulum:
                 ifstats["name"] = str(interface)
                 ifstats["rxb"] = interface.rxb
                 ifstats["txb"] = interface.txb
+                ifstats["incoming_announce_frequency"] = interface.incoming_announce_frequency()
+                ifstats["outgoing_announce_frequency"] = interface.outgoing_announce_frequency()
+                ifstats["held_announces"] = len(interface.held_announces)
                 ifstats["status"] = interface.online
                 ifstats["mode"] = interface.mode
 
@@ -1213,6 +1253,22 @@ class Reticulum:
         else:
             return RNS.Transport.expire_path(destination)
 
+    def drop_all_via(self, transport_hash):
+        if self.is_connected_to_shared_instance:
+            rpc_connection = multiprocessing.connection.Client(self.rpc_addr, authkey=self.rpc_key)
+            rpc_connection.send({"drop": "all_via", "destination_hash": transport_hash})
+            response = rpc_connection.recv()
+            return response
+
+        else:
+            dropped_count = 0
+            for destination_hash in RNS.Transport.destination_table:
+                if RNS.Transport.destination_table[destination_hash][1] == transport_hash:
+                    RNS.Transport.expire_path(destination_hash)
+                    dropped_count += 1
+
+            return dropped_count
+
     def drop_announce_queues(self):
         if self.is_connected_to_shared_instance:
             rpc_connection = multiprocessing.connection.Client(self.rpc_addr, authkey=self.rpc_key)

RNS/Transport.py

@@ -1,6 +1,6 @@
 # MIT License
 #
-# Copyright (c) 2016-2022 Mark Qvist / unsigned.io
+# Copyright (c) 2016-2023 Mark Qvist / unsigned.io and contributors.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -128,6 +128,8 @@ class Transport:
     hashlist_maxsize         = 1000000
     tables_last_culled       = 0.0
     tables_cull_interval     = 5.0
+    interface_last_jobs      = 0.0
+    interface_jobs_interval  = 5.0
 
     identity = None
 
@@ -352,12 +354,12 @@ class Transport:
 
                 # Process announces needing retransmission
                 if time.time() > Transport.announces_last_checked+Transport.announces_check_interval:
+                    completed_announces = []
                     for destination_hash in Transport.announce_table:
                         announce_entry = Transport.announce_table[destination_hash]
                         if announce_entry[2] > Transport.PATHFINDER_R:
                             RNS.log("Completed announce processing for "+RNS.prettyhexrep(destination_hash)+", retry limit reached", RNS.LOG_EXTREME)
-                            Transport.announce_table.pop(destination_hash)
-                            break
+                            completed_announces.append(destination_hash)
                         else:
                             if time.time() > announce_entry[1]:
                                 announce_entry[1] = time.time() + Transport.PATHFINDER_G + Transport.PATHFINDER_RW
@@ -404,6 +406,10 @@ class Transport:
                                     Transport.announce_table[destination_hash] = held_entry
                                     RNS.log("Reinserting held announce into table", RNS.LOG_DEBUG)
 
+                    for destination_hash in completed_announces:
+                        if destination_hash in Transport.announce_table:
+                            Transport.announce_table.pop(destination_hash)
+
                     Transport.announces_last_checked = time.time()
 
 
@@ -604,6 +610,11 @@ class Transport:
 
                     Transport.tables_last_culled = time.time()
 
+                if time.time() > Transport.interface_last_jobs + Transport.interface_jobs_interval:
+                    for interface in Transport.interfaces:
+                        interface.process_held_announces()
+                    Transport.interface_last_jobs = time.time()
+
             else:
                 # Transport jobs were locked, do nothing
                 pass
@@ -883,6 +894,8 @@ class Transport:
                         # thread.start()
 
                         Transport.transmit(interface, packet.raw)
+                        if packet.packet_type == RNS.Packet.ANNOUNCE:
+                            interface.sent_announce()
                         sent = True
 
         if sent:
@@ -1036,6 +1049,7 @@ class Transport:
         
         packet = RNS.Packet(None, raw)
         if not packet.unpack():
+            Transport.jobs_locked = False
             return
             
         packet.receiving_interface = interface
@@ -1049,7 +1063,7 @@ class Transport:
                         Transport.local_client_rssi_cache.append([packet.packet_hash, packet.rssi])
 
                         while len(Transport.local_client_rssi_cache) > Transport.LOCAL_CLIENT_CACHE_MAXSIZE:
-                            Transport.local_client_rssi_cache.pop()
+                            Transport.local_client_rssi_cache.pop(0)
 
             if hasattr(interface, "r_stat_snr"):
                 if interface.r_stat_rssi != None:
@@ -1058,7 +1072,7 @@ class Transport:
                         Transport.local_client_snr_cache.append([packet.packet_hash, packet.snr])
 
                         while len(Transport.local_client_snr_cache) > Transport.LOCAL_CLIENT_CACHE_MAXSIZE:
-                            Transport.local_client_snr_cache.pop()
+                            Transport.local_client_snr_cache.pop(0)
 
         if len(Transport.local_client_interfaces) > 0:
             if Transport.is_local_client_interface(interface):
@@ -1117,6 +1131,7 @@ class Transport:
                 # normal processing.
                 if packet.context == RNS.Packet.CACHE_REQUEST:
                     if Transport.cache_request_packet(packet):
+                        Transport.jobs_locked = False
                         return
 
                 # If the packet is in transport, check whether we
@@ -1223,8 +1238,21 @@ class Transport:
             # announces, queueing rebroadcasts of these, and removal
             # of queued announce rebroadcasts once handed to the next node.
             if packet.packet_type == RNS.Packet.ANNOUNCE:
+                if interface != None and RNS.Identity.validate_announce(packet, only_validate_signature=True):
+                    interface.received_announce()
+
+                if not packet.destination_hash in Transport.destination_table:
+                    # This is an unknown destination, and we'll apply
+                    # potential ingress limiting. Already known
+                    # destinations will have re-announces controlled
+                    # by normal announce rate limiting.
+                    if interface.should_ingress_limit():
+                        interface.hold_announce(packet)
+                        Transport.jobs_locked = False
+                        return
+
                 local_destination = next((d for d in Transport.destinations if d.hash == packet.destination_hash), None)
-                if local_destination == None and RNS.Identity.validate_announce(packet): 
+                if local_destination == None and RNS.Identity.validate_announce(packet):
                     if packet.transport_id != None:
                         received_from = packet.transport_id
                         
@@ -1316,7 +1344,7 @@ class Transport:
                             should_add = True
 
                         if should_add:
-                            now                = time.time()
+                            now = time.time()
 
                             rate_blocked = False
                             if packet.context != RNS.Packet.PATH_RESPONSE and packet.receiving_interface.announce_rate_target != None:

RNS/Utilities/rncp.py

@@ -321,7 +321,7 @@ def fetch(configdir, verbosity = 0, quietness = 0, destination = None, file = No
         if silent:
             print("Establishing link with "+RNS.prettyhexrep(destination_hash))
         else:
-            print("\r                                                            \rEstablishing link with "+RNS.prettyhexrep(destination_hash)+" ", end=" ")
+            print("\r                                                            \rEstablishing link with "+RNS.prettyhexrep(destination_hash)+"  ", end=" ")
 
     listener_identity = RNS.Identity.recall(destination_hash)
     listener_destination = RNS.Destination(

RNS/Utilities/rnid.py

@@ -196,7 +196,7 @@ def main():
                 if args.hash:
                     try:
                         aspects = args.hash.split(".")
-                        if not len(aspects) > 1:
+                        if not len(aspects) > 0:
                             RNS.log("Invalid destination aspects specified", RNS.LOG_ERROR)
                             exit(32)
                         else:

RNS/Utilities/rnir.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+
+# MIT License
+#
+# Copyright (c) 2023 Mark Qvist / unsigned.io
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import RNS
+import argparse
+import time
+
+from RNS._version import __version__
+
+
+def program_setup(configdir, verbosity = 0, quietness = 0, service = False):
+    targetverbosity = verbosity-quietness
+
+    if service:
+        targetlogdest  = RNS.LOG_FILE
+        targetverbosity = None
+    else:
+        targetlogdest  = RNS.LOG_STDOUT
+
+    reticulum = RNS.Reticulum(configdir=configdir, verbosity=targetverbosity, logdest=targetlogdest)
+    exit(0)
+
+def main():
+    try:
+        parser = argparse.ArgumentParser(description="Reticulum Distributed Identity Resolver")
+        parser.add_argument("--config", action="store", default=None, help="path to alternative Reticulum config directory", type=str)
+        parser.add_argument('-v', '--verbose', action='count', default=0)
+        parser.add_argument('-q', '--quiet', action='count', default=0)
+        parser.add_argument("--exampleconfig", action='store_true', default=False, help="print verbose configuration example to stdout and exit")
+        parser.add_argument("--version", action="version", version="ir {version}".format(version=__version__))
+        
+        args = parser.parse_args()
+
+        if args.exampleconfig:
+            print(__example_rns_config__)
+            exit()
+
+        if args.config:
+            configarg = args.config
+        else:
+            configarg = None
+
+        program_setup(configdir = configarg, verbosity=args.verbose, quietness=args.quiet)
+
+    except KeyboardInterrupt:
+        print("")
+        exit()
+
+__example_rns_config__ = '''# This is an example Identity Resolver file.
+'''
+
+if __name__ == "__main__":
+    main()

RNS/Utilities/rnpath.py

@@ -30,7 +30,7 @@ import argparse
 from RNS._version import __version__
 
 
-def program_setup(configdir, table, rates, drop, destination_hexhash, verbosity, timeout, drop_queues):
+def program_setup(configdir, table, rates, drop, destination_hexhash, verbosity, timeout, drop_queues, drop_via):
     if table:
         destination_hash = None
         if destination_hexhash != None:
@@ -155,6 +155,29 @@ def program_setup(configdir, table, rates, drop, destination_hexhash, verbosity,
             sys.exit(1)
 
 
+    elif drop_via:
+        try:
+            dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH//8)*2
+            if len(destination_hexhash) != dest_len:
+                raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
+            try:
+                destination_hash = bytes.fromhex(destination_hexhash)
+            except Exception as e:
+                raise ValueError("Invalid destination entered. Check your input.")
+        except Exception as e:
+            print(str(e))
+            sys.exit(1)
+
+
+        reticulum = RNS.Reticulum(configdir = configdir, loglevel = 3+verbosity)
+
+        if reticulum.drop_all_via(destination_hash):
+            print("Dropped all paths via "+RNS.prettyhexrep(destination_hash))
+        else:
+            print("Unable to drop paths via "+RNS.prettyhexrep(destination_hash)+". Does the transport instance exist?")
+            sys.exit(1)
+
+
     else:
         try:
             dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH//8)*2
@@ -256,6 +279,13 @@ def main():
             default=False
         )
 
+        parser.add_argument(
+            "-x", "--drop-via",
+            action="store_true",
+            help="drop all paths via specified transport instance",
+            default=False
+        )
+
         parser.add_argument(
             "-w",
             action="store",
@@ -282,7 +312,7 @@ def main():
         else:
             configarg = None
 
-        if not args.drop_announces and not args.table and not args.rates and not args.destination:
+        if not args.drop_announces and not args.table and not args.rates and not args.destination and not args.drop_via:
             print("")
             parser.print_help()
             print("")
@@ -296,6 +326,7 @@ def main():
                 verbosity = args.verbose,
                 timeout = args.w,
                 drop_queues = args.drop_announces,
+                drop_via = args.drop_via,
             )
             sys.exit(0)
 

RNS/Utilities/rnprobe.py

@@ -31,8 +31,9 @@ import argparse
 from RNS._version import __version__
 
 DEFAULT_PROBE_SIZE = 16
+DEFAULT_TIMEOUT = 15
 
-def program_setup(configdir, destination_hexhash, size=None, full_name = None, verbosity = 0):
+def program_setup(configdir, destination_hexhash, size=None, full_name = None, verbosity = 0, timeout=None):
     if size == None: size = DEFAULT_PROBE_SIZE
     if full_name == None:
         print("The full destination name including application name aspects must be specified for the destination")
@@ -72,14 +73,19 @@ def program_setup(configdir, destination_hexhash, size=None, full_name = None, v
         print("Path to "+RNS.prettyhexrep(destination_hash)+" requested  ", end=" ")
         sys.stdout.flush()
 
+    _timeout = time.time() + (timeout or DEFAULT_TIMEOUT)
     i = 0
     syms = "⢄⢂⢁⡁⡈⡐⡠"
-    while not RNS.Transport.has_path(destination_hash):
+    while not RNS.Transport.has_path(destination_hash) and not time.time() > _timeout:
         time.sleep(0.1)
         print(("\b\b"+syms[i]+" "), end="")
         sys.stdout.flush()
         i = (i+1)%len(syms)
 
+    if time.time() > _timeout:
+        print("\r                                                          \rPath request timed out")
+        exit(1)
+
     server_identity = RNS.Identity.recall(destination_hash)
 
     request_destination = RNS.Destination(
@@ -95,7 +101,7 @@ def program_setup(configdir, destination_hexhash, size=None, full_name = None, v
         probe.pack()
     except OSError:
         print("Error: Probe packet size of "+str(len(probe.raw))+" bytes exceed MTU of "+str(RNS.Reticulum.MTU)+" bytes")
-        exit(1)
+        exit(3)
 
     receipt = probe.send()
 
@@ -109,56 +115,66 @@ def program_setup(configdir, destination_hexhash, size=None, full_name = None, v
 
     print("\rSent "+str(size)+" byte probe to "+RNS.prettyhexrep(destination_hash)+more+"  ", end=" ")
 
+    _timeout = time.time() + (timeout or DEFAULT_TIMEOUT)
     i = 0
-    while not receipt.status == RNS.PacketReceipt.DELIVERED:
+    while receipt.status == RNS.PacketReceipt.SENT and not time.time() > _timeout:
         time.sleep(0.1)
         print(("\b\b"+syms[i]+" "), end="")
         sys.stdout.flush()
         i = (i+1)%len(syms)
 
+    if time.time() > _timeout:
+        print("\r                                                          \rProbe timed out")
+        exit(2)
+
     print("\b\b ")
     sys.stdout.flush()
 
-    hops = RNS.Transport.hops_to(destination_hash)
-    if hops != 1:
-        ms = "s"
-    else:
-        ms = ""
+    if receipt.status == RNS.PacketReceipt.DELIVERED:
+        hops = RNS.Transport.hops_to(destination_hash)
+        if hops != 1:
+            ms = "s"
+        else:
+            ms = ""
 
-    rtt = receipt.get_rtt()
-    if (rtt >= 1):
-        rtt = round(rtt, 3)
-        rttstring = str(rtt)+" seconds"
-    else:
-        rtt = round(rtt*1000, 3)
-        rttstring = str(rtt)+" milliseconds"
+        rtt = receipt.get_rtt()
+        if (rtt >= 1):
+            rtt = round(rtt, 3)
+            rttstring = str(rtt)+" seconds"
+        else:
+            rtt = round(rtt*1000, 3)
+            rttstring = str(rtt)+" milliseconds"
 
-    reception_stats = ""
-    if reticulum.is_connected_to_shared_instance:
-        reception_rssi = reticulum.get_packet_rssi(receipt.proof_packet.packet_hash)
-        reception_snr  = reticulum.get_packet_snr(receipt.proof_packet.packet_hash)
+        reception_stats = ""
+        if reticulum.is_connected_to_shared_instance:
+            reception_rssi = reticulum.get_packet_rssi(receipt.proof_packet.packet_hash)
+            reception_snr  = reticulum.get_packet_snr(receipt.proof_packet.packet_hash)
 
-        if reception_rssi != None:
-            reception_stats += " [RSSI "+str(reception_rssi)+" dBm]"
-        
-        if reception_snr != None:
-            reception_stats += " [SNR "+str(reception_snr)+" dB]"
-
-    else:
-        if receipt.proof_packet != None:
-            if receipt.proof_packet.rssi != None:
-                reception_stats += " [RSSI "+str(receipt.proof_packet.rssi)+" dBm]"
+            if reception_rssi != None:
+                reception_stats += " [RSSI "+str(reception_rssi)+" dBm]"
             
-            if receipt.proof_packet.snr != None:
-                reception_stats += " [SNR "+str(receipt.proof_packet.snr)+" dB]"
+            if reception_snr != None:
+                reception_stats += " [SNR "+str(reception_snr)+" dB]"
 
-    print(
-        "Valid reply received from "+
-        RNS.prettyhexrep(receipt.destination.hash)+
-        "\nRound-trip time is "+rttstring+
-        " over "+str(hops)+" hop"+ms+
-        reception_stats
-    )
+        else:
+            if receipt.proof_packet != None:
+                if receipt.proof_packet.rssi != None:
+                    reception_stats += " [RSSI "+str(receipt.proof_packet.rssi)+" dBm]"
+                
+                if receipt.proof_packet.snr != None:
+                    reception_stats += " [SNR "+str(receipt.proof_packet.snr)+" dB]"
+
+        print(
+            "Valid reply received from "+
+            RNS.prettyhexrep(receipt.destination.hash)+
+            "\nRound-trip time is "+rttstring+
+            " over "+str(hops)+" hop"+ms+
+            reception_stats
+        )
+
+    else:
+        print("\r                                                          \rProbe timed out")
+        exit(2)
 
     
 
@@ -168,6 +184,7 @@ def main():
 
         parser.add_argument("--config", action="store", default=None, help="path to alternative Reticulum config directory", type=str)
         parser.add_argument("-s", "--size", action="store", default=None, help="size of probe packet payload in bytes", type=int)
+        parser.add_argument("-t", "--timeout", metavar="seconds", action="store", default=None, help="timeout before giving up", type=float)
         parser.add_argument("--version", action="version", version="rnprobe {version}".format(version=__version__))
         parser.add_argument("full_name", nargs="?", default=None, help="full destination name in dotted notation", type=str)
         parser.add_argument("destination_hash", nargs="?", default=None, help="hexadecimal hash of the destination", type=str)

RNS/Utilities/rnsd.py

@@ -112,6 +112,17 @@ shared_instance_port = 37428
 instance_control_port = 37429
 
 
+# On systems where running instances may not have access
+# to the same shared Reticulum configuration directory,
+# it is still possible to allow full interactivity for
+# running instances, by manually specifying a shared RPC
+# key. In almost all cases, this option is not needed, but
+# it can be useful on operating systems such as Android.
+# The key must be specified as bytes in hexadecimal.
+
+# rpc_key = e5c032d3ec4e64a6aca9927ba8ab73336780f6d71790
+
+
 # You can configure Reticulum to panic and forcibly close
 # if an unrecoverable interface error occurs, such as the
 # hardware device for an interface disappearing. This is

RNS/Utilities/rnstatus.py

@@ -46,7 +46,7 @@ def size_str(num, suffix='B'):
 
     return "%.2f%s%s" % (num, last_unit, suffix)
 
-def program_setup(configdir, dispall=False, verbosity=0, name_filter=None,json=False):
+def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=False, astats=False, sorting=None, sort_reverse=False):
     reticulum = RNS.Reticulum(configdir = configdir, loglevel = 3+verbosity)
 
     stats = None
@@ -62,16 +62,38 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None,json=F
                 if isinstance(stats[s], bytes):
                     stats[s] = RNS.hexrep(stats[s], delimit=False)
 
-                for i in stats[s]:
-                    if isinstance(i, dict):
-                        for k in i:
-                            if isinstance(i[k], bytes):
-                                i[k] = RNS.hexrep(i[k], delimit=False)
+                if isinstance(stats[s], dict):
+                    for i in stats[s]:
+                        if isinstance(i, dict):
+                            for k in i:
+                                if isinstance(i[k], bytes):
+                                    i[k] = RNS.hexrep(i[k], delimit=False)
 
             print(json.dumps(stats))
             exit()
+
+        interfaces = stats["interfaces"]
+        if sorting != None and isinstance(sorting, str):
+            sorting = sorting.lower()
+            if sorting == "rate" or sorting == "bitrate":
+                interfaces.sort(key=lambda i: i["bitrate"], reverse=not sort_reverse)
+            if sorting == "rx":
+                interfaces.sort(key=lambda i: i["rxb"], reverse=not sort_reverse)
+            if sorting == "tx":
+                interfaces.sort(key=lambda i: i["txb"], reverse=not sort_reverse)
+            if sorting == "traffic":
+                interfaces.sort(key=lambda i: i["rxb"]+i["txb"], reverse=not sort_reverse)
+            if sorting == "announces" or sorting == "announce":
+                interfaces.sort(key=lambda i: i["incoming_announce_frequency"]+i["outgoing_announce_frequency"], reverse=not sort_reverse)
+            if sorting == "arx":
+                interfaces.sort(key=lambda i: i["incoming_announce_frequency"], reverse=not sort_reverse)
+            if sorting == "atx":
+                interfaces.sort(key=lambda i: i["outgoing_announce_frequency"], reverse=not sort_reverse)
+            if sorting == "held":
+                interfaces.sort(key=lambda i: i["held_announces"], reverse=not sort_reverse)
+
             
-        for ifstat in stats["interfaces"]:
+        for ifstat in interfaces:
             name = ifstat["name"]
 
             if dispall or not (
@@ -113,7 +135,7 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None,json=F
                                 else:
                                     spec_str = " programs"
 
-                                clients_string = "Serving : "+str(cnum)+spec_str
+                                clients_string = "Serving   : "+str(cnum)+spec_str
                             elif name.startswith("I2PInterface["):
                                 if "i2p_connectable" in ifstat and ifstat["i2p_connectable"] == True:
                                     cnum = clients
@@ -122,11 +144,11 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None,json=F
                                     else:
                                         spec_str = " connected I2P endpoints"
 
-                                    clients_string = "Peers   : "+str(cnum)+spec_str
+                                    clients_string = "Peers     : "+str(cnum)+spec_str
                                 else:
                                     clients_string = ""
                             else:
-                                clients_string = "Clients : "+str(clients)
+                                clients_string = "Clients   : "+str(clients)
 
                         else:
                             clients = None
@@ -134,51 +156,62 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None,json=F
                         print(" {n}".format(n=ifstat["name"]))
 
                         if "ifac_netname" in ifstat and ifstat["ifac_netname"] != None:
-                            print("    Network : {nn}".format(nn=ifstat["ifac_netname"]))
+                            print("    Network   : {nn}".format(nn=ifstat["ifac_netname"]))
 
-                        print("    Status  : {ss}".format(ss=ss))
+                        print("    Status    : {ss}".format(ss=ss))
 
                         if clients != None and clients_string != "":
                             print("    "+clients_string)
 
                         if not (name.startswith("Shared Instance[") or name.startswith("TCPInterface[Client") or name.startswith("LocalInterface[")):
-                            print("    Mode    : {mode}".format(mode=modestr))
+                            print("    Mode      : {mode}".format(mode=modestr))
 
                         if "bitrate" in ifstat and ifstat["bitrate"] != None:
-                            print("    Rate    : {ss}".format(ss=speed_str(ifstat["bitrate"])))
+                            print("    Rate      : {ss}".format(ss=speed_str(ifstat["bitrate"])))
 
                         if "airtime_short" in ifstat and "airtime_long" in ifstat:
-                            print("    Airtime : {atl}% (1h), {ats}% (15s)".format(ats=str(ifstat["airtime_short"]),atl=str(ifstat["airtime_long"])))
+                            print("    Airtime   : {ats}% (15s), {atl}% (1h)".format(ats=str(ifstat["airtime_short"]),atl=str(ifstat["airtime_long"])))
                         
                         if "channel_load_short" in ifstat and "channel_load_long" in ifstat:
-                            print("    Ch.Load : {atl}% (1h), {ats}% (15s)".format(ats=str(ifstat["channel_load_short"]),atl=str(ifstat["channel_load_long"])))
+                            print("    Ch.Load   : {ats}% (15s), {atl}% (1h)".format(ats=str(ifstat["channel_load_short"]),atl=str(ifstat["channel_load_long"])))
                         
                         if "peers" in ifstat and ifstat["peers"] != None:
-                            print("    Peers   : {np} reachable".format(np=ifstat["peers"]))
+                            print("    Peers     : {np} reachable".format(np=ifstat["peers"]))
 
                         if "tunnelstate" in ifstat and ifstat["tunnelstate"] != None:
-                            print("    I2P     : {ts}".format(ts=ifstat["tunnelstate"]))
+                            print("    I2P       : {ts}".format(ts=ifstat["tunnelstate"]))
 
                         if "ifac_signature" in ifstat and ifstat["ifac_signature"] != None:
                             sigstr = "<…"+RNS.hexrep(ifstat["ifac_signature"][-5:], delimit=False)+">"
-                            print("    Access  : {nb}-bit IFAC by {sig}".format(nb=ifstat["ifac_size"]*8, sig=sigstr))
+                            print("    Access    : {nb}-bit IFAC by {sig}".format(nb=ifstat["ifac_size"]*8, sig=sigstr))
                         
                         if "i2p_b32" in ifstat and ifstat["i2p_b32"] != None:
-                            print("    I2P B32 : {ep}".format(ep=str(ifstat["i2p_b32"])))
+                            print("    I2P B32   : {ep}".format(ep=str(ifstat["i2p_b32"])))
 
-                        if "announce_queue" in ifstat and ifstat["announce_queue"] != None and ifstat["announce_queue"] > 0:
+                        if astats and "announce_queue" in ifstat and ifstat["announce_queue"] != None and ifstat["announce_queue"] > 0:
                             aqn = ifstat["announce_queue"]
                             if aqn == 1:
-                                print("    Queued  : {np} announce".format(np=aqn))
+                                print("    Queued    : {np} announce".format(np=aqn))
                             else:
-                                print("    Queued  : {np} announces".format(np=aqn))
+                                print("    Queued    : {np} announces".format(np=aqn))
                         
-                        print("    Traffic : {txb}↑\n              {rxb}↓".format(rxb=size_str(ifstat["rxb"]), txb=size_str(ifstat["txb"])))
+                        if astats and "held_announces" in ifstat and ifstat["held_announces"] != None and ifstat["held_announces"] > 0:
+                            aqn = ifstat["held_announces"]
+                            if aqn == 1:
+                                print("    Held      : {np} announce".format(np=aqn))
+                            else:
+                                print("    Held      : {np} announces".format(np=aqn))
+                        
+                        if astats and "incoming_announce_frequency" in ifstat and ifstat["incoming_announce_frequency"] != None:
+                            print("    Announces : {iaf}↑".format(iaf=RNS.prettyfrequency(ifstat["outgoing_announce_frequency"])))
+                            print("                {iaf}↓".format(iaf=RNS.prettyfrequency(ifstat["incoming_announce_frequency"])))
+
+                        print("    Traffic   : {txb}↑\n                {rxb}↓".format(rxb=size_str(ifstat["rxb"]), txb=size_str(ifstat["txb"])))
 
         if "transport_id" in stats and stats["transport_id"] != None:
             print("\n Transport Instance "+RNS.prettyhexrep(stats["transport_id"])+" running")
             if "probe_responder" in stats and stats["probe_responder"] != None:
-                print(" Probe responder at "+RNS.prettyhexrep(stats["probe_responder"]))
+                print(" Probe responder at "+RNS.prettyhexrep(stats["probe_responder"])+ " active")
             print(" Uptime is "+RNS.prettytime(stats["transport_uptime"]))
 
         print("")
@@ -200,6 +233,31 @@ def main():
             default=False
         )
         
+        parser.add_argument(
+            "-A",
+            "--announce-stats",
+            action="store_true",
+            help="show announce stats",
+            default=False
+        )
+        
+        parser.add_argument(
+            "-s",
+            "--sort",
+            action="store",
+            help="sort interfaces by [rate, traffic, rx, tx, announces, arx, atx, held]",
+            default=None,
+            type=str
+        )
+        
+        parser.add_argument(
+            "-r",
+            "--reverse",
+            action="store_true",
+            help="reverse sorting",
+            default=False,
+        )
+        
         parser.add_argument(
             "-j",
             "--json",
@@ -219,7 +277,16 @@ def main():
         else:
             configarg = None
 
-        program_setup(configdir = configarg, dispall = args.all, verbosity=args.verbose, name_filter=args.filter, json=args.json)
+        program_setup(
+            configdir = configarg,
+            dispall = args.all,
+            verbosity=args.verbose,
+            name_filter=args.filter,
+            json=args.json,
+            astats=args.announce_stats,
+            sorting=args.sort,
+            sort_reverse=args.reverse,
+        )
 
     except KeyboardInterrupt:
         print("")

RNS/__init__.py

@@ -1,6 +1,6 @@
 # MIT License
 #
-# Copyright (c) 2016-2022 Mark Qvist / unsigned.io
+# Copyright (c) 2016-2023 Mark Qvist / unsigned.io and contributors
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -38,6 +38,7 @@ from .Transport import Transport
 from .Destination import Destination
 from .Packet import Packet
 from .Packet import PacketReceipt
+from .Resolver import Resolver
 from .Resource import Resource, ResourceAdvertisement
 from .Cryptography import HKDF
 from .Cryptography import Hashes
@@ -179,6 +180,18 @@ def prettysize(num, suffix='B'):
 
     return "%.2f%s%s" % (num, last_unit, suffix)
 
+def prettyfrequency(hz, suffix="Hz"):
+    num = hz*1e6
+    units = ["µ", "m", "", "K","M","G","T","P","E","Z"]
+    last_unit = "Y"
+
+    for unit in units:
+        if abs(num) < 1000.0:
+            return "%.2f %s%s" % (num, unit, suffix)
+        num /= 1000.0
+
+    return "%.2f%s%s" % (num, last_unit, suffix)
+
 def prettytime(time, verbose=False):
     days = int(time // (24 * 3600))
     time = time % (24 * 3600)

RNS/_version.py

@@ -1 +1 @@
-__version__ = "0.6.0"
+__version__ = "0.6.2"

Roadmap.md

@@ -14,14 +14,14 @@ This document outlines the currently established development roadmap for Reticul
 ## Currently Active Work Areas
 For each release cycle of Reticulum, improvements and additions from the five [Primary Efforts](#primary-efforts) are selected as active work areas, and can be expected to be included in the upcoming releases within that cycle. While not entirely set in stone for each release cycle, they serve as a pointer of what to expect in the near future.
 
-- The current `0.5.x` release cycle aims at completing
-  - [x] Reach feature-completion of the Reticulum API
-  - [x] Improve performance and efficiency of the `Buffer` and `Channel` API
-  - [x] Add bluetooth pairing code output to rnodeconf
+- The current `0.6.x` release cycle aims at completing
   - [ ] Overhauling and updating the documentation
-  - [ ] Performance and memory optimisations of the Python reference implementation
-  - [ ] Fixing potential bugs
+  - [ ] Distributed Destination Naming System
+  - [ ] Create a standalone RNS Daemon app for Android
+  - [ ] Network-wide path balancing
   - [ ] Add automatic retries to all use cases of the `Request` API
+  - [ ] Performance and memory optimisations of the Python reference implementation
+  - [ ] Fixing bugs discovered while operating Reticulum systems and applications
 
 ## Primary Efforts
 The development path for Reticulum is currently laid out in five distinct areas: *Comprehensibility*, *Universality*, *Functionality*, *Usability & Utility* and *Interfaceability*. Conceptualising the development of Reticulum into these areas serves to advance the implementation and work towards the Foundational Goals & Values of Reticulum.
@@ -40,12 +40,12 @@ These efforts are aimed at improving the ease of which Reticulum is understood,
         - Update NomadNet screenshots
         - Update Sideband screenshots
     - Installation
-        - Add a *Reticulum On Raspberry Pi* section
-        - Update *Reticulum On Android* section if necessary
-        - Update Android install documentation.
+        - [x] Add a *Reticulum On Raspberry Pi* section
+        - [x] Update *Reticulum On Android* section if necessary
+        - [x] Update Android install documentation.
     - Communications hardware section
         - Add information about RNode external displays.
-        - Packet radio modems.
+        - [x] Packet radio modems.
         - Possibly add other relevant types here as well.
     - Setup *Best Practices For...* / *Installation Examples* section.
         - Home or office (example)

docs/manual/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 68929b7207a84262cbd1b68cc50e2489
+config: 46393e4581f8a313437c181a16088a4d
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/manual/_sources/interfaces.rst.txt

@@ -1,9 +1,9 @@
 
 .. _interfaces-main:
 
-********************
-Supported Interfaces
-********************
+**********************
+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
@@ -761,3 +761,74 @@ conserve bandwidth, while very fast networks can support applications that
 need very 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.
+
+**It's important to note** 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 announce 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.
+

docs/manual/_sources/using.rst.txt

@@ -99,6 +99,17 @@ configuration file is created. The default configuration looks like this:
   instance_control_port = 37429
 
 
+  # On systems where running instances may not have access
+  # to the same shared Reticulum configuration directory,
+  # it is still possible to allow full interactivity for
+  # running instances, by manually specifying a shared RPC
+  # key. In almost all cases, this option is not needed, but
+  # it can be useful on operating systems such as Android.
+  # The key must be specified as bytes in hexadecimal.
+
+  # rpc_key = e5c032d3ec4e64a6aca9927ba8ab73336780f6d71790
+
+
   # You can configure Reticulum to panic and forcibly close
   # if an unrecoverable interface error occurs, such as the
   # hardware device for an interface disappearing. This is
@@ -301,19 +312,23 @@ Filter output to only show some interfaces:
 
 .. code:: text
 
-  usage: rnstatus.py [-h] [--config CONFIG] [--version] [-a] [-j] [-v] [filter]
+  usage: rnstatus.py [-h] [--config CONFIG] [--version] [-a] [-A] [-s SORT]
+                     [-r] [-j] [-v] [filter]
 
   Reticulum Network Stack Status
 
   positional arguments:
-    filter           only display interfaces with names including filter
+    filter                only display interfaces with names including filter
 
   options:
-    -h, --help       show this help message and exit
-    --config CONFIG  path to alternative Reticulum config directory
-    --version        show program's version number and exit
-    -a, --all        show all interfaces
-    -j, --json       output in JSON format
+    -h, --help            show this help message and exit
+    --config CONFIG       path to alternative Reticulum config directory
+    --version             show program's version number and exit
+    -a, --all             show all interfaces
+    -A, --announce-stats  show announce stats
+    -s SORT, --sort SORT  sort interfaces by [rate, traffic, rx, tx, announces, arx, atx, held]
+    -r, --reverse         reverse sorting
+    -j, --json            output in JSON format
     -v, --verbose
 
 
@@ -438,7 +453,7 @@ Resolve path to a destination:
 .. code:: text
 
   usage: rnpath.py [-h] [--config CONFIG] [--version] [-t] [-r] [-d] [-D]
-                   [-w seconds] [-v] [destination]
+                   [-x] [-w seconds] [-v] [destination]
 
   Reticulum Path Discovery Utility
 
@@ -453,6 +468,7 @@ Resolve path to a destination:
     -r, --rates           show announce rate info
     -d, --drop            remove the path to a destination
     -D, --drop-announces  drop all queued announces
+    -x, --drop-via        drop all paths via specified transport instance
     -w seconds            timeout before giving up
     -v, --verbose
 

docs/manual/_static/documentation_options.js

@@ -1,6 +1,6 @@
 var DOCUMENTATION_OPTIONS = {
     URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
-    VERSION: '0.6.0 beta',
+    VERSION: '0.6.2 beta',
     LANGUAGE: 'en',
     COLLAPSE_INDEX: false,
     BUILDER: 'html',

docs/manual/examples.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Support Reticulum" href="support.html" /><link rel="prev" title="Building Networks" href="networks.html" />
 
     <meta name="generator" content="sphinx-7.1.2, furo 2022.09.29.dev1"/>
-        <title>Code Examples - Reticulum Network Stack 0.6.0 beta documentation</title>
+        <title>Code Examples - Reticulum Network Stack 0.6.2 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=a746c00c" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.2 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.2 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -181,7 +181,7 @@
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
-<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Supported Interfaces</a></li>
+<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Code Examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
@@ -258,7 +258,7 @@ program.</p>
     <span class="c1"># Destinations are endpoints in Reticulum, that can be addressed</span>
     <span class="c1"># and communicated with. Destinations can also announce their</span>
     <span class="c1"># existence, which will let the network know they are reachable</span>
-    <span class="c1"># and autoomatically create paths to them, from anywhere else</span>
+    <span class="c1"># and automatically create paths to them, from anywhere else</span>
     <span class="c1"># in the network.</span>
     <span class="n">destination</span> <span class="o">=</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Destination</span><span class="p">(</span>
         <span class="n">identity</span><span class="p">,</span>
@@ -269,7 +269,7 @@ program.</p>
     <span class="p">)</span>
 
     <span class="c1"># We configure the destination to automatically prove all</span>
-    <span class="c1"># packets adressed to it. By doing this, RNS will automatically</span>
+    <span class="c1"># packets addressed to it. By doing this, RNS will automatically</span>
     <span class="c1"># generate a proof for each incoming packet and transmit it</span>
     <span class="c1"># back to the sender of that packet. This will let anyone that</span>
     <span class="c1"># tries to communicate with the destination know whether their</span>
@@ -375,7 +375,7 @@ notifications about announces from relevant destinations.</p>
     <span class="c1"># Destinations are endpoints in Reticulum, that can be addressed</span>
     <span class="c1"># and communicated with. Destinations can also announce their</span>
     <span class="c1"># existence, which will let the network know they are reachable</span>
-    <span class="c1"># and autoomatically create paths to them, from anywhere else</span>
+    <span class="c1"># and automatically create paths to them, from anywhere else</span>
     <span class="c1"># in the network.</span>
     <span class="n">destination_1</span> <span class="o">=</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Destination</span><span class="p">(</span>
         <span class="n">identity</span><span class="p">,</span>
@@ -396,7 +396,7 @@ notifications about announces from relevant destinations.</p>
     <span class="p">)</span>
 
     <span class="c1"># We configure the destinations to automatically prove all</span>
-    <span class="c1"># packets adressed to it. By doing this, RNS will automatically</span>
+    <span class="c1"># packets addressed to it. By doing this, RNS will automatically</span>
     <span class="c1"># generate a proof for each incoming packet and transmit it</span>
     <span class="c1"># back to the sender of that packet. This will let anyone that</span>
     <span class="c1"># tries to communicate with the destination know whether their</span>
@@ -697,7 +697,7 @@ the Packet interface.</p>
     <span class="p">)</span>
 
     <span class="c1"># We configure the destination to automatically prove all</span>
-    <span class="c1"># packets adressed to it. By doing this, RNS will automatically</span>
+    <span class="c1"># packets addressed to it. By doing this, RNS will automatically</span>
     <span class="c1"># generate a proof for each incoming packet and transmit it</span>
     <span class="c1"># back to the sender of that packet.</span>
     <span class="n">echo_destination</span><span class="o">.</span><span class="n">set_proof_strategy</span><span class="p">(</span><span class="n">RNS</span><span class="o">.</span><span class="n">Destination</span><span class="o">.</span><span class="n">PROVE_ALL</span><span class="p">)</span>
@@ -3322,7 +3322,7 @@ interface to efficiently pass files of any size over a Reticulum <a class="refer
       
     </aside>
   </div>
-</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=c96a9f3e"></script>
+</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=2c9eb04b"></script>
     <script src="_static/doctools.js?v=888ff710"></script>
     <script src="_static/sphinx_highlight.js?v=4825356b"></script>
     <script src="_static/scripts/furo.js?v=2c7c1115"></script>

docs/manual/forhumans.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" />
 
     <meta name="generator" content="sphinx-7.1.2, furo 2022.09.29.dev1"/>
-        <title>An Explanation of Reticulum for Human Beings - Reticulum Network Stack 0.6.0 beta documentation</title>
+        <title>An Explanation of Reticulum for Human Beings - Reticulum Network Stack 0.6.2 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=a746c00c" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.2 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.2 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -181,7 +181,7 @@
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
-<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Supported Interfaces</a></li>
+<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
@@ -257,7 +257,7 @@
       
     </aside>
   </div>
-</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=c96a9f3e"></script>
+</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=2c9eb04b"></script>
     <script src="_static/doctools.js?v=888ff710"></script>
     <script src="_static/sphinx_highlight.js?v=4825356b"></script>
     <script src="_static/scripts/furo.js?v=2c7c1115"></script>

docs/manual/genindex.html

@@ -4,7 +4,7 @@
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="#" /><link rel="search" title="Search" href="search.html" />
 
-    <meta name="generator" content="sphinx-7.1.2, furo 2022.09.29.dev1"/><title>Index - Reticulum Network Stack 0.6.0 beta documentation</title>
+    <meta name="generator" content="sphinx-7.1.2, furo 2022.09.29.dev1"/><title>Index - Reticulum Network Stack 0.6.2 beta documentation</title>
 <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=a746c00c" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -139,7 +139,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.2 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -165,7 +165,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.2 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -179,7 +179,7 @@
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
-<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Supported Interfaces</a></li>
+<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
@@ -723,7 +723,7 @@
       
     </aside>
   </div>
-</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=c96a9f3e"></script>
+</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=2c9eb04b"></script>
     <script src="_static/doctools.js?v=888ff710"></script>
     <script src="_static/sphinx_highlight.js?v=4825356b"></script>
     <script src="_static/scripts/furo.js?v=2c7c1115"></script>

docs/manual/gettingstartedfast.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Using Reticulum on Your System" href="using.html" /><link rel="prev" title="What is Reticulum?" href="whatis.html" />
 
     <meta name="generator" content="sphinx-7.1.2, furo 2022.09.29.dev1"/>
-        <title>Getting Started Fast - Reticulum Network Stack 0.6.0 beta documentation</title>
+        <title>Getting Started Fast - Reticulum Network Stack 0.6.2 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=a746c00c" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.2 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.2 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -181,7 +181,7 @@
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
-<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Supported Interfaces</a></li>
+<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
@@ -758,7 +758,7 @@ section of this manual.</p>
       
     </aside>
   </div>
-</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=c96a9f3e"></script>
+</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=2c9eb04b"></script>
     <script src="_static/doctools.js?v=888ff710"></script>
     <script src="_static/sphinx_highlight.js?v=4825356b"></script>
     <script src="_static/scripts/furo.js?v=2c7c1115"></script>

docs/manual/hardware.html

@@ -3,10 +3,10 @@
   <head><meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
     <meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
-<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Supported Interfaces" href="interfaces.html" /><link rel="prev" title="Understanding Reticulum" href="understanding.html" />
+<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Configuring Interfaces" href="interfaces.html" /><link rel="prev" title="Understanding Reticulum" href="understanding.html" />
 
     <meta name="generator" content="sphinx-7.1.2, furo 2022.09.29.dev1"/>
-        <title>Communications Hardware - Reticulum Network Stack 0.6.0 beta documentation</title>
+        <title>Communications Hardware - Reticulum Network Stack 0.6.2 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=a746c00c" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.2 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.2 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -181,7 +181,7 @@
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Communications Hardware</a></li>
-<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Supported Interfaces</a></li>
+<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
@@ -441,7 +441,7 @@ can be used with Reticulum. This includes virtual software modems such as
                 <div class="context">
                   <span>Next</span>
                 </div>
-                <div class="title">Supported Interfaces</div>
+                <div class="title">Configuring Interfaces</div>
               </div>
               <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
             </a>
@@ -519,7 +519,7 @@ can be used with Reticulum. This includes virtual software modems such as
       
     </aside>
   </div>
-</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=c96a9f3e"></script>
+</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=2c9eb04b"></script>
     <script src="_static/doctools.js?v=888ff710"></script>
     <script src="_static/sphinx_highlight.js?v=4825356b"></script>
     <script src="_static/scripts/furo.js?v=2c7c1115"></script>

docs/manual/index.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="What is Reticulum?" href="whatis.html" />
 
     <meta name="generator" content="sphinx-7.1.2, furo 2022.09.29.dev1"/>
-        <title>Reticulum Network Stack 0.6.0 beta documentation</title>
+        <title>Reticulum Network Stack 0.6.2 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=a746c00c" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="#"><div class="brand">Reticulum Network Stack 0.6.0 beta documentation</div></a>
+      <a href="#"><div class="brand">Reticulum Network Stack 0.6.2 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.2 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -181,7 +181,7 @@
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
-<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Supported Interfaces</a></li>
+<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
@@ -330,7 +330,7 @@ to participate in the development of Reticulum itself.</p>
 <li class="toctree-l2"><a class="reference internal" href="hardware.html#packet-radio-modems">Packet Radio Modems</a></li>
 </ul>
 </li>
-<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Supported Interfaces</a><ul>
+<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="interfaces.html#auto-interface">Auto Interface</a></li>
 <li class="toctree-l2"><a class="reference internal" href="interfaces.html#i2p-interface">I2P Interface</a></li>
 <li class="toctree-l2"><a class="reference internal" href="interfaces.html#tcp-server-interface">TCP Server Interface</a></li>
@@ -344,6 +344,7 @@ to participate in the development of Reticulum itself.</p>
 <li class="toctree-l2"><a class="reference internal" href="interfaces.html#common-interface-options">Common Interface Options</a></li>
 <li class="toctree-l2"><a class="reference internal" href="interfaces.html#interface-modes">Interface Modes</a></li>
 <li class="toctree-l2"><a class="reference internal" href="interfaces.html#announce-rate-control">Announce Rate Control</a></li>
+<li class="toctree-l2"><a class="reference internal" href="interfaces.html#new-destination-rate-limiting">New Destination Rate Limiting</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a><ul>
@@ -467,7 +468,7 @@ to participate in the development of Reticulum itself.</p>
       
     </aside>
   </div>
-</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=c96a9f3e"></script>
+</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=2c9eb04b"></script>
     <script src="_static/doctools.js?v=888ff710"></script>
     <script src="_static/sphinx_highlight.js?v=4825356b"></script>
     <script src="_static/scripts/furo.js?v=2c7c1115"></script>

docs/manual/interfaces.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Building Networks" href="networks.html" /><link rel="prev" title="Communications Hardware" href="hardware.html" />
 
     <meta name="generator" content="sphinx-7.1.2, furo 2022.09.29.dev1"/>
-        <title>Supported Interfaces - Reticulum Network Stack 0.6.0 beta documentation</title>
+        <title>Configuring Interfaces - Reticulum Network Stack 0.6.2 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=a746c00c" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.2 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.2 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -181,7 +181,7 @@
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
-<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Supported Interfaces</a></li>
+<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
@@ -221,8 +221,8 @@
           </label>
         </div>
         <article role="main">
-          <section id="supported-interfaces">
-<span id="interfaces-main"></span><h1>Supported Interfaces<a class="headerlink" href="#supported-interfaces" title="Permalink to this heading">#</a></h1>
+          <section id="configuring-interfaces">
+<span id="interfaces-main"></span><h1>Configuring Interfaces<a class="headerlink" href="#configuring-interfaces" title="Permalink to this heading">#</a></h1>
 <p>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
@@ -937,6 +937,91 @@ conserve bandwidth, while very fast networks can support applications that
 need very frequent announces. Reticulum implements these mechanisms to ensure
 that a large span of network types can seamlessly <em>co-exist</em> and interconnect.</p>
 </section>
+<section id="new-destination-rate-limiting">
+<span id="interfaces-ingress-control"></span><h2>New Destination Rate Limiting<a class="headerlink" href="#new-destination-rate-limiting" title="Permalink to this heading">#</a></h2>
+<p>On public interfaces, where anyone may connect and announce new destinations,
+it can be useful to control the rate at which announces for <em>new</em>  destinations are
+processed.</p>
+<p>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.</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 <a class="reference internal" href="#interfaces-tcps"><span class="std std-ref">TCP Server Interface</span></a>
+cannot disrupt processing of incoming announces for other connected clients on the same
+<a class="reference internal" href="#interfaces-tcps"><span class="std std-ref">TCP Server Interface</span></a>. All other clients on the same interface will still have new announces
+processed without interruption.</p>
+<p>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.</p>
+<blockquote>
+<div><ul>
+<li><div class="line-block">
+<div class="line">The <code class="docutils literal notranslate"><span class="pre">ingress_control</span></code> option tells Reticulum whether or not
+to enable announce ingress control on the interface. Defaults to
+<code class="docutils literal notranslate"><span class="pre">True</span></code>.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">The <code class="docutils literal notranslate"><span class="pre">ic_new_time</span></code> option configures how long (in seconds) an
+interface is considered newly spawned. Defaults to <code class="docutils literal notranslate"><span class="pre">2*60*60</span></code> seconds. This
+option is useful on publicly accessible interfaces that spawn new
+sub-interfaces when a new client connects.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">The <code class="docutils literal notranslate"><span class="pre">ic_burst_freq_new</span></code> option sets the maximum announce ingress
+frequency for newly spawned interfaces. Defaults to <code class="docutils literal notranslate"><span class="pre">3.5</span></code>
+announces per second.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">The <code class="docutils literal notranslate"><span class="pre">ic_burst_freq</span></code> option sets the maximum announce ingress
+frequency for other interfaces. Defaults to <code class="docutils literal notranslate"><span class="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><div class="line-block">
+<div class="line">The <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">256</span></code> announces.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">The <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">60</span></code>
+seconds.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">The <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">5*60</span></code>
+seconds.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">The <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">30</span></code> seconds.</div>
+</div>
+</li>
+</ul>
+</div></blockquote>
+</section>
 </section>
 
         </article>
@@ -995,7 +1080,7 @@ that a large span of network types can seamlessly <em>co-exist</em> and intercon
         <div class="toc-tree-container">
           <div class="toc-tree">
             <ul>
-<li><a class="reference internal" href="#">Supported Interfaces</a><ul>
+<li><a class="reference internal" href="#">Configuring Interfaces</a><ul>
 <li><a class="reference internal" href="#auto-interface">Auto Interface</a></li>
 <li><a class="reference internal" href="#i2p-interface">I2P Interface</a></li>
 <li><a class="reference internal" href="#tcp-server-interface">TCP Server Interface</a></li>
@@ -1009,6 +1094,7 @@ that a large span of network types can seamlessly <em>co-exist</em> and intercon
 <li><a class="reference internal" href="#common-interface-options">Common Interface Options</a></li>
 <li><a class="reference internal" href="#interface-modes">Interface Modes</a></li>
 <li><a class="reference internal" href="#announce-rate-control">Announce Rate Control</a></li>
+<li><a class="reference internal" href="#new-destination-rate-limiting">New Destination Rate Limiting</a></li>
 </ul>
 </li>
 </ul>
@@ -1020,7 +1106,7 @@ that a large span of network types can seamlessly <em>co-exist</em> and intercon
       
     </aside>
   </div>
-</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=c96a9f3e"></script>
+</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=2c9eb04b"></script>
     <script src="_static/doctools.js?v=888ff710"></script>
     <script src="_static/sphinx_highlight.js?v=4825356b"></script>
     <script src="_static/scripts/furo.js?v=2c7c1115"></script>

docs/manual/networks.html

@@ -3,10 +3,10 @@
   <head><meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
     <meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
-<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Code Examples" href="examples.html" /><link rel="prev" title="Supported Interfaces" href="interfaces.html" />
+<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Code Examples" href="examples.html" /><link rel="prev" title="Configuring Interfaces" href="interfaces.html" />
 
     <meta name="generator" content="sphinx-7.1.2, furo 2022.09.29.dev1"/>
-        <title>Building Networks - Reticulum Network Stack 0.6.0 beta documentation</title>
+        <title>Building Networks - Reticulum Network Stack 0.6.2 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=a746c00c" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.2 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.2 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -181,7 +181,7 @@
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
-<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Supported Interfaces</a></li>
+<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Building Networks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
@@ -413,7 +413,7 @@ connected outliers are now an integral part of the network.</p>
                   <span>Previous</span>
                 </div>
                 
-                <div class="title">Supported Interfaces</div>
+                <div class="title">Configuring Interfaces</div>
                 
               </div>
             </a>
@@ -467,7 +467,7 @@ connected outliers are now an integral part of the network.</p>
       
     </aside>
   </div>
-</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=c96a9f3e"></script>
+</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=2c9eb04b"></script>
     <script src="_static/doctools.js?v=888ff710"></script>
     <script src="_static/sphinx_highlight.js?v=4825356b"></script>
     <script src="_static/scripts/furo.js?v=2c7c1115"></script>

docs/manual/reference.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="prev" title="Support Reticulum" href="support.html" />
 
     <meta name="generator" content="sphinx-7.1.2, furo 2022.09.29.dev1"/>
-        <title>API Reference - Reticulum Network Stack 0.6.0 beta documentation</title>
+        <title>API Reference - Reticulum Network Stack 0.6.2 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=a746c00c" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.2 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.2 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -181,7 +181,7 @@
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
-<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Supported Interfaces</a></li>
+<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
@@ -850,7 +850,7 @@ unless other app_data is specified in the <em>announce</em> method.</p>
 <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">RNS.</span></span><span class="sig-name descname"><span class="pre">Packet</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">destination</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">create_receipt</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Packet" title="Permalink to this definition">#</a></dt>
 <dd><p>The Packet class is used to create packet instances that can be sent
 over a Reticulum network. Packets will automatically be encrypted if
-they are adressed to a <code class="docutils literal notranslate"><span class="pre">RNS.Destination.SINGLE</span></code> destination,
+they are addressed to a <code class="docutils literal notranslate"><span class="pre">RNS.Destination.SINGLE</span></code> destination,
 <code class="docutils literal notranslate"><span class="pre">RNS.Destination.GROUP</span></code> destination or a <a class="reference internal" href="#api-link"><span class="std std-ref">RNS.Link</span></a>.</p>
 <p>For <code class="docutils literal notranslate"><span class="pre">RNS.Destination.GROUP</span></code> destinations, Reticulum will use the
 pre-shared key configured for the destination. All packets to group
@@ -2013,7 +2013,7 @@ will announce it.</p>
       
     </aside>
   </div>
-</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=c96a9f3e"></script>
+</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=2c9eb04b"></script>
     <script src="_static/doctools.js?v=888ff710"></script>
     <script src="_static/sphinx_highlight.js?v=4825356b"></script>
     <script src="_static/scripts/furo.js?v=2c7c1115"></script>

docs/manual/search.html

@@ -4,7 +4,7 @@
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="#" />
 
-    <meta name="generator" content="sphinx-7.1.2, furo 2022.09.29.dev1"/><title>Search - Reticulum Network Stack 0.6.0 beta documentation</title><link rel="stylesheet" type="text/css" href="_static/pygments.css?v=a746c00c" />
+    <meta name="generator" content="sphinx-7.1.2, furo 2022.09.29.dev1"/><title>Search - Reticulum Network Stack 0.6.2 beta documentation</title><link rel="stylesheet" type="text/css" href="_static/pygments.css?v=a746c00c" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo-extensions.css?digest=30d1aed668e5c3a91c3e3bf6a60b675221979f0e" />
@@ -138,7 +138,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.2 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -164,7 +164,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.2 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="#" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -178,7 +178,7 @@
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
-<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Supported Interfaces</a></li>
+<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
@@ -262,7 +262,7 @@
       
     </aside>
   </div>
-</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=c96a9f3e"></script>
+</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=2c9eb04b"></script>
     <script src="_static/doctools.js?v=888ff710"></script>
     <script src="_static/sphinx_highlight.js?v=4825356b"></script>
     <script src="_static/scripts/furo.js?v=2c7c1115"></script>

docs/manual/support.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="API Reference" href="reference.html" /><link rel="prev" title="Code Examples" href="examples.html" />
 
     <meta name="generator" content="sphinx-7.1.2, furo 2022.09.29.dev1"/>
-        <title>Support Reticulum - Reticulum Network Stack 0.6.0 beta documentation</title>
+        <title>Support Reticulum - Reticulum Network Stack 0.6.2 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=a746c00c" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.2 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.2 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -181,7 +181,7 @@
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
-<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Supported Interfaces</a></li>
+<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Support Reticulum</a></li>
@@ -330,7 +330,7 @@ report issues, suggest functionality and contribute code to Reticulum.</p>
       
     </aside>
   </div>
-</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=c96a9f3e"></script>
+</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=2c9eb04b"></script>
     <script src="_static/doctools.js?v=888ff710"></script>
     <script src="_static/sphinx_highlight.js?v=4825356b"></script>
     <script src="_static/scripts/furo.js?v=2c7c1115"></script>

docs/manual/understanding.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Communications Hardware" href="hardware.html" /><link rel="prev" title="Using Reticulum on Your System" href="using.html" />
 
     <meta name="generator" content="sphinx-7.1.2, furo 2022.09.29.dev1"/>
-        <title>Understanding Reticulum - Reticulum Network Stack 0.6.0 beta documentation</title>
+        <title>Understanding Reticulum - Reticulum Network Stack 0.6.2 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=a746c00c" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.2 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.2 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -181,7 +181,7 @@
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
-<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Supported Interfaces</a></li>
+<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
@@ -1196,7 +1196,7 @@ those risks are acceptable to you.</p>
       
     </aside>
   </div>
-</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=c96a9f3e"></script>
+</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=2c9eb04b"></script>
     <script src="_static/doctools.js?v=888ff710"></script>
     <script src="_static/sphinx_highlight.js?v=4825356b"></script>
     <script src="_static/scripts/furo.js?v=2c7c1115"></script>

docs/manual/using.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Understanding Reticulum" href="understanding.html" /><link rel="prev" title="Getting Started Fast" href="gettingstartedfast.html" />
 
     <meta name="generator" content="sphinx-7.1.2, furo 2022.09.29.dev1"/>
-        <title>Using Reticulum on Your System - Reticulum Network Stack 0.6.0 beta documentation</title>
+        <title>Using Reticulum on Your System - Reticulum Network Stack 0.6.2 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=a746c00c" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.2 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.2 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -181,7 +181,7 @@
 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
-<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Supported Interfaces</a></li>
+<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
@@ -307,6 +307,17 @@ configuration file is created. The default configuration looks like this:</p>
 <span class="n">instance_control_port</span> <span class="o">=</span> <span class="mi">37429</span>
 
 
+<span class="c1"># On systems where running instances may not have access</span>
+<span class="c1"># to the same shared Reticulum configuration directory,</span>
+<span class="c1"># it is still possible to allow full interactivity for</span>
+<span class="c1"># running instances, by manually specifying a shared RPC</span>
+<span class="c1"># key. In almost all cases, this option is not needed, but</span>
+<span class="c1"># it can be useful on operating systems such as Android.</span>
+<span class="c1"># The key must be specified as bytes in hexadecimal.</span>
+
+<span class="c1"># rpc_key = e5c032d3ec4e64a6aca9927ba8ab73336780f6d71790</span>
+
+
 <span class="c1"># You can configure Reticulum to panic and forcibly close</span>
 <span class="c1"># if an unrecoverable interface error occurs, such as the</span>
 <span class="c1"># hardware device for an interface disappearing. This is</span>
@@ -481,19 +492,23 @@ Reticulum Transport Instance &lt;5245a8efe1788c6a1cd36144a270e13b&gt; running
 </pre></div>
 </div>
 <p><strong>All Command-Line Options</strong></p>
-<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnstatus.py [-h] [--config CONFIG] [--version] [-a] [-j] [-v] [filter]
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnstatus.py [-h] [--config CONFIG] [--version] [-a] [-A] [-s SORT]
+                   [-r] [-j] [-v] [filter]
 
 Reticulum Network Stack Status
 
 positional arguments:
-  filter           only display interfaces with names including filter
+  filter                only display interfaces with names including filter
 
 options:
-  -h, --help       show this help message and exit
-  --config CONFIG  path to alternative Reticulum config directory
-  --version        show program&#39;s version number and exit
-  -a, --all        show all interfaces
-  -j, --json       output in JSON format
+  -h, --help            show this help message and exit
+  --config CONFIG       path to alternative Reticulum config directory
+  --version             show program&#39;s version number and exit
+  -a, --all             show all interfaces
+  -A, --announce-stats  show announce stats
+  -s SORT, --sort SORT  sort interfaces by [rate, traffic, rx, tx, announces, arx, atx, held]
+  -r, --reverse         reverse sorting
+  -j, --json            output in JSON format
   -v, --verbose
 </pre></div>
 </div>
@@ -595,7 +610,7 @@ Path found, destination &lt;c89b4da064bf66d280f0e4d8abfd9806&gt; is 4 hops away
 </div>
 <p><strong>All Command-Line Options</strong></p>
 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnpath.py [-h] [--config CONFIG] [--version] [-t] [-r] [-d] [-D]
-                 [-w seconds] [-v] [destination]
+                 [-x] [-w seconds] [-v] [destination]
 
 Reticulum Path Discovery Utility
 
@@ -610,6 +625,7 @@ options:
   -r, --rates           show announce rate info
   -d, --drop            remove the path to a destination
   -D, --drop-announces  drop all queued announces
+  -x, --drop-via        drop all paths via specified transport instance
   -w seconds            timeout before giving up
   -v, --verbose
 </pre></div>
@@ -998,7 +1014,7 @@ WantedBy=multi-user.target
       
     </aside>
   </div>
-</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=c96a9f3e"></script>
+</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=2c9eb04b"></script>
     <script src="_static/doctools.js?v=888ff710"></script>
     <script src="_static/sphinx_highlight.js?v=4825356b"></script>
     <script src="_static/scripts/furo.js?v=2c7c1115"></script>

docs/manual/whatis.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Getting Started Fast" href="gettingstartedfast.html" /><link rel="prev" title="Reticulum Network Stack Manual" href="index.html" />
 
     <meta name="generator" content="sphinx-7.1.2, furo 2022.09.29.dev1"/>
-        <title>What is Reticulum? - Reticulum Network Stack 0.6.0 beta documentation</title>
+        <title>What is Reticulum? - Reticulum Network Stack 0.6.2 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=a746c00c" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.6.2 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.6.2 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -181,7 +181,7 @@
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
-<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Supported Interfaces</a></li>
+<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
@@ -434,7 +434,7 @@ want to help out with this, or can help sponsor an audit, please do get in touch
       
     </aside>
   </div>
-</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=c96a9f3e"></script>
+</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=2c9eb04b"></script>
     <script src="_static/doctools.js?v=888ff710"></script>
     <script src="_static/sphinx_highlight.js?v=4825356b"></script>
     <script src="_static/scripts/furo.js?v=2c7c1115"></script>

docs/source/interfaces.rst

@@ -1,9 +1,9 @@
 
 .. _interfaces-main:
 
-********************
-Supported Interfaces
-********************
+**********************
+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
@@ -761,3 +761,74 @@ conserve bandwidth, while very fast networks can support applications that
 need very 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.
+
+**It's important to note** 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 announce 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.
+

docs/source/using.rst

@@ -99,6 +99,17 @@ configuration file is created. The default configuration looks like this:
   instance_control_port = 37429
 
 
+  # On systems where running instances may not have access
+  # to the same shared Reticulum configuration directory,
+  # it is still possible to allow full interactivity for
+  # running instances, by manually specifying a shared RPC
+  # key. In almost all cases, this option is not needed, but
+  # it can be useful on operating systems such as Android.
+  # The key must be specified as bytes in hexadecimal.
+
+  # rpc_key = e5c032d3ec4e64a6aca9927ba8ab73336780f6d71790
+
+
   # You can configure Reticulum to panic and forcibly close
   # if an unrecoverable interface error occurs, such as the
   # hardware device for an interface disappearing. This is
@@ -301,19 +312,23 @@ Filter output to only show some interfaces:
 
 .. code:: text
 
-  usage: rnstatus.py [-h] [--config CONFIG] [--version] [-a] [-j] [-v] [filter]
+  usage: rnstatus.py [-h] [--config CONFIG] [--version] [-a] [-A] [-s SORT]
+                     [-r] [-j] [-v] [filter]
 
   Reticulum Network Stack Status
 
   positional arguments:
-    filter           only display interfaces with names including filter
+    filter                only display interfaces with names including filter
 
   options:
-    -h, --help       show this help message and exit
-    --config CONFIG  path to alternative Reticulum config directory
-    --version        show program's version number and exit
-    -a, --all        show all interfaces
-    -j, --json       output in JSON format
+    -h, --help            show this help message and exit
+    --config CONFIG       path to alternative Reticulum config directory
+    --version             show program's version number and exit
+    -a, --all             show all interfaces
+    -A, --announce-stats  show announce stats
+    -s SORT, --sort SORT  sort interfaces by [rate, traffic, rx, tx, announces, arx, atx, held]
+    -r, --reverse         reverse sorting
+    -j, --json            output in JSON format
     -v, --verbose
 
 
@@ -438,7 +453,7 @@ Resolve path to a destination:
 .. code:: text
 
   usage: rnpath.py [-h] [--config CONFIG] [--version] [-t] [-r] [-d] [-D]
-                   [-w seconds] [-v] [destination]
+                   [-x] [-w seconds] [-v] [destination]
 
   Reticulum Path Discovery Utility
 
@@ -453,6 +468,7 @@ Resolve path to a destination:
     -r, --rates           show announce rate info
     -d, --drop            remove the path to a destination
     -D, --drop-announces  drop all queued announces
+    -x, --drop-via        drop all paths via specified transport instance
     -w seconds            timeout before giving up
     -v, --verbose
 

setup.py

@@ -49,6 +49,7 @@ setuptools.setup(
             'rnid=RNS.Utilities.rnid:main',
             'rncp=RNS.Utilities.rncp:main',
             'rnx=RNS.Utilities.rnx:main',
+            'rnir=RNS.Utilities.rnir:main',
             'rnodeconf=RNS.Utilities.rnodeconf:main',
         ]
     },