feat: VPCS kernel datapath

A VPCS node's single adapter anchors on a persistent TAP the server
creates (tap create + set_owner via uBridge) and the vpcs process
attaches to by name: -e -d <gp{id8}e0p0> -n, the same
server-creates/guest-attaches shape as QEMU's netdev. -n (a vpcs fork
feature) keeps the guest's ip command from ifconfig'ing the anchor on
the host; the vpcs build is probed once per binary identity
(vpcs_tap capability, usage scan) and gates kernel links together
with ubridge_tap — anything else keeps the node on the relay (the
legacy local UDP tunnel on a stock binary, an AF_PACKET endpoint on
the anchor with a capable one).

VPCSVM takes KernelDatapathMixin: _connect_nio dispatches kernel
(enslave into the per-link bridge) / relay-on-anchor / legacy,
captures pick capture start_kernel vs the bridge engine, stop runs
under an execute lock and terminates the process before deleting the
anchor TAPs (a held device refuses deletion), and the duplicate-port
guard backstops the controller's. The NIO routes accept nio_bridge
and write suspend back on update.

_delete_anchor_taps verifies each tap is gone from sysfs and retries
a bounded three times: a holder can release its fd a moment after its
process was reaped (vpcs's daemon parent kills its console child and
exits first), so the unconditional delete raced EBUSY and leaked the
anchor intermittently.

The vpcs side needs IFNAMSIZ (16) instead of its own IFNAMESIZ (12)
for the -d name buffer — anchor names are 14 chars and truncated to a
nonexistent device, which TUNSETIFF then tries to create without
CAP_NET_ADMIN (fixed in the vpcs fork).

e2e (tests/e2e/test_vpcs_kernel_datapath.py): kernel and relay
scenarios green against the real binary — real ICMP both ways, §E.1/§
E.2 on the anchors, delay/suspend/capture, link delete/re-create,
node stop/restart self-heal, zero leftovers; the relay control passes
with both the fork binary and a stock one.

tests/compute/vpcs/test_vpcs_probe.py

@@ -0,0 +1,78 @@
+#
+# Copyright (C) 2026 GNS3 Technologies Inc.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+import os
+import stat
+
+import pytest
+
+from gns3server.compute.vpcs.vpcs_probe import probe_vpcs_tap
+
+pytestmark = pytest.mark.asyncio
+
+
+def _fake_vpcs(path, usage):
+    path.write_text(f"#!/bin/sh\ncat <<'EOF'\n{usage}\nEOF\n")
+    mode = path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH
+    os.chmod(path, mode)
+
+
+async def test_probe_reports_dash_n_build(config, tmp_path):
+
+    binary = tmp_path / "vpcs"
+    _fake_vpcs(
+        binary,
+        "  -d device      device name, works only when -i is set to 1\n"
+        "  -n             do not auto-configure the host tap interface\n",
+    )
+    config.settings.VPCS.vpcs_path = str(binary)
+    assert await probe_vpcs_tap() is True
+
+
+async def test_probe_reports_upstream_build(config, tmp_path):
+
+    binary = tmp_path / "vpcs"
+    _fake_vpcs(
+        binary,
+        "  -d device      device name, works only when -i is set to 1\n",
+    )
+    config.settings.VPCS.vpcs_path = str(binary)
+    assert await probe_vpcs_tap() is False
+
+
+async def test_probe_reports_missing_binary(config, tmp_path):
+
+    config.settings.VPCS.vpcs_path = str(tmp_path / "does-not-exist")
+    assert await probe_vpcs_tap() is None
+
+
+async def test_probe_caches_by_binary_identity(config, tmp_path):
+    """
+    The same binary answers once; replacing it (a different mtime/size)
+    re-probes.
+    """
+
+    binary = tmp_path / "vpcs"
+    _fake_vpcs(binary, "  -n             do not auto-configure\n")
+    config.settings.VPCS.vpcs_path = str(binary)
+    assert await probe_vpcs_tap() is True
+
+    # replace with a build without the flag: the binary identity changed,
+    # so the cached True must not answer
+    _fake_vpcs(binary, "  -d device      device name\n")
+    os.utime(binary, (0, 0))
+    assert await probe_vpcs_tap() is False

tests/compute/vpcs/test_vpcs_vm.py

@@ -45,7 +45,12 @@ async def vm(compute_project, manager, tmpdir, ubridge_path):
     vm._start_ubridge = AsyncioMagicMock()
     vm._ubridge_hypervisor = MagicMock()
     vm._ubridge_hypervisor.is_running.return_value = True
-    return vm
+    # The legacy-datapath tests run with an unknown probe answer (None):
+    # the tap datapath stays off without a project warning, exactly like a
+    # host whose probe failed. The tap-datapath tests patch the probe to
+    # True (or False, when they assert the fallback) on top.
+    with patch("gns3server.compute.vpcs.vpcs_vm.probe_vpcs_tap", new=AsyncioMagicMock(return_value=None)):
+        yield vm
 
 
 @pytest.mark.asyncio
@@ -350,3 +355,177 @@ async def test_close(vm):
                 await vm.start()
                 await vm.close()
                 assert vm.is_running() is False
+
+
+# ----------------------------------------------------------------------
+# Kernel datapath (the adapter anchor is a persistent TAP the vpcs process
+# attaches to with -e -d, kept away from host auto-configuration with -n)
+# ----------------------------------------------------------------------
+
+
+async def _start_on_tap_datapath(vm):
+    """
+    Start the node with both probes answering (a -n-capable vpcs build, a
+    uBridge with the tap module), returning the recorded uBridge commands.
+    """
+
+    # a startup.vpc left in the shared working directory by an earlier test
+    # would append its name to the command line (the script tests run in any
+    # order) — start from a clean one.
+    try:
+        os.remove(os.path.join(vm.working_dir, "startup.vpc"))
+    except FileNotFoundError:
+        pass
+
+    commands = []
+
+    async def record_send(command):
+        commands.append(command)
+
+    vm._ubridge_send = AsyncioMagicMock(side_effect=record_send)
+    process = MagicMock()
+    process.returncode = None
+    with patch("gns3server.compute.vpcs.vpcs_vm.probe_vpcs_tap", new=AsyncioMagicMock(return_value=True)):
+        with asyncio_patch("gns3server.compute.vpcs.vpcs_vm.VPCSVM._check_requirements", return_value=True):
+            with asyncio_patch("asyncio.create_subprocess_exec", return_value=process) as mock_exec:
+                with asyncio_patch("gns3server.compute.vpcs.vpcs_vm.VPCSVM.start_wrap_console"):
+                    await vm.start()
+    return mock_exec, commands
+
+
+@pytest.mark.asyncio
+async def test_start_tap_datapath(vm):
+    """
+    A -n-capable vpcs build on a tap-capable uBridge anchors the adapter on
+    a persistent TAP and speaks tap mode: -e -d <anchor> -n, no UDP tunnel.
+    """
+
+    mock_exec, commands = await _start_on_tap_datapath(vm)
+    assert vm._tap_datapath is True
+    assert vm._kernel_taps == {(0, 0): "gp00010203e0p0"}
+    assert mock_exec.call_args[0] == (
+        vm._vpcs_path(),
+        "-p",
+        str(vm._internal_console_port),
+        "-m",
+        "1",
+        "-i",
+        "1",
+        "-F",
+        "-R",
+        "-e",
+        "-d",
+        "gp00010203e0p0",
+        "-n",
+    )
+    # the anchor was created through uBridge's tap module, owned by this user
+    assert 'tap create "gp00010203e0p0"' in commands
+    assert f"tap set_owner gp00010203e0p0 {os.getuid()}" in commands
+    # no local UDP tunnel on this datapath
+    assert vm._local_udp_tunnel is None
+
+
+@pytest.mark.asyncio
+async def test_start_legacy_datapath_when_binary_lacks_dash_n(vm):
+    """
+    A vpcs build without -n cannot be kept away from the host side of the
+    anchor, so the node keeps the legacy UDP relay datapath.
+    """
+
+    process = MagicMock()
+    process.returncode = None
+    with patch("gns3server.compute.vpcs.vpcs_vm.probe_vpcs_tap", new=AsyncioMagicMock(return_value=False)):
+        with asyncio_patch("gns3server.compute.vpcs.vpcs_vm.VPCSVM._check_requirements", return_value=True):
+            with asyncio_patch("asyncio.create_subprocess_exec", return_value=process) as mock_exec:
+                with asyncio_patch("gns3server.compute.vpcs.vpcs_vm.VPCSVM.start_wrap_console"):
+                    await vm.start()
+
+    assert vm._tap_datapath is False
+    assert vm._kernel_taps == {}
+    command = mock_exec.call_args[0]
+    assert "-e" not in command
+    assert "-n" not in command
+    assert "-s" in command and "-c" in command and "-t" in command
+
+
+@pytest.mark.asyncio
+async def test_stop_terminates_process_before_deleting_taps(vm):
+    """
+    The vpcs process holds the anchor TAP open: a held device refuses
+    deletion, so the TAP delete must follow the process termination (the
+    suppressed delete of the old order leaked the anchor).
+    """
+
+    calls = []
+    process = MagicMock()
+    process.returncode = None
+    process.terminate.side_effect = lambda: calls.append("terminate")
+
+    async def record_send(command):
+        commands.append(command)
+
+    commands = []
+    vm._ubridge_send = AsyncioMagicMock(side_effect=record_send)
+    with patch("gns3server.compute.vpcs.vpcs_vm.probe_vpcs_tap", new=AsyncioMagicMock(return_value=True)):
+        with asyncio_patch("gns3server.compute.vpcs.vpcs_vm.VPCSVM._check_requirements", return_value=True):
+            with asyncio_patch("asyncio.create_subprocess_exec", return_value=process):
+                with asyncio_patch("gns3server.compute.vpcs.vpcs_vm.VPCSVM.start_wrap_console"):
+                    await vm.start()
+
+    with asyncio_patch("gns3server.utils.asyncio.wait_for_process_termination"):
+        await vm.stop()
+
+    assert calls == ["terminate"]
+    # every tap delete (the start-time sweep and the stop-time teardown)
+    # happened after the process termination
+    assert all(calls.index("terminate") < commands.index(c) for c in commands if c.startswith("tap delete"))
+
+
+@pytest.mark.asyncio
+async def test_add_nio_binding_duplicate_port_rejected(vm):
+    """
+    A port carries at most one NIO: overwriting the one a link still owns
+    orphans that link's teardown.
+    """
+
+    nio = VPCS.instance().create_nio(
+        {"type": "nio_udp", "lport": 4242, "rport": 4243, "rhost": "127.0.0.1", "filters": {}}
+    )
+    await vm.port_add_nio_binding(0, nio)
+    with pytest.raises(VPCSError, match="already has a link"):
+        await vm.port_add_nio_binding(0, nio)
+
+
+@pytest.mark.asyncio
+async def test_kernel_nio_on_legacy_datapath_rejected(vm):
+    """
+    A kernel link to a node running on the legacy relay datapath (no anchor)
+    is refused with a clear error instead of a late uBridge failure.
+    """
+
+    vm._process = MagicMock()
+    vm._process.returncode = None
+    vm._tap_datapath = False
+    nio = VPCS.instance().create_nio({"type": "nio_bridge", "bridge": "gns3testbridge", "filters": {}})
+    with pytest.raises(VPCSError, match="legacy relay datapath"):
+        await vm.port_add_nio_binding(0, nio)
+
+
+@pytest.mark.asyncio
+async def test_kernel_nio_attach_enslaves_the_anchor(vm):
+    """
+    A kernel link enslaves the anchor into the per-link bridge and installs
+    the impairment filters the NIO carries — the same _kernel_attach flow
+    every anchor-backed node type uses.
+    """
+
+    await _start_on_tap_datapath(vm)
+    nio = VPCS.instance().create_nio(
+        {"type": "nio_bridge", "bridge": "gns3testbridge", "filters": {"delay": [100]}}
+    )
+    await vm.port_add_nio_binding(0, nio)
+
+    sent = [call[0][0] for call in vm._ubridge_send.call_args_list]
+    assert 'brctl create "gns3testbridge"' in sent
+    assert 'brctl addif "gns3testbridge" "gp00010203e0p0"' in sent
+    assert any(c.startswith('tc netem set "gp00010203e0p0" delay 100') for c in sent)