Added ability to filter destination types by hash

This commit is contained in:
Mark Qvist 2026-11-15 00:10:54 +01:00
parent 29ce7ca568
commit e96c81c3f2
No known key found for this signature in database
12 changed files with 204 additions and 30 deletions

View file

@ -4756,7 +4756,14 @@ class Transport:
@staticmethod
def block_destination_type(full_name):
try:
name_hash = RNS.Destination.name_hash(full_name)
name_hash = None
if not full_name: return
if full_name.startswith("<") and full_name.endswith(">"):
full_name = full_name[1:1+RNS.Identity.NAME_HASH_LENGTH//8*2]
try: name_hash = bytes.fromhex(full_name)
except: name_hash = None
name_hash = name_hash or RNS.Destination.name_hash(full_name)
with Transport.destination_filters_lock:
Transport.blocked_destination_types[name_hash] = [True]
Transport.client_destination_types.pop(name_hash, None)
@ -4769,7 +4776,14 @@ class Transport:
@staticmethod
def allow_destination_type(full_name):
try:
name_hash = RNS.Destination.name_hash(full_name)
name_hash = None
if not full_name: return
if full_name.startswith("<") and full_name.endswith(">"):
full_name = full_name[1:1+RNS.Identity.NAME_HASH_LENGTH//8*2]
try: name_hash = bytes.fromhex(full_name)
except: name_hash = None
name_hash = name_hash or RNS.Destination.name_hash(full_name)
with Transport.destination_filters_lock:
Transport.allowed_destination_types[name_hash] = [True]
Transport.destination_type_map[name_hash] = full_name

View file

@ -1481,11 +1481,11 @@ but all the parameters are exposed for configuration if needed.
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``
frequency for newly spawned interfaces. Defaults to ``3.0``
announces per second.
* | The ``ic_burst_freq`` option sets the maximum announce ingress
frequency for other interfaces. Defaults to ``12`` announces
frequency for other interfaces. Defaults to ``10.0`` announces
per second.
*If an interface exceeds its burst frequency, incoming announces
@ -1494,21 +1494,21 @@ but all the parameters are exposed for configuration if needed.
* | 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.
unique announces will be dropped. Defaults to ``64`` 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``
announce burst to be considered cleared. Defaults to ``15``
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``
start being released from the queue. Defaults to ``15``
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.
to ``5`` seconds.
All of the above settings can be configured both as instance-wide defaults
under the ``[reticulum]`` section of the configuration file, or on a per-

View file

@ -254,13 +254,18 @@ The filtering subsystem can operate in two modes:
| In addition, any application using the shared instance can temporarily request required destination types for its use. Applications that request required destination types will automatically have them granted, unless they are included in the ``ignored_types`` list.
The filtering defaults and base settings are configured in the ``[filter]`` section of the configuration file. For example, it is possible to explicitly ignore a series of destination types, while also limiting hop reach to a more local topology:
The filtering defaults and base settings are configured in the ``[filter]`` section of the configuration file. For example, it is possible to explicitly ignore a series of destination types, while also limiting hop reach to a more local topology.
.. tip::
The ``hop_limiter`` in the filter section is an instance-wide setting. You can also use the ``hop_limiter`` option *per-interface* if you want to limit hops on some interfaces only.
If you do not know the human readable destination type aspects for a destination type you want to ignore, you can also add entries as 10-byte (20 hexadecimal character) hashes using the ``<c4ace368262d845c9dd3>`` format.
.. code:: ini
[filter]
hop_limiter = 14
ignored_types = application.that.spams, traffic.heavy.service
ignored_types = application.that.spams, traffic.heavy.service, <c4ace368262d845c9dd3>
In some situations, you may want to allow *only* certain destination types. If, for example, you are creating a high-performance transport node intended to handle thousands of simultaneous voice calls at minimal latency, a configuration might look something like:
@ -279,6 +284,42 @@ The filtering subsystem provided in RNS ``1.6.0`` is functional and useful, but
If you are a developer, see the following section.
Blocking Transport Nodes
------------------------
Misbehaving, spamming and broken transport nodes can be completely blocked using the :ref:`Blackhole system<protecting-blackhole>`. First, obtain the Transport Identity hash of a misbehaving transport node, using ``rnstatus``:
.. code:: txt
$ rnstatus -FATa "71.29.190.5"
BackboneInterface[Client on Bern IPv4/71.29.190.5:37062]
Status : Up
Mode : Gateway
Rate : 250.00 Mbps, MTU 65536
Running : Unknown implementation
Rem.Tr.ID : <a0c289d131c7bfa8d5ddc8b652c0f40d>
Held : 64 announces
Violatns. : 382 protocol
Flt. Hits : 92
Announces : 147174↓ 11193↑ total, 140554 filtered
1.2 Hz↑ (↓0% / ↑0% of flow)
7.8 Hz↓ (t:6h/p:0s/g:1) burst for 4h, 54m and 42.69s
Traffic : ↑4.75 MB 0 bps
↓1.50 MB 0 bps
Filtered : ↑0 B 0 bps
↓55.43 MB 380.14 Kbps
You can then block it by its Transport ID:
.. code:: txt
$ rnpath -B a0c289d131c7bfa8d5ddc8b652c0f40d --reason "Broken node"
Blackholed identity a0c289d131c7bfa8d5ddc8b652c0f40d
Its connection will be immediately torn down, and further reconnection attempts will be ignored.
For Developers
--------------
@ -332,6 +373,7 @@ Rate limiting bounds the *rate* at which abuse can occur, for everyone, while st
Full configuration details are available in the :ref:`Announce Rate Control<interfaces-announcerates>` and :ref:`New Destination Rate Limiting<interfaces-ingress-control>` sections.
.. _protecting-blachole:
Blackhole Management
====================

View file

@ -462,6 +462,7 @@ to participate in the development of Reticulum itself.</p>
</li>
<li class="toctree-l2"><a class="reference internal" href="protecting.html#filtering-qos">Filtering &amp; QoS</a><ul>
<li class="toctree-l3"><a class="reference internal" href="protecting.html#id1">Instance Configuration</a></li>
<li class="toctree-l3"><a class="reference internal" href="protecting.html#blocking-transport-nodes">Blocking Transport Nodes</a></li>
<li class="toctree-l3"><a class="reference internal" href="protecting.html#id2">For Developers</a></li>
</ul>
</li>

View file

@ -1651,13 +1651,13 @@ sub-interfaces when a new client connects.</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>
frequency for newly spawned interfaces. Defaults to <code class="docutils literal notranslate"><span class="pre">3.0</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
frequency for other interfaces. Defaults to <code class="docutils literal notranslate"><span class="pre">10.0</span></code> announces
per second.</div>
</div>
<blockquote>
@ -1669,27 +1669,27 @@ not processed until later.</em></p>
<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>
unique announces will be dropped. Defaults to <code class="docutils literal notranslate"><span class="pre">64</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>
announce burst to be considered cleared. Defaults to <code class="docutils literal notranslate"><span class="pre">15</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>
start being released from the queue. Defaults to <code class="docutils literal notranslate"><span class="pre">15</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>
to <code class="docutils literal notranslate"><span class="pre">5</span></code> seconds.</div>
</div>
</li>
</ul>

Binary file not shown.

View file

@ -513,10 +513,15 @@ option. It will become mandatory and enabled by default in RNS
</li>
</ul>
</div></blockquote>
<p>The filtering defaults and base settings are configured in the <code class="docutils literal notranslate"><span class="pre">[filter]</span></code> section of the configuration file. For example, it is possible to explicitly ignore a series of destination types, while also limiting hop reach to a more local topology:</p>
<p>The filtering defaults and base settings are configured in the <code class="docutils literal notranslate"><span class="pre">[filter]</span></code> section of the configuration file. For example, it is possible to explicitly ignore a series of destination types, while also limiting hop reach to a more local topology.</p>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
<p>The <code class="docutils literal notranslate"><span class="pre">hop_limiter</span></code> in the filter section is an instance-wide setting. You can also use the <code class="docutils literal notranslate"><span class="pre">hop_limiter</span></code> option <em>per-interface</em> if you want to limit hops on some interfaces only.</p>
</div>
<p>If you do not know the human readable destination type aspects for a destination type you want to ignore, you can also add entries as 10-byte (20 hexadecimal character) hashes using the <code class="docutils literal notranslate"><span class="pre">&lt;c4ace368262d845c9dd3&gt;</span></code> format.</p>
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[filter]</span>
<span class="w"> </span><span class="na">hop_limiter</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">14</span>
<span class="w"> </span><span class="na">ignored_types</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">application.that.spams, traffic.heavy.service</span>
<span class="w"> </span><span class="na">ignored_types</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">application.that.spams, traffic.heavy.service, &lt;c4ace368262d845c9dd3&gt;</span>
</pre></div>
</div>
<p>In some situations, you may want to allow <em>only</em> certain destination types. If, for example, you are creating a high-performance transport node intended to handle thousands of simultaneous voice calls at minimal latency, a configuration might look something like:</p>
@ -533,6 +538,37 @@ option. It will become mandatory and enabled by default in RNS
<p>If you are a developer, see the following section.</p>
</div>
</section>
<section id="blocking-transport-nodes">
<h3>Blocking Transport Nodes<a class="headerlink" href="#blocking-transport-nodes" title="Link to this heading"></a></h3>
<p>Misbehaving, spamming and broken transport nodes can be completely blocked using the <span class="xref std std-ref">Blackhole system</span>. First, obtain the Transport Identity hash of a misbehaving transport node, using <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code>:</p>
<div class="highlight-txt notranslate"><div class="highlight"><pre><span></span>$ rnstatus -FATa &quot;71.29.190.5&quot;
BackboneInterface[Client on Bern IPv4/71.29.190.5:37062]
Status : Up
Mode : Gateway
Rate : 250.00 Mbps, MTU 65536
Running : Unknown implementation
Rem.Tr.ID : &lt;a0c289d131c7bfa8d5ddc8b652c0f40d&gt;
Held : 64 announces
Violatns. : 382 protocol
Flt. Hits : 92
Announces : 147174↓ 11193↑ total, 140554 filtered
1.2 Hz↑ (↓0% / ↑0% of flow)
7.8 Hz↓ (t:6h/p:0s/g:1) burst for 4h, 54m and 42.69s
Traffic : ↑4.75 MB 0 bps
↓1.50 MB 0 bps
Filtered : ↑0 B 0 bps
↓55.43 MB 380.14 Kbps
</pre></div>
</div>
<p>You can then block it by its Transport ID:</p>
<div class="highlight-txt notranslate"><div class="highlight"><pre><span></span>$ rnpath -B a0c289d131c7bfa8d5ddc8b652c0f40d --reason &quot;Broken node&quot;
Blackholed identity a0c289d131c7bfa8d5ddc8b652c0f40d
</pre></div>
</div>
<p>Its connection will be immediately torn down, and further reconnection attempts will be ignored.</p>
</section>
<section id="id2">
<h3>For Developers<a class="headerlink" href="#id2" title="Link to this heading"></a></h3>
<p>At some point during the <code class="docutils literal notranslate"><span class="pre">1.6.x</span></code> release cycle, RNS will move to using the <code class="docutils literal notranslate"><span class="pre">required_only</span></code> mode for <em>non-transport</em> instances by default. This means that applications will, in most cases, have to request what types of destinations they are interested in receiving announces from.</p>
@ -571,7 +607,7 @@ option. It will become mandatory and enabled by default in RNS
<p>Full configuration details are available in the <a class="reference internal" href="interfaces.html#interfaces-announcerates"><span class="std std-ref">Announce Rate Control</span></a> and <a class="reference internal" href="interfaces.html#interfaces-ingress-control"><span class="std std-ref">New Destination Rate Limiting</span></a> sections.</p>
</section>
<section id="blackhole-management">
<h2>Blackhole Management<a class="headerlink" href="#blackhole-management" title="Link to this heading"></a></h2>
<span id="protecting-blachole"></span><h2>Blackhole Management<a class="headerlink" href="#blackhole-management" title="Link to this heading"></a></h2>
<p>The <em>blackhole</em> system allows any node operator or individual user to block specific identities at the transport layer.</p>
<p>Once an identity has been blackholed on a node, announces originating from <em>any</em> destination associated with that identity are dropped, and the node will refuse to transport traffic, or establish and maintain links, to the blackholed identity’s destinations.</p>
<p>It is important to understand the scope of this mechanism corrrectly. There is fundamentally <strong>no way</strong> to <em>globally</em> block or censor any identity or destination in Reticulum networks. A blackhole entry only applies on the network segments that enforce it, which is the exact intention. Operators retain full control over what is allowed on their own segments, while no one can impose restrictions on segments they do not operate.</p>
@ -656,6 +692,7 @@ option. It will become mandatory and enabled by default in RNS
</li>
<li><a class="reference internal" href="#filtering-qos">Filtering &amp; QoS</a><ul>
<li><a class="reference internal" href="#id1">Instance Configuration</a></li>
<li><a class="reference internal" href="#blocking-transport-nodes">Blocking Transport Nodes</a></li>
<li><a class="reference internal" href="#id2">For Developers</a></li>
</ul>
</li>

File diff suppressed because one or more lines are too long

View file

@ -137,6 +137,7 @@ to participate in the development of Reticulum itself.
* [Configuring Stamps](protecting.md#configuring-stamps)
* [Filtering & QoS](protecting.md#filtering-qos)
* [Instance Configuration](protecting.md#id1)
* [Blocking Transport Nodes](protecting.md#blocking-transport-nodes)
* [For Developers](protecting.md#id2)
* [Ingress & Burst Control](protecting.md#ingress-burst-control)
* [Blackhole Management](protecting.md#blackhole-management)

View file

@ -1398,11 +1398,11 @@ but all the parameters are exposed for configuration if needed.
> 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`
> frequency for newly spawned interfaces. Defaults to `3.0`
> announces per second.
>
> * The `ic_burst_freq` option sets the maximum announce ingress
> frequency for other interfaces. Defaults to `12` announces
> frequency for other interfaces. Defaults to `10.0` announces
> per second.
>
> > *If an interface exceeds its burst frequency, incoming announces
@ -1410,21 +1410,21 @@ but all the parameters are exposed for configuration if needed.
> > 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.
> unique announces will be dropped. Defaults to `64` 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`
> announce burst to be considered cleared. Defaults to `15`
> 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`
> start being released from the queue. Defaults to `15`
> 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.
> to `5` seconds.
>
All of the above settings can be configured both as instance-wide defaults

View file

@ -232,12 +232,14 @@ The filtering subsystem can operate in two modes:
> In addition, any application using the shared instance can temporarily request required destination types for its use. Applications that request required destination types will automatically have them granted, unless they are included in the `ignored_types` list.
>
The filtering defaults and base settings are configured in the `[filter]` section of the configuration file. For example, it is possible to explicitly ignore a series of destination types, while also limiting hop reach to a more local topology:
The filtering defaults and base settings are configured in the `[filter]` section of the configuration file. For example, it is possible to explicitly ignore a series of destination types, while also limiting hop reach to a more local topology.
If you do not know the human readable destination type aspects for a destination type you want to ignore, you can also add entries as 10-byte (20 hexadecimal character) hashes using the `<c4ace368262d845c9dd3>` format.
```ini
[filter]
hop_limiter = 14
ignored_types = application.that.spams, traffic.heavy.service
ignored_types = application.that.spams, traffic.heavy.service, <c4ace368262d845c9dd3>
```
In some situations, you may want to allow *only* certain destination types. If, for example, you are creating a high-performance transport node intended to handle thousands of simultaneous voice calls at minimal latency, a configuration might look something like:
@ -257,6 +259,41 @@ This ensures that a local, non-transport node (running on resource-limited hardw
If you are a developer, see the following section.
### Blocking Transport Nodes
Misbehaving, spamming and broken transport nodes can be completely blocked using the Blackhole system. First, obtain the Transport Identity hash of a misbehaving transport node, using `rnstatus`:
```txt
$ rnstatus -FATa "71.29.190.5"
BackboneInterface[Client on Bern IPv4/71.29.190.5:37062]
Status : Up
Mode : Gateway
Rate : 250.00 Mbps, MTU 65536
Running : Unknown implementation
Rem.Tr.ID : <a0c289d131c7bfa8d5ddc8b652c0f40d>
Held : 64 announces
Violatns. : 382 protocol
Flt. Hits : 92
Announces : 147174↓ 11193↑ total, 140554 filtered
1.2 Hz↑ (↓0% / ↑0% of flow)
7.8 Hz↓ (t:6h/p:0s/g:1) burst for 4h, 54m and 42.69s
Traffic : ↑4.75 MB 0 bps
↓1.50 MB 0 bps
Filtered : ↑0 B 0 bps
↓55.43 MB 380.14 Kbps
```
You can then block it by its Transport ID:
```txt
$ rnpath -B a0c289d131c7bfa8d5ddc8b652c0f40d --reason "Broken node"
Blackholed identity a0c289d131c7bfa8d5ddc8b652c0f40d
```
Its connection will be immediately torn down, and further reconnection attempts will be ignored.
### For Developers
At some point during the `1.6.x` release cycle, RNS will move to using the `required_only` mode for *non-transport* instances by default. This means that applications will, in most cases, have to request what types of destinations they are interested in receiving announces from.

View file

@ -254,13 +254,18 @@ The filtering subsystem can operate in two modes:
| In addition, any application using the shared instance can temporarily request required destination types for its use. Applications that request required destination types will automatically have them granted, unless they are included in the ``ignored_types`` list.
The filtering defaults and base settings are configured in the ``[filter]`` section of the configuration file. For example, it is possible to explicitly ignore a series of destination types, while also limiting hop reach to a more local topology:
The filtering defaults and base settings are configured in the ``[filter]`` section of the configuration file. For example, it is possible to explicitly ignore a series of destination types, while also limiting hop reach to a more local topology.
.. tip::
The ``hop_limiter`` in the filter section is an instance-wide setting. You can also use the ``hop_limiter`` option *per-interface* if you want to limit hops on some interfaces only.
If you do not know the human readable destination type aspects for a destination type you want to ignore, you can also add entries as 10-byte (20 hexadecimal character) hashes using the ``<c4ace368262d845c9dd3>`` format.
.. code:: ini
[filter]
hop_limiter = 14
ignored_types = application.that.spams, traffic.heavy.service
ignored_types = application.that.spams, traffic.heavy.service, <c4ace368262d845c9dd3>
In some situations, you may want to allow *only* certain destination types. If, for example, you are creating a high-performance transport node intended to handle thousands of simultaneous voice calls at minimal latency, a configuration might look something like:
@ -279,6 +284,42 @@ The filtering subsystem provided in RNS ``1.6.0`` is functional and useful, but
If you are a developer, see the following section.
Blocking Transport Nodes
------------------------
Misbehaving, spamming and broken transport nodes can be completely blocked using the :ref:`Blackhole system<protecting-blackhole>`. First, obtain the Transport Identity hash of a misbehaving transport node, using ``rnstatus``:
.. code:: txt
$ rnstatus -FATa "71.29.190.5"
BackboneInterface[Client on Bern IPv4/71.29.190.5:37062]
Status : Up
Mode : Gateway
Rate : 250.00 Mbps, MTU 65536
Running : Unknown implementation
Rem.Tr.ID : <a0c289d131c7bfa8d5ddc8b652c0f40d>
Held : 64 announces
Violatns. : 382 protocol
Flt. Hits : 92
Announces : 147174↓ 11193↑ total, 140554 filtered
1.2 Hz↑ (↓0% / ↑0% of flow)
7.8 Hz↓ (t:6h/p:0s/g:1) burst for 4h, 54m and 42.69s
Traffic : ↑4.75 MB 0 bps
↓1.50 MB 0 bps
Filtered : ↑0 B 0 bps
↓55.43 MB 380.14 Kbps
You can then block it by its Transport ID:
.. code:: txt
$ rnpath -B a0c289d131c7bfa8d5ddc8b652c0f40d --reason "Broken node"
Blackholed identity a0c289d131c7bfa8d5ddc8b652c0f40d
Its connection will be immediately torn down, and further reconnection attempts will be ignored.
For Developers
--------------
@ -332,6 +373,7 @@ Rate limiting bounds the *rate* at which abuse can occur, for everyone, while st
Full configuration details are available in the :ref:`Announce Rate Control<interfaces-announcerates>` and :ref:`New Destination Rate Limiting<interfaces-ingress-control>` sections.
.. _protecting-blachole:
Blackhole Management
====================