feat(docker): eBPF stateful packet filters on kernel links

Consume the eBPF impairment classifier delivered in uBridge
feature/tc-precision: frequency_drop becomes the exact every-Nth mode
(tc nth_drop; -1 = drop everything maps to every 1st) and the new
kernel-only quota type is the byte-cap mode (tc quota_drop, 100 = hard
cutoff). KERNEL_UNSUPPORTED_FILTERS is gone entirely — kernel/relay
eligibility is now purely topological. Both modes gate on ebpf=1 from
the per-process tc capabilities probe (error names the setcap fix); the
cleanup path (modes off) only talks to the eBPF commands when the probe
reported them. Reconcile is a plain re-set: the netem reset-before-set
already detaches the program and clears uBridge's per-interface
registry, so a mode set after it is a fresh load+attach.

Documented semantic difference: the relay counts both directions
through one bridge counter, the kernel counts per direction — N=3
round-trip loss is 1-(2/3)^2 = 55.6% on kernel vs ~1/N on relay
(measured 57%). window_drop is NOT exposed: the delivered
implementation advances the window with no gap, making 'outside the
window packets pass' unreachable (needs outage/period fields —
recorded in the spec); flow_drop awaits a parameter-shape decision.

Also fixes a pre-existing restart bug the e2e exposed: _bridges (relay
bridge names) was never cleared on stop, so restarting a node with a
relay link skipped 'bridge create' and failed on add_nio_udp.

e2e (isolated instance): 13/13 — pref-1 tc_impair classifier on both
veths, 57% round-trip for N=3, -1 = exact 100%, quota hard cutoff,
delay coexistence, clean teardown, suspend/resume, node restart,
relay-leg frequency_drop regression through an Ethernet switch. Full
suite: 1925 passed.

gns3server/compute/base_manager.py

@@ -375,17 +375,6 @@ class BaseManager:
             nio.suspend = nio_settings.get("suspend", False)
         elif nio_settings["type"] == "nio_bridge":
             nio = NIOBridge(nio_settings["bridge"])
-            # Impairment filters with a tc netem equivalent run on the veth
-            # host end; the relay-only types are rejected here (the controller
-            # already keeps them off kernel links — this is the second guard).
-            from gns3server.utils.packet_filter_validation import KERNEL_UNSUPPORTED_FILTERS
-
-            unsupported = KERNEL_UNSUPPORTED_FILTERS.intersection(nio_settings.get("filters") or {})
-            if unsupported:
-                raise ComputeError(
-                    "Packet filter(s) {} cannot run on a kernel-datapath link "
-                    "(no uBridge relay in the forwarding path)".format(", ".join(sorted(unsupported)))
-                )
             nio.filters = nio_settings.get("filters", {})
             # Markers ride the NIO and attach to the veth host interface via
             # uBridge's AF_PACKET marker module (marker add_kernel).

gns3server/compute/docker/docker_vm.py

@@ -1438,6 +1438,11 @@ class DockerVM(BaseNode):
             # The next start spawns a fresh uBridge process — its capabilities
             # must be re-probed (see _ubridge_tc_capabilities).
             self._ubridge_tc_caps = None
+            # The uBridge process dies with every bridge it hosted — drop the
+            # relay bridge names too, or the next start would skip
+            # "bridge create" for them (the gate checks the name's presence)
+            # and fail on "bridge add_nio_udp: bridge doesn't exist".
+            self._bridges.clear()
             # veth host ends live in the root namespace and survive container
             # death — remove them while the uBridge control channel is still up.
             await self._remove_kernel_veths()
@@ -1944,9 +1949,11 @@ class DockerVM(BaseNode):
             await self._ubridge_apply_markers(host_ifc, nio)
             # Impairment filters become one tc netem qdisc on the veth host
             # end (restored here on node restart, like the capture above);
-            # bpf expressions become cls_bpf match-drop classifiers.
+            # bpf expressions become cls_bpf match-drop classifiers and
+            # frequency_drop/quota become the eBPF stateful classifier.
             await self._ubridge_apply_netem(host_ifc, nio.filters)
             await self._ubridge_apply_bpf_drops(host_ifc, nio.filters)
+            await self._ubridge_apply_ebpf_drops(host_ifc, nio.filters)
             return
 
         # Relay NIO. On a veth-backed adapter (the unified Docker interface)
@@ -2015,28 +2022,19 @@ class DockerVM(BaseNode):
 
         if self.ubridge:
             if isinstance(nio, NIOBridge):
-                # The controller keeps frequency_drop off kernel links (no
-                # kernel equivalent until the eBPF classifier lands) and
-                # create_nio rejects it on the POST path; this PUT path
-                # mutates the NIO in place, so guard here too. bpf is fine —
-                # it becomes cls_bpf match-drop classifiers (cbpf-probed).
-                unsupported = KERNEL_UNSUPPORTED_FILTERS.intersection(nio.filters or {})
-                if unsupported:
-                    raise DockerError(
-                        "Packet filter(s) {} cannot run on a kernel-datapath link "
-                        "(no uBridge relay in the forwarding path)".format(", ".join(sorted(unsupported)))
-                    )
                 if self.status == "started":
                     host_ifc = self._kernel_veths.get((adapter_number, port_number))
                     if host_ifc is not None:
                         # Incremental marker reconcile on the veth anchor —
                         # the relay-datapath equivalent of the branch below.
                         await self._ubridge_apply_markers(host_ifc, nio)
-                        # netem set is an atomic replace, so a full re-apply
-                        # IS the incremental reconcile for impairment filters;
-                        # bpf drops reconcile as flush + re-add.
+                        # The netem apply resets the interface first (the
+                        # kernel merges optional netem attrs on replace), so
+                        # everything anchored on clsact must re-apply after
+                        # it: bpf drops flush + re-add, eBPF modes re-set.
                         await self._ubridge_apply_netem(host_ifc, nio.filters)
                         await self._ubridge_apply_bpf_drops(host_ifc, nio.filters)
+                        await self._ubridge_apply_ebpf_drops(host_ifc, nio.filters)
                     await self._set_adapter_carrier(adapter_number, not nio.suspend, port_number)
                 return
 
@@ -2376,6 +2374,70 @@ class DockerVM(BaseNode):
                 log.warning(message)
                 self.project.emit("log.warning", {"message": message})
 
+    async def _ubridge_apply_ebpf_drops(self, host_ifc, filters):
+        """
+        Translate the NIO's stateful filters into uBridge's eBPF impairment
+        classifier on the veth host end's clsact egress (prio 1, below
+        bpf_drop's 10-99): ``frequency_drop`` becomes the exact every-Nth
+        mode (``tc nth_drop``; -1 = drop everything maps to every 1st), and
+        the kernel-only ``quota`` type the byte-cap mode (``tc quota_drop``).
+
+        Reconcile is a plain re-set on every apply: the preceding netem
+        apply resets the interface (which detaches the program and drops
+        uBridge's per-interface registry entry), so a mode set re-loads the
+        program from scratch, and a mode left absent is turned off
+        explicitly (idempotent) so a removed filter stops dropping.
+
+        Semantic difference vs the relay, documented server-side: the relay
+        counts packets of BOTH directions through its single filtered
+        bridge, while each veth end's classifier counts only the traffic
+        entering that container — with both endpoints applying theirs, each
+        direction drops every Nth independently.
+
+        :param host_ifc: veth host-end interface name
+        :param filters: NIO filters dictionary
+        """
+
+        def values_of(key):
+            values = filters.get(key)
+            if isinstance(values, (list, tuple)):
+                return list(values)
+            return [values] if values else []
+
+        frequency = values_of("frequency_drop")
+        quota = values_of("quota")
+        if not frequency and not quota and self._ubridge_tc_caps is None:
+            # Nothing to set and nothing was ever installed (no probe yet) —
+            # skip touching an old uBridge entirely.
+            return
+        caps = await self._ubridge_tc_capabilities()
+        if not frequency and not quota:
+            if caps.get("ebpf") == "1":
+                # Only when the eBPF module answers can anything be
+                # installed; "off" is idempotent in uBridge.
+                await self._ubridge_send(f'tc nth_drop "{host_ifc}" off')
+                await self._ubridge_send(f'tc quota_drop "{host_ifc}" off')
+            return
+        if caps.get("ebpf") != "1":
+            raise DockerError(
+                "Packet filter(s) {} on a kernel-datapath link need a uBridge with eBPF support "
+                "(tc capabilities reports no ebpf; setcap cap_bpf,cap_net_admin,cap_net_raw=ep on "
+                "the uBridge binary); upgrade uBridge on this compute or keep the link on the "
+                "relay datapath".format(", ".join(sorted(f for f in ("frequency_drop", "quota") if f in filters)))
+            )
+        if frequency:
+            # relay semantics: -1 = drop everything, N = every Nth packet
+            nth = 1 if int(frequency[0]) == -1 else int(frequency[0])
+            await self._ubridge_send(f'tc nth_drop "{host_ifc}" {nth}')
+        else:
+            await self._ubridge_send(f'tc nth_drop "{host_ifc}" off')
+        if quota:
+            await self._ubridge_send(
+                'tc quota_drop "{ifc}" {bytes} {pct}'.format(ifc=host_ifc, bytes=int(quota[0]), pct=int(quota[1]))
+            )
+        else:
+            await self._ubridge_send(f'tc quota_drop "{host_ifc}" off')
+
     async def _remove_kernel_markers(self, host_ifc):
         """
         Tear down every kernel marker anchored to *host_ifc*: the veth survives

gns3server/controller/link.py

@@ -46,7 +46,8 @@ FILTERS = [
     {
         "type": "frequency_drop",
         "name": "Frequency drop",
-        "description": "It will drop everything with a -1 frequency, drop every Nth packet with a positive frequency, or drop nothing",
+        "description": "It will drop everything with a -1 frequency, drop every Nth packet with a positive "
+        "frequency, or drop nothing. On kernel-datapath links this is exact (eBPF every-Nth counter)",
         "parameters": [{"name": "Frequency", "minimum": -1, "maximum": 32767, "type": "int", "unit": "th packet"}],
     },
     {
@@ -136,6 +137,16 @@ FILTERS = [
         "combining a low rate with a long delay (kernel-datapath links only)",
         "parameters": [{"name": "Limit", "minimum": 1, "maximum": 1000000, "type": "int", "unit": "packets"}],
     },
+    {
+        "type": "quota",
+        "name": "Byte quota",
+        "description": "After the byte quota is consumed, each further packet drops with the given chance "
+        "(100 = hard cutoff) — a data cap, like a mobile plan (kernel-datapath links only)",
+        "parameters": [
+            {"name": "Quota", "minimum": 1, "maximum": 1000000000000000, "type": "int", "unit": "bytes"},
+            {"name": "Chance", "minimum": 0, "maximum": 100, "type": "int", "unit": "%"},
+        ],
+    },
 ]
 
 
@@ -296,24 +307,12 @@ class Link:
         except FilterValidationError as e:
             raise ControllerError(f"Invalid packet filter parameters: {e!s}")
 
-        if self.kernel_datapath:
-            from gns3server.utils.packet_filter_validation import KERNEL_UNSUPPORTED_FILTERS
-
-            unsupported = KERNEL_UNSUPPORTED_FILTERS.intersection(new_filters or {})
-            if unsupported:
-                raise ControllerError(
-                    "Packet filter(s) {} cannot run on a kernel-datapath link (no uBridge relay "
-                    "in the forwarding path; delay, packet loss and corrupt are served by tc "
-                    "netem on the veth); delete and recreate the link to use them".format(
-                        ", ".join(sorted(unsupported))
-                    )
-                )
-        elif self._created:
-            # The reverse guard: netem-extension filters have no relay
-            # equivalent. Only enforced on created links — while loading a
-            # project the datapath is not decided yet (a link that will be
-            # wired on the kernel datapath must accept them), and the relay
-            # prepare path drops what it cannot run with a warning.
+        if self._created and not self.kernel_datapath:
+            # Kernel-only filters (the netem extensions, the eBPF quota mode)
+            # have no relay equivalent. Only enforced on created links — while
+            # loading a project the datapath is not decided yet (a link that
+            # will be wired on the kernel datapath must accept them), and the
+            # relay prepare path drops what it cannot run with a warning.
             conflicts = kernel_only_features(new_filters)
             if conflicts:
                 raise ControllerError(
@@ -722,13 +721,11 @@ class Link:
         filter_node = self._get_filter_node()
         if filter_node:
             if self.kernel_datapath:
-                # Kernel-datapath links serve filters via tc netem on the
-                # veth host end; types without a netem equivalent (which
-                # only run in the uBridge relay) are hidden from the picker.
-                from gns3server.utils.packet_filter_validation import KERNEL_UNSUPPORTED_FILTERS
-
-                return [f for f in FILTERS if f["type"] not in KERNEL_UNSUPPORTED_FILTERS]
-            # Relay links: hide the netem-extension types the relay cannot run
+                # Kernel-datapath links serve every filter type: netem for
+                # delay/loss/corrupt and the netem extensions, cls_bpf for
+                # bpf, the eBPF classifier for frequency_drop and quota.
+                return FILTERS
+            # Relay links: hide the kernel-only types the relay cannot run
             # (they would be rejected with 409 on update).
             from gns3server.utils.packet_filter_validation import KERNEL_ONLY_FILTERS
 

gns3server/controller/udp_link.py

@@ -165,11 +165,10 @@ class UDPLink(Link):
         """
         Whether this link can be wired on the kernel datapath (veth pairs
         enslaved into a per-link Linux bridge) instead of the uBridge UDP
-        relay. Impairment filters with a tc netem equivalent (delay,
-        packet_loss, corrupt, bpf via cls_bpf, and the netem extensions
-        rate/reorder/gemodel/duplicate/seed/limit) are served on the veth
-        host end; frequency_drop only exists in the uBridge relay and
-        disqualifies the kernel path. Capture and markers are served by
+        relay. Every GNS3 filter type has a kernel equivalent — netem for
+        delay/packet_loss/corrupt and the netem extensions, cls_bpf for bpf,
+        the eBPF stateful classifier for frequency_drop — so filters no
+        longer disqualify the kernel path. Capture and markers are served by
         uBridge's AF_PACKET modules on the veth host end.
 
         Docker adapters are born as veth pairs (unified interface), so the
@@ -185,12 +184,6 @@ class UDPLink(Link):
             return False
         if node1.compute.id != node2.compute.id:
             return False
-        # Look at the *stored* filters, not get_active_filters(): a suspended
-        # link reports the synthetic frequency_drop emulation, which is
-        # relay-only mechanics and must not flip a kernel link to the relay
-        # on reopen/reset.
-        if KERNEL_UNSUPPORTED_FILTERS.intersection(self._filters or {}):
-            return False
         if _is_unix_socket_docker(node1) or _is_unix_socket_docker(node2):
             return False
         return True
@@ -229,10 +222,10 @@ class UDPLink(Link):
             # Markers ride the NIO like on the relay datapath, routed by
             # capture node; they attach to the veth host end via uBridge's
             # AF_PACKET marker module instead of a relay `mark` filter.
-            # Filters (delay/packet_loss/corrupt plus the netem extensions
-            # rate/reorder/gemodel/duplicate/seed/limit — eligibility
-            # guarantees frequency_drop is absent) become one tc netem qdisc
-            # per veth host end, pushed to both endpoints.
+            # Filters become one tc netem qdisc per veth host end (the netem
+            # surface and its extensions), plus cls_bpf match-drop (bpf) and
+            # the eBPF stateful classifier (frequency_drop, quota) — every
+            # GNS3 filter type has a kernel equivalent now.
             bridge_name = "gns3" + self._id.replace("-", "")[:11]
             node1_filters, node2_filters = self._get_node_filters(node1, node2, kernel=True)
             node1_markers, node2_markers = self._get_node_markers(node1, node2)

gns3server/schemas/compute/nios.py

@@ -38,7 +38,7 @@ class UDPNIO(BaseModel):
     filters: Optional[dict] = Field(
         None,
         description="Packet filters (relay-supported types only: delay/packet_loss/corrupt/frequency_drop/bpf — "
-        "the netem extensions need a kernel-datapath NIO)",
+        "the netem extensions and the quota mode need a kernel-datapath NIO)",
     )
     markers: Optional[dict] = Field(None, description="Traffic-insight markers")
 
@@ -81,9 +81,9 @@ class BridgeNIO(BaseModel):
     delay/packet_loss/corrupt and the netem extensions (rate, reorder,
     gemodel, duplicate, seed, limit, jitter distributions, loss correlation)
     as one tc netem qdisc, bpf as cls_bpf match-drop classifiers (needs a
-    uBridge reporting cbpf). frequency_drop still has no kernel equivalent
-    and is rejected. Markers and packet capture are served by uBridge's
-    AF_PACKET modules on the veth host end.
+    uBridge reporting cbpf), frequency_drop and quota as the eBPF stateful
+    classifier (needs ebpf). Markers and packet capture are served by
+    uBridge's AF_PACKET modules on the veth host end.
     """
 
     type: BridgeNIOType
@@ -91,8 +91,8 @@ class BridgeNIO(BaseModel):
     suspend: Optional[bool] = Field(None, description="Suspend the NIO")
     filters: Optional[dict] = Field(
         None,
-        description="Packet filters served on the veth host end (delay/packet_loss/corrupt and the netem extensions "
-        "via one tc netem qdisc, bpf via cls_bpf)",
+        description="Packet filters served on the veth host end (netem surface + extensions via one tc netem qdisc, "
+        "bpf via cls_bpf, frequency_drop/quota via the eBPF classifier)",
     )
     markers: Optional[dict] = Field(None, description="Traffic-insight markers (attached to the veth host end)")
 

gns3server/utils/packet_filter_validation.py

@@ -16,18 +16,18 @@ class FilterValidationError(Exception):
     pass
 
 
-# Packet filters with no kernel-datapath equivalent yet: frequency_drop needs
-# the eBPF stateful classifier (frozen in
-# docs/design/ubridge-kernel-impairment-spec.md, part B — not delivered),
-# so it still only runs in the uBridge userspace relay. bpf is served by the
-# cBPF match-drop classifier (tc bpf_drop) when uBridge reports cbpf=1.
-KERNEL_UNSUPPORTED_FILTERS = frozenset({"frequency_drop"})
-
-# Packet filters with no uBridge *relay* equivalent: the tc netem extensions
-# (uBridge feature/tc-netem-ext) serve them on the kernel datapath only. The
-# relay's packet-filter registry only knows frequency_drop / packet_loss /
-# delay / corrupt / bpf / mark.
-KERNEL_ONLY_FILTERS = frozenset({"rate", "reorder", "gemodel", "duplicate", "seed", "limit"})
+# Every GNS3 filter type now has a kernel-datapath equivalent: delay /
+# packet_loss / corrupt / the netem extensions run as one tc netem qdisc,
+# bpf as cBPF match-drop classifiers, and frequency_drop as the eBPF
+# stateful classifier's exact every-Nth mode (tc nth_drop — needs a uBridge
+# reporting ebpf=1). No type is relay-only anymore; the controller-side
+# kernel/relay choice is purely topological (same compute, docker/docker).
+#
+# Packet filters with no uBridge *relay* equivalent: the netem extensions
+# plus the eBPF quota mode run on the kernel datapath only. The relay's
+# packet-filter registry only knows frequency_drop / packet_loss / delay /
+# corrupt / bpf / mark.
+KERNEL_ONLY_FILTERS = frozenset({"rate", "reorder", "gemodel", "duplicate", "seed", "limit", "quota"})
 
 # Jitter distributions embedded in the netem-extension uBridge (tc_netem_dist).
 NETEM_DISTRIBUTIONS = ("uniform", "normal", "pareto", "paretonormal")
@@ -220,6 +220,15 @@ def validate_filter_parameters(filter_type: str, values: List[Any]) -> None:
         },
         "seed": {"params_count": (1, 1), "ranges": [(0, 4294967295)], "names": ["Seed"], "units": [""]},
         "limit": {"params_count": (1, 1), "ranges": [(1, 1000000)], "names": ["Limit"], "units": ["packets"]},
+        "quota": {
+            # eBPF stateful classifier (uBridge tc quota_drop): after the byte
+            # quota is consumed, each further packet drops with the given
+            # chance (100 = hard cutoff). Kernel-datapath only.
+            "params_count": (2, 2),
+            "ranges": [(1, 10**15), (0, 100)],
+            "names": ["Quota", "Chance"],
+            "units": ["bytes", "%"],
+        },
         "bpf": {"params_count": (1, 1), "is_text": True, "names": ["Filters"]},
     }