NgTech-LTD/gns3-server
2
0
Fork 0
mirror of https://github.com/GNS3/gns3-server.git synced 2026-10-12 13:35:31 +03:00
Code Issues Packages Projects Releases Wiki Activity

feat(iou): anchor every Ethernet bay/unit on a persistent TAP

Browse Source 
IOU's only wire is the IOL fabric (Unix datagrams, 8-byte headers,
NETMAP), so it has no host netdev to enslave — the kernel datapath gives
each Ethernet bay/unit a persistent TAP anchor the uBridge IOL bridge
binds the port to (iol_bridge add_nio_tap), which links then enslave into
their per-link kernel bridge exactly like Docker's veth and QEMU's TAP.

* IOUVM joins KernelDatapathMixin: one TAP per Ethernet bay/unit
  (gi{id8}e{bay}p{unit}), created at start after a capability probe and a
  stale sweep, born down and address-free; serial bays never anchor.
* _networking dispatches per NIO type: a relay link keeps iol_bridge
  add_nio_udp, a kernel link binds the anchor then runs _kernel_attach.
* Stop order is QEMU's reverse, because uBridge holds the anchor fds:
  iol_bridge delete (releases every port NIO) -> tap delete (a held TAP
  answers EBADFD) -> brctl delete -> hypervisor stop. Removing a single
  link releases its fd the same way (delete_nio_tap).
* The IOU-specific marker reconcile override is gone: marker primitives
  are polymorphic on the anchor (marker *_kernel on a TAP, iol_bridge
  commands on an IOL location), so the base reconcile serves both.

Capture on a kernel link anchors on the TAP (capture start_kernel);
filters are tc on the anchor, never combined with the userspace
iol_bridge filters a relay link uses.
This commit is contained in:
YueGuobin 2026-10-01 00:59:37 +08:00
parent 81ad9b837f
commit 9a14a91293
No known key found for this signature in database
3 changed files with 723 additions and 131 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
gns3server/compute/base_node.py
View File

@ -1449,7 +1449,8 @@ class BaseNode:
The anchor is resolved from the (name, link_id)→bridge map populated at
apply time; entries are iterated so a node that hosts the same marker name
on several links (e.g. IOU with one IOL-BRIDGE per node) toggles every
copy. IOU overrides this for its ``iol_bridge`` command shape.
copy. IOU's ``iol_bridge`` command shape lives in its
``_ubridge_enable_marker_filter`` override.
:param name: marker filter name
:param enabled: True = on (signal+pcap), False = off (paused tap)

438
gns3server/compute/iou/iou_vm.py
View File

@ -36,6 +36,7 @@ import sys
import gns3server.utils.asyncio
import gns3server.utils.images
from gns3server.compute.ubridge.tc_probe import probe_iol_tap_support
from gns3server.compute.ubridge.ubridge_error import UbridgeError
from gns3server.utils.asyncio import locking
from gns3server.utils.asyncio.ssh_server import AsyncioSSHServer
@ -46,6 +47,8 @@ from gns3server.utils.hostname import is_ios_hostname_valid
from ..adapters.ethernet_adapter import EthernetAdapter
from ..adapters.serial_adapter import SerialAdapter
from ..base_node import BaseNode
from ..kernel_datapath import KernelDatapathMixin
from ..nios.nio_bridge import NIOBridge
from ..nios.nio_udp import NIOUDP
from .iou_error import IOUError
from .utils.iou_export import nvram_export
@ -133,7 +136,7 @@ class IOUL1KeepaliveProtocol(asyncio.DatagramProtocol):
log.debug('IOU "%s": could not send an L1 keepalive: %s', self._vm.name, e)
class IOUVM(BaseNode):
class IOUVM(KernelDatapathMixin, BaseNode):
module_name = "iou"
# Class-level caches shared across all IOU VM instances using the same image.
@ -189,6 +192,13 @@ class IOUVM(BaseNode):
self._application_id = application_id
self._l1_keepalives = False
# Kernel datapath (see KernelDatapathMixin): one persistent TAP per
# Ethernet bay/unit, opened and held by uBridge's iol_bridge while a
# kernel link attaches the port (iol_bridge add_nio_tap).
self._kernel_taps = {}
self._ubridge_tc_caps = None
self._tap_datapath = False
def _nvram_changed(self, path):
"""
Called when the NVRAM file has changed
@ -675,6 +685,7 @@ class IOUVM(BaseNode):
await self._check_iou_license()
await self._start_ubridge()
await self._prepare_tap_datapath()
self._create_netmap_config()
if self.use_default_iou_values:
# make sure we have the default nvram amount to correctly push the configs
@ -784,10 +795,14 @@ class IOUVM(BaseNode):
@locking
async def _networking(self):
"""
Configures the IOL bridge in uBridge.
Configures the IOL bridge in uBridge: every port's NIO is wired to
it — a relay link (NIOUDP) as an ``iol_bridge`` UDP NIO, a kernel
link (NIOBridge) by binding the port's anchor TAP to the bridge
(``iol_bridge add_nio_tap``) and enslaving that TAP into the link's
per-link kernel bridge.
"""
bridge_name = f"IOL-BRIDGE-{self.application_id + 512}"
bridge_name = self._iol_bridge_name()
try:
# delete any previous bridge if it exists
await self._ubridge_send(f"iol_bridge delete {bridge_name}")
@ -806,20 +821,175 @@ class IOUVM(BaseNode):
)
if nio.capturing:
await self._ubridge_send(
'iol_bridge start_capture {name} "{output_file}" {data_link_type}'.format(
'iol_bridge start_capture {name} {bay} {unit} "{output_file}" {data_link_type}'.format(
name=bridge_name,
bay=bay_id,
unit=unit_id,
output_file=nio.pcap_output_file,
data_link_type=re.sub(r"^DLT_", "", nio.pcap_data_link_type),
)
)
await self._ubridge_apply_filters(bay_id, unit_id, nio.filters)
await self._ubridge_apply_markers(bay_id, unit_id, nio)
location = self._iol_location(bay_id, unit_id)
await self._ubridge_apply_filters(location, nio.filters)
await self._ubridge_apply_markers(location, nio)
elif nio and isinstance(nio, NIOBridge):
await self._attach_kernel_nio(bay_id, unit_id, nio)
unit_id += 1
bay_id += 1
await self._ubridge_send(f"iol_bridge start {bridge_name}")
# ------------------------------------------------------------------
# Kernel datapath: the port anchor is a persistent TAP held by uBridge
# ------------------------------------------------------------------
def _iol_bridge_name(self):
"""
Name of this node's IOL bridge in uBridge (the fake IOL instance
the NETMAP maps every bay/unit to).
"""
return f"IOL-BRIDGE-{self.application_id + 512}"
def _iol_location(self, adapter_number, port_number):
"""
uBridge's location token for one IOL port: ``iol_bridge`` commands
take the bridge name plus the bay/unit coordinates positionally.
"""
return f"{self._iol_bridge_name()} {adapter_number} {port_number}"
def _tap_name(self, adapter_number, port_number):
"""
Deterministic anchor TAP name for an Ethernet bay/unit. The ``gi``
prefix keeps it out of the ``gns3`` bridge/TAP name space (and apart
from Docker's ``gv``/``gc`` and QEMU's ``gq``); 8 hex chars of the
node id plus bay/unit keep it unique and within IFNAMSIZ (15).
"""
return f"gi{self._id.replace('-', '')[:8]}e{adapter_number}p{port_number}"
def _kernel_host_ifc(self, adapter_number, port_number=0):
"""
The persistent TAP this Ethernet bay/unit owns, or None on serial
bays (never anchored) and before the node started.
"""
return self._kernel_taps.get((adapter_number, port_number))
def _kernel_anchors(self):
"""
Every anchor TAP this node currently owns.
"""
return set(self._kernel_taps.values())
def _kernel_error(self, message):
return IOUError(message)
async def _prepare_tap_datapath(self):
"""
Probe uBridge for the commands the kernel datapath needs (the tap
module plus ``iol_bridge add_nio_tap``, both covered by the compute
capability probe, cached by binary identity) and, when it answers,
create the persistent TAP every Ethernet bay/unit owns — the anchor
role QEMU's TAPs and Docker's veth host ends play. A uBridge
without them keeps this node on the relay datapath: every link
rides ``iol_bridge add_nio_udp``, exactly as before.
"""
self._tap_datapath = False
self._kernel_taps.clear()
if not self.ubridge:
return
if await probe_iol_tap_support() is not True:
message = (
f'IOU "{self._name}": uBridge cannot bind an IOL port to a persistent TAP '
"(iol_bridge add_nio_tap); this node runs on the relay datapath and cannot "
"carry kernel links"
)
log.warning(message)
self.project.emit("log.warning", {"message": message})
return
self._tap_datapath = True
await self._create_taps()
async def _create_taps(self):
"""
Create the persistent TAP every Ethernet bay/unit owns (four units
per bay, the IOU adapter model). uBridge holds a device's fd only
while a kernel link binds the port to it (``iol_bridge
add_nio_tap``); until then the TAP sits DOWN with no holder, and it
survives link churn untouched — links attach to it, never recreate
it. A persistent TAP outlives its creator, so a leftover from a
previous run (crash, kill) is swept first.
"""
for adapter_number, adapter in enumerate(self._ethernet_adapters):
for port_number in adapter.ports.keys():
tap = self._tap_name(adapter_number, port_number)
with contextlib.suppress(UbridgeError):
await self._ubridge_send(f'tap delete "{tap}"')
await self._ubridge_send(f'tap create "{tap}"')
await self._ubridge_send(f'link set "{tap}" down')
self._kernel_taps[(adapter_number, port_number)] = tap
async def _attach_kernel_nio(self, adapter_number, port_number, nio):
"""
Wire a kernel link's NIO (NIOBridge) on a running node: bind the
port's anchor TAP to the IOL bridge (uBridge opens and holds the
fd, relaying the IOL fabric onto the device), then enslave the TAP
into the per-link kernel bridge — the shared mixin flow, with the
anchor playing the role Docker's veth and QEMU's TAP play.
"""
anchor = self._kernel_host_ifc(adapter_number, port_number)
if anchor is None:
raise self._kernel_error(
"Bay {bay}/{unit} of IOU '{name}' has no TAP anchor to carry a kernel link "
"(serial ports stay on the relay datapath, and a node whose uBridge lacks "
"iol_bridge add_nio_tap runs relay-only)".format(
bay=adapter_number, unit=port_number, name=self._name
)
)
await self._ubridge_send(
'iol_bridge add_nio_tap {name} {iol_id} {bay} {unit} "{tap}"'.format(
name=self._iol_bridge_name(),
iol_id=self.application_id,
bay=adapter_number,
unit=port_number,
tap=anchor,
)
)
await self._kernel_attach(anchor, nio)
await self._set_adapter_carrier(adapter_number, not nio.suspend, port_number)
async def _stop_ubridge(self):
"""
Stops uBridge, releasing the kernel datapath's host state first —
in the reverse order of QEMU's stop, because here uBridge itself
holds the anchor TAPs open (``iol_bridge add_nio_tap``): the IOL
bridge must be deleted, closing every port's TAP fd, before
``tap delete`` can succeed (a held device answers EBADFD), and the
per-link kernel bridges need the control channel as well. The next
start spawns a fresh uBridge, so the tc capabilities must be probed
again.
"""
if self.ubridge:
with contextlib.suppress(UbridgeError):
await self._ubridge_send(f"iol_bridge delete {self._iol_bridge_name()}")
for tap in self._kernel_taps.values():
with contextlib.suppress(UbridgeError):
await self._ubridge_send(f'tap delete "{tap}"')
await self._remove_kernel_bridges()
self._kernel_taps.clear()
self._ubridge_tc_caps = None
await super()._stop_ubridge()
def _termination_callback(self, process_name, returncode):
"""
Called when the process has stopped.
@ -1179,12 +1349,23 @@ class IOUVM(BaseNode):
log.debug(f'IOU "{self._name}" [{self._id}]: {nio} added to {adapter_number}/{port_number}')
if self.ubridge:
bridge_name = f"IOL-BRIDGE-{self.application_id + 512}"
if isinstance(nio, NIOBridge):
await self._attach_kernel_nio(adapter_number, port_number, nio)
return
await self._ubridge_send(
f"iol_bridge add_nio_udp {bridge_name} {self.application_id} {adapter_number} {port_number} {nio.lport} {nio.rhost} {nio.rport}"
"iol_bridge add_nio_udp {name} {iol_id} {bay} {unit} {lport} {rhost} {rport}".format(
name=self._iol_bridge_name(),
iol_id=self.application_id,
bay=adapter_number,
unit=port_number,
lport=nio.lport,
rhost=nio.rhost,
rport=nio.rport,
)
)
await self._ubridge_apply_filters(adapter_number, port_number, nio.filters)
await self._ubridge_apply_markers(adapter_number, port_number, nio)
location = self._iol_location(adapter_number, port_number)
await self._ubridge_apply_filters(location, nio.filters)
await self._ubridge_apply_markers(location, nio)
async def adapter_update_nio_binding(self, adapter_number, port_number, nio):
"""
@ -1196,131 +1377,96 @@ class IOUVM(BaseNode):
"""
if self.ubridge:
await self._ubridge_apply_filters(adapter_number, port_number, nio.filters)
await self._ubridge_apply_markers(adapter_number, port_number, nio)
if isinstance(nio, NIOBridge):
# Filters or markers changed on an attached kernel link, or
# its suspend state did: re-apply on the anchor, no
# re-binding of the IOL port and no re-enslaving.
anchor = self._kernel_host_ifc(adapter_number, port_number)
if anchor is not None:
await self._kernel_update(anchor, nio)
await self._set_adapter_carrier(adapter_number, not nio.suspend, port_number)
return
location = self._iol_location(adapter_number, port_number)
await self._ubridge_apply_filters(location, nio.filters)
await self._ubridge_apply_markers(location, nio)
async def _ubridge_apply_filters(self, adapter_number, port_number, filters):
async def _ubridge_apply_filters(self, location, filters):
"""
Apply filter like rate limiting
Apply relay packet filters on one IOL port (``iol_bridge``
userspace filters). Kernel links never come here — their filters
run as tc on the port's anchor (see _attach_kernel_nio /
_kernel_update).
:param adapter_number: adapter number
:param port_number: port number
:param location: the port's IOL location ("{bridge} {bay} {unit}")
:param filters: Array of filter dictionnary
"""
bridge_name = f"IOL-BRIDGE-{self.application_id + 512}"
location = f"{bridge_name} {adapter_number} {port_number}"
await self._ubridge_send("iol_bridge reset_packet_filters " + location)
for filter in self._build_filter_list(filters):
cmd = f"iol_bridge add_packet_filter {location} {filter}"
await self._ubridge_send(cmd)
async def _ubridge_apply_markers(self, adapter_number, port_number, nio):
async def _ubridge_add_marker_filter(
self, location, name, bpf, pcap_path, tag=None, link_id=None, direction=None, data_link_type=None
):
"""
Reconcile traffic-insight markers on the IOL bridge (diff desired
``nio.markers`` against installed ``_marker_specs``): delete removed,
rebuild changed, toggle on/off-only changes, add new, skip unchanged.
IOU uses ``iol_bridge`` (not ``bridge``) and the ``add_packet_filter``
command carries extra ``{bay} {unit}`` positional arguments between the
bridge name and the filter name — this override mirrors the pattern in
``_ubridge_apply_filters`` above.
:param adapter_number: bay id
:param port_number: unit id
:param nio: NIO instance carrying ``nio.markers``
IOU's `mark` filter attach. The marker anchor is polymorphic: on the
relay datapath it is the port's IOL location, and ``iol_bridge
add_packet_filter`` carries extra ``{bay} {unit}`` positionals between
the bridge name and the filter name; on the kernel datapath it is the
port's TAP, and the mixin's ``marker add_kernel`` applies.
"""
from gns3server.compute.marker.marker_manager import MarkerManager
markers = nio.markers if hasattr(nio, "markers") else {}
manager = MarkerManager.instance()
markers_dir = self.project.markers_working_directory()
bridge_name = f"IOL-BRIDGE-{self.application_id + 512}"
location = f"{bridge_name} {adapter_number} {port_number}"
desired = {(name, spec.get("link_id", "")): spec for name, spec in markers.items()}
if self._kernel_marker_anchor(location):
await super()._ubridge_add_marker_filter(
location,
name,
bpf,
pcap_path,
tag=tag,
link_id=link_id,
direction=direction,
data_link_type=data_link_type,
)
return
self._validate_marker_name(name)
# iol_bridge add_packet_filter {br} {bay} {unit} {name} mark "{bpf}" [tag {id}] pcap "{path}"
cmd = 'iol_bridge add_packet_filter {loc} {name} mark "{bpf}"'.format(loc=location, name=name, bpf=bpf)
if tag is not None:
cmd += f" tag {tag}"
if link_id:
cmd += f" link {link_id}"
if direction is not None:
cmd += f" dir {direction}"
linktype = self._marker_linktype(data_link_type)
if linktype is not None:
cmd += f" linktype {linktype}"
cmd += ' pcap "{path}"'.format(path=pcap_path)
await self._ubridge_send(cmd)
# 1. Remove installed markers that are no longer desired.
# Scope to THIS port's IOL location — the map is node-wide and also
# holds markers on this IOU's other ports, which must not be deleted
# when reconciling a single NIO (see base_node for the same guard).
for key in list(self._marker_filter_bridges):
if self._marker_filter_bridges[key] != location:
continue
if key not in desired:
mname, link_id = key
installed_location = self._marker_filter_bridges.pop(key)
self._marker_specs.pop(key, None)
await self._ubridge_delete_marker_filter(installed_location, mname)
try:
os.remove(os.path.join(markers_dir, f"{self._id}_{link_id}_{mname}.pcap"))
except FileNotFoundError:
pass
except OSError as e:
log.warning("Could not remove marker pcap for '%s' on link %s: %s", mname, link_id, e)
manager.unregister(self._id, mname)
async def _ubridge_enable_marker_filter(self, location, name, state):
"""
IOU's on/off toggle: ``iol_bridge enable_packet_filter`` on the
relay datapath (the port's IOL location), the mixin's
``marker enable_kernel`` on the kernel datapath's anchor.
"""
# 2. Add / reconcile desired markers.
rebuild_fields = ("bpf", "tag", "direction", "data_link_type")
for (name, link_id), spec in desired.items():
bpf = spec.get("bpf", "")
tag = spec.get("tag")
enabled = spec.get("enabled", True)
if (name, link_id) in self._marker_filter_bridges:
installed_spec = self._marker_specs.get((name, link_id))
if installed_spec is None:
continue # installed (legacy, no spec) — skip to avoid dup
if any(installed_spec.get(f) != spec.get(f) for f in rebuild_fields):
installed_location = self._marker_filter_bridges.get((name, link_id))
await self._ubridge_delete_marker_filter(installed_location, name)
elif installed_spec.get("enabled", True) != enabled:
await self._ubridge_set_marker_filter_state(name, enabled)
self._marker_specs[(name, link_id)] = spec
continue
else:
continue
pcap_path = os.path.join(markers_dir, f"{self._id}_{link_id}_{name}.pcap")
# iol_bridge add_packet_filter {br} {bay} {unit} {name} mark "{bpf}" [tag {id}] pcap "{path}"
cmd = f'iol_bridge add_packet_filter {location} {name} mark "{bpf}"'
if tag is not None:
cmd += f" tag {tag}"
if link_id:
cmd += f" link {link_id}"
direction = spec.get("direction")
if direction is not None:
cmd += f" dir {direction}"
linktype = self._marker_linktype(spec.get("data_link_type"))
if linktype is not None:
cmd += f" linktype {linktype}"
cmd += f' pcap "{pcap_path}"'
try:
await self._ubridge_send(cmd)
except UbridgeError as e:
if "syntax error" in str(e).lower() or "compile filter" in str(e).lower():
message = f"Warning: ignoring marker '{name}' due to BPF syntax error: {e}"
log.warning(message)
self.project.emit("log.warning", {"message": message})
continue
raise
if not enabled:
try:
await self._ubridge_send(f"iol_bridge enable_packet_filter {location} {name} off")
except UbridgeError as e:
log.warning(f"Could not turn marker '{name}' off on {location}: {e}")
manager.register(str(self.project.id), self._id, name, link_id, tag)
self._marker_filter_bridges[name, link_id] = location
self._marker_specs[name, link_id] = spec
async def _ubridge_set_marker_filter_state(self, name, enabled):
"""IOU override: toggle every (name, link_id) entry via ``iol_bridge``."""
state = "on" if enabled else "off"
for (n, lid), location in list(self._marker_filter_bridges.items()):
if n == name:
await self._ubridge_send(f"iol_bridge enable_packet_filter {location} {name} {state}")
if self._kernel_marker_anchor(location):
await super()._ubridge_enable_marker_filter(location, name, state)
return
await self._ubridge_send(f"iol_bridge enable_packet_filter {location} {name} {state}")
async def _ubridge_delete_marker_filter(self, location, name):
"""IOU override: remove a single marker filter via ``iol_bridge``
(location = ``{bridge} {bay} {unit}``), not a bridge-wide reset."""
"""
IOU override: remove a single marker filter via ``iol_bridge`` on
the relay datapath (location = ``{bridge} {bay} {unit}``), via the
mixin's ``marker delete_kernel`` on a kernel anchor — both
fine-grained, not a bridge-wide reset.
"""
if self._kernel_marker_anchor(location):
await super()._ubridge_delete_marker_filter(location, name)
return
if not (self._ubridge_hypervisor and self._ubridge_hypervisor.is_running()):
return
try:
@ -1353,8 +1499,24 @@ class IOUVM(BaseNode):
log.debug(f'IOU "{self._name}" [{self._id}]: {nio} removed from {adapter_number}/{port_number}')
if self.ubridge:
bridge_name = f"IOL-BRIDGE-{self.application_id + 512}"
await self._ubridge_send(f"iol_bridge delete_nio_udp {bridge_name} {adapter_number} {port_number}")
if isinstance(nio, NIOBridge):
await self._remove_kernel_nio(nio, adapter_number, port_number)
# Release the anchor's fd while the control channel lives:
# uBridge holds it while the port is bound (add_nio_tap),
# and a held TAP answers tap delete with EBADFD. The
# persistent device itself survives for the next link.
with contextlib.suppress(UbridgeError):
await self._ubridge_send(
"iol_bridge delete_nio_tap {name} {bay} {unit}".format(
name=self._iol_bridge_name(), bay=adapter_number, unit=port_number
)
)
else:
await self._ubridge_send(
"iol_bridge delete_nio_udp {name} {bay} {unit}".format(
name=self._iol_bridge_name(), bay=adapter_number, unit=port_number
)
)
return nio
@ -1674,16 +1836,26 @@ class IOUVM(BaseNode):
)
if self.ubridge:
bridge_name = f"IOL-BRIDGE-{self.application_id + 512}"
await self._ubridge_send(
'iol_bridge start_capture {name} {bay} {unit} "{output_file}" {data_link_type}'.format(
name=bridge_name,
bay=adapter_number,
unit=port_number,
output_file=output_file,
data_link_type=re.sub(r"^DLT_", "", data_link_type),
if isinstance(nio, NIOBridge):
# Kernel link: capture on the port's TAP anchor (AF_PACKET).
anchor = self._kernel_host_ifc(adapter_number, port_number)
if anchor is None:
raise self._kernel_error(
"Bay {bay}/{unit} of IOU '{name}' has no TAP anchor to capture on".format(
bay=adapter_number, unit=port_number, name=self._name
)
)
await self._ubridge_send(f'capture start_kernel {anchor} "{output_file}"')
else:
await self._ubridge_send(
'iol_bridge start_capture {name} {bay} {unit} "{output_file}" {data_link_type}'.format(
name=self._iol_bridge_name(),
bay=adapter_number,
unit=port_number,
output_file=output_file,
data_link_type=re.sub(r"^DLT_", "", data_link_type),
)
)
)
async def stop_capture(self, adapter_number, port_number):
"""
@ -1699,5 +1871,11 @@ class IOUVM(BaseNode):
nio.stop_packet_capture()
log.debug(f'IOU "{self._name}" [{self._id}]: stopping packet capture on {adapter_number}/{port_number}')
if self.ubridge:
bridge_name = f"IOL-BRIDGE-{self.application_id + 512}"
await self._ubridge_send(f"iol_bridge stop_capture {bridge_name} {adapter_number} {port_number}")
if isinstance(nio, NIOBridge):
await self._ubridge_send("capture stop_kernel")
else:
await self._ubridge_send(
"iol_bridge stop_capture {name} {bay} {unit}".format(
name=self._iol_bridge_name(), bay=adapter_number, unit=port_number
)
)

413
tests/compute/iou/test_iou_kernel_datapath.py Normal file
View File

@ -0,0 +1,413 @@
#
# 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 as either version 2 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 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/>.
#
"""
Kernel-datapath wiring for IOU: the persistent TAP every Ethernet bay/unit
owns, the IOL-fabric binding (iol_bridge add_nio_tap) a kernel link adds to
it, kernel-link enslavement, the relay fallback for a uBridge without the
command, and the reverse-of-QEMU stop order (uBridge holds the anchor fds).
"""
import pytest
import pytest_asyncio
from unittest.mock import MagicMock, patch
from tests.utils import AsyncioMagicMock
from gns3server.compute.iou import IOU
from gns3server.compute.iou.iou_vm import IOUVM
from gns3server.compute.iou.iou_error import IOUError
from gns3server.compute.nios.nio_bridge import NIOBridge
NODE_ID = "00010203-0405-0607-0809-0a0b0c0d0e0f"
BRIDGE = "gns3a1b2c3d4e5f"
TAP00 = "gi00010203e0p0" # the vm fixture's node id, bay 0 unit 0
IOL_BRIDGE = "IOL-BRIDGE-513" # application_id 1 + 512
@pytest_asyncio.fixture
async def manager(port_manager):
m = IOU.instance()
m.port_manager = port_manager
return m
@pytest_asyncio.fixture(scope="function")
async def vm(compute_project, manager):
vm = IOUVM("test", NODE_ID, compute_project, manager, application_id=1)
vm._ubridge_hypervisor = MagicMock()
vm._ubridge_hypervisor.is_running.return_value = True
vm._ubridge_send = AsyncioMagicMock()
return vm
def _capable(vm, monkeypatch):
"""Make the iol-tap capability probe answer True."""
async def probe(timeout=15.0):
return True
monkeypatch.setattr("gns3server.compute.iou.iou_vm.probe_iol_tap_support", probe)
return vm
# ---------------------------------------------------------------------------
# Anchor lifecycle
# ---------------------------------------------------------------------------
@pytest.mark.asyncio
async def test_prepare_tap_datapath_creates_one_tap_per_ethernet_unit(vm, monkeypatch):
"""
On a capable uBridge every Ethernet bay/unit gets its persistent TAP —
four units per bay, the IOU adapter model — swept of leftovers first and
born down. Serial bays never anchor.
"""
_capable(vm, monkeypatch)
await vm._prepare_tap_datapath()
assert vm._tap_datapath is True
assert set(vm._kernel_taps) == {(bay, unit) for bay in range(2) for unit in range(4)}
assert vm._kernel_taps[(0, 0)] == TAP00
vm._ubridge_send.assert_any_call(f'tap delete "{TAP00}"')
vm._ubridge_send.assert_any_call(f'tap create "{TAP00}"')
vm._ubridge_send.assert_any_call(f'link set "{TAP00}" down')
assert not any("set_owner" in str(c) for c in vm._ubridge_send.call_args_list)
@pytest.mark.asyncio
async def test_prepare_tap_datapath_falls_back_without_the_command(vm, monkeypatch):
"""
A uBridge without iol_bridge add_nio_tap keeps the node on the relay
datapath — it still starts, it just cannot carry kernel links.
"""
async def probe(timeout=15.0):
return None
monkeypatch.setattr("gns3server.compute.iou.iou_vm.probe_iol_tap_support", probe)
with patch.object(vm.project, "emit") as emit:
await vm._prepare_tap_datapath()
assert vm._tap_datapath is False
assert vm._kernel_taps == {}
assert emit.called
def test_tap_name_fits_ifnamsiz(vm):
"""
The anchor name has to fit IFNAMSIZ (15) even for a late bay/unit.
"""
assert len(vm._tap_name(15, 3)) <= 15
def test_kernel_host_ifc_is_none_on_serial_bays(vm):
"""
Serial bays (past the Ethernet adapters) never anchor, so a kernel link
there fails with the serial-port message rather than wiring nonsense.
"""
assert vm._kernel_host_ifc(2, 0) is None
# ---------------------------------------------------------------------------
# Link attach / detach
# ---------------------------------------------------------------------------
@pytest.mark.asyncio
async def test_attach_kernel_nio_binds_the_anchor_and_enslaves_it(vm):
"""
A kernel link binds the port's anchor TAP to the IOL bridge (uBridge
holds the fd and relays the fabric onto it), then enslaves the TAP into
the per-link kernel bridge.
"""
vm._kernel_taps[(0, 0)] = TAP00
nio = vm.manager.create_nio({"type": "nio_bridge", "bridge": BRIDGE})
await vm._attach_kernel_nio(0, 0, nio)
vm._ubridge_send.assert_any_call(f'iol_bridge add_nio_tap {IOL_BRIDGE} 1 0 0 "{TAP00}"')
vm._ubridge_send.assert_any_call(f'brctl create "{BRIDGE}"')
vm._ubridge_send.assert_any_call(f'link set "{BRIDGE}" up')
vm._ubridge_send.assert_any_call(f'brctl addif "{BRIDGE}" "{TAP00}"')
vm._ubridge_send.assert_any_call(f'link set "{TAP00}" up')
@pytest.mark.asyncio
async def test_attach_kernel_nio_without_anchor_raises(vm):
"""
A kernel link on a serial bay (or a node that never anchored) is an
error naming the relay datapath, not a silent fallback.
"""
nio = vm.manager.create_nio({"type": "nio_bridge", "bridge": BRIDGE})
with pytest.raises(IOUError, match="no TAP anchor"):
await vm._attach_kernel_nio(2, 0, nio)
@pytest.mark.asyncio
async def test_add_nio_binding_relay_keeps_the_iol_udp_path(vm):
"""
A relay link is wired exactly as before: a UDP NIO on the IOL bridge
port, userspace filters at the port's IOL location.
"""
vm._ubridge_hypervisor.is_running.return_value = True
nio = vm.manager.create_nio({"type": "nio_udp", "lport": 20000, "rhost": "127.0.0.1", "rport": 20001})
nio.filters = {"delay": [10]}
await vm.adapter_add_nio_binding(0, 0, nio)
vm._ubridge_send.assert_any_call(f"iol_bridge add_nio_udp {IOL_BRIDGE} 1 0 0 20000 127.0.0.1 20001")
vm._ubridge_send.assert_any_call(f"iol_bridge reset_packet_filters {IOL_BRIDGE} 0 0")
vm._ubridge_send.assert_any_call(f"iol_bridge add_packet_filter {IOL_BRIDGE} 0 0 filter0 delay 10")
@pytest.mark.asyncio
async def test_update_nio_binding_kernel_reapplies_on_the_anchor(vm):
"""
A filter update on an attached kernel link reconciles on the anchor
(tc) without re-binding the IOL port or re-enslaving the TAP.
"""
vm._kernel_taps[(0, 0)] = TAP00
nio = vm.manager.create_nio({"type": "nio_bridge", "bridge": BRIDGE})
vm._ethernet_adapters[0].add_nio(0, nio)
nio.filters = {"delay": [10]}
await vm.adapter_update_nio_binding(0, 0, nio)
vm._ubridge_send.assert_any_call(f'tc reset "{TAP00}"')
vm._ubridge_send.assert_any_call(f'tc netem set "{TAP00}" delay 10')
assert not any("iol_bridge add_nio" in str(c) for c in vm._ubridge_send.call_args_list)
assert not any("brctl addif" in str(c) for c in vm._ubridge_send.call_args_list)
@pytest.mark.asyncio
async def test_update_nio_binding_kernel_suspend_flaps_the_anchor(vm):
"""
Suspending a kernel link admin-downs the anchor: the IOL relay's writes
fail EIO (dropped) and nothing comes back — a genuinely dead link.
"""
vm._kernel_taps[(0, 0)] = TAP00
nio = vm.manager.create_nio({"type": "nio_bridge", "bridge": BRIDGE})
vm._ethernet_adapters[0].add_nio(0, nio)
nio.suspend = True
await vm.adapter_update_nio_binding(0, 0, nio)
vm._ubridge_send.assert_any_call(f'link set "{TAP00}" down')
@pytest.mark.asyncio
async def test_remove_nio_binding_kernel_releases_the_fd_and_detaches(vm):
"""
Removing a kernel link detaches the anchor from the per-link bridge,
resets its qdisc, and unbinds the port from the TAP — releasing uBridge's
fd while the control channel lives, so a later tap delete cannot hit
EBADFD.
"""
vm._kernel_taps[(0, 0)] = TAP00
nio = vm.manager.create_nio({"type": "nio_bridge", "bridge": BRIDGE})
vm._ethernet_adapters[0].add_nio(0, nio)
await vm.adapter_remove_nio_binding(0, 0)
vm._ubridge_send.assert_any_call(f'tc reset "{TAP00}"')
vm._ubridge_send.assert_any_call(f'brctl delif "{BRIDGE}" "{TAP00}"')
vm._ubridge_send.assert_any_call(f'brctl delete "{BRIDGE}"')
vm._ubridge_send.assert_any_call(f"iol_bridge delete_nio_tap {IOL_BRIDGE} 0 0")
# ---------------------------------------------------------------------------
# Stop order (uBridge holds the anchor fds — the reverse of QEMU)
# ---------------------------------------------------------------------------
@pytest.mark.asyncio
async def test_stop_ubridge_releases_fds_before_deleting_taps(vm):
"""
The IOL bridge must be deleted (closing every port's TAP fd) before the
taps are unpersisted, and the per-link bridges still need the control
channel — all before the hypervisor itself stops.
"""
vm._kernel_taps[(0, 0)] = TAP00
nio = vm.manager.create_nio({"type": "nio_bridge", "bridge": BRIDGE})
vm._ethernet_adapters[0].add_nio(0, nio)
with patch("gns3server.compute.base_node.BaseNode._stop_ubridge", new=AsyncioMagicMock()) as stop:
await vm._stop_ubridge()
commands = [str(c[0][0]) if c[0] else "" for c in vm._ubridge_send.call_args_list]
assert commands.index(f"iol_bridge delete {IOL_BRIDGE}") < commands.index(f'tap delete "{TAP00}"')
assert commands.index(f'tap delete "{TAP00}"') < commands.index(f'brctl delete "{BRIDGE}"')
assert commands.index(f'brctl delete "{BRIDGE}"') < len(commands)
assert stop.called
assert vm._kernel_taps == {}
assert vm._ubridge_tc_caps is None
# ---------------------------------------------------------------------------
# _networking (node start with links already attached)
# ---------------------------------------------------------------------------
@pytest.mark.asyncio
async def test_networking_wires_kernel_and_relay_ports(vm):
"""
On start, a kernel-linked port binds its anchor to the IOL bridge and
enslaves it; a relay-linked port keeps its UDP NIO. The IOL bridge is
recreated and started around both.
"""
vm._kernel_taps[(0, 0)] = TAP00
kernel_nio = vm.manager.create_nio({"type": "nio_bridge", "bridge": BRIDGE})
vm._ethernet_adapters[0].add_nio(0, kernel_nio)
relay_nio = vm.manager.create_nio({"type": "nio_udp", "lport": 20000, "rhost": "127.0.0.1", "rport": 20001})
vm._ethernet_adapters[1].add_nio(1, relay_nio)
await vm._networking()
vm._ubridge_send.assert_any_call(f"iol_bridge delete {IOL_BRIDGE}")
vm._ubridge_send.assert_any_call(f"iol_bridge create {IOL_BRIDGE} 513")
vm._ubridge_send.assert_any_call(f'iol_bridge add_nio_tap {IOL_BRIDGE} 1 0 0 "{TAP00}"')
vm._ubridge_send.assert_any_call(f'brctl addif "{BRIDGE}" "{TAP00}"')
vm._ubridge_send.assert_any_call(f"iol_bridge add_nio_udp {IOL_BRIDGE} 1 1 1 20000 127.0.0.1 20001")
vm._ubridge_send.assert_any_call(f"iol_bridge start {IOL_BRIDGE}")
@pytest.mark.asyncio
async def test_networking_restores_relay_capture_with_port_coordinates(vm):
"""
A capture active across a restart is restored on the port's bay/unit —
the iol_bridge command takes them positionally (the old restore sent a
3-arg command uBridge refused with 203).
"""
relay_nio = vm.manager.create_nio({"type": "nio_udp", "lport": 20000, "rhost": "127.0.0.1", "rport": 20001})
relay_nio.start_packet_capture("/tmp/capture.pcap", "DLT_EN10MB")
vm._ethernet_adapters[0].add_nio(0, relay_nio)
await vm._networking()
vm._ubridge_send.assert_any_call(f'iol_bridge start_capture {IOL_BRIDGE} 0 0 "/tmp/capture.pcap" EN10MB')
# ---------------------------------------------------------------------------
# Capture
# ---------------------------------------------------------------------------
@pytest.mark.asyncio
async def test_capture_on_a_kernel_link_uses_the_anchor(vm):
vm._kernel_taps[(0, 0)] = TAP00
nio = vm.manager.create_nio({"type": "nio_bridge", "bridge": BRIDGE})
vm._ethernet_adapters[0].add_nio(0, nio)
await vm.start_capture(0, 0, "/tmp/test.pcap")
vm._ubridge_send.assert_any_call(f'capture start_kernel {TAP00} "/tmp/test.pcap"')
await vm.stop_capture(0, 0)
vm._ubridge_send.assert_any_call("capture stop_kernel")
@pytest.mark.asyncio
async def test_capture_on_a_relay_link_uses_the_iol_port(vm):
nio = vm.manager.create_nio({"type": "nio_udp", "lport": 20000, "rhost": "127.0.0.1", "rport": 20001})
vm._ethernet_adapters[0].add_nio(0, nio)
await vm.start_capture(0, 0, "/tmp/test.pcap")
vm._ubridge_send.assert_any_call(f'iol_bridge start_capture {IOL_BRIDGE} 0 0 "/tmp/test.pcap" EN10MB')
await vm.stop_capture(0, 0)
vm._ubridge_send.assert_any_call(f"iol_bridge stop_capture {IOL_BRIDGE} 0 0")
# ---------------------------------------------------------------------------
# Markers (the polymorphic anchor: IOL location on relay, TAP on kernel)
# ---------------------------------------------------------------------------
@pytest.mark.asyncio
async def test_markers_on_a_kernel_link_attach_to_the_anchor(vm):
"""
The marker reconcile is datapath-agnostic: with the anchor as the
location, the attach/toggle/delete primitives translate to
marker *_kernel on the TAP.
"""
vm._kernel_taps[(0, 0)] = TAP00
nio = vm.manager.create_nio({"type": "nio_bridge", "bridge": BRIDGE})
nio.markers = {
"m1": {"bpf": "vlan 100", "link_id": "lk1", "enabled": True, "data_link_type": "DLT_EN10MB"},
}
vm._ethernet_adapters[0].add_nio(0, nio)
await vm._ubridge_apply_markers(TAP00, nio)
vm._ubridge_send.assert_any_call(
f'marker add_kernel m1 {TAP00} "vlan 100" link lk1 pcap "{vm.project.markers_working_directory()}/'
f'{vm.id}_lk1_m1.pcap"'
)
assert vm._marker_filter_bridges[("m1", "lk1")] == TAP00
await vm._ubridge_set_marker_filter_state("m1", False)
vm._ubridge_send.assert_any_call(f"marker enable_kernel {TAP00} m1 off")
await vm.delete_marker_capture("m1", "lk1", nio)
vm._ubridge_send.assert_any_call(f"marker delete_kernel {TAP00} m1")
@pytest.mark.asyncio
async def test_markers_on_a_relay_link_keep_the_iol_shape(vm):
"""
On the relay datapath the same reconcile talks iol_bridge, with the
bay/unit positionals — unchanged behaviour.
"""
nio = vm.manager.create_nio({"type": "nio_udp", "lport": 20000, "rhost": "127.0.0.1", "rport": 20001})
nio.markers = {
"m1": {"bpf": "vlan 100", "link_id": "lk1", "enabled": True, "data_link_type": "DLT_EN10MB"},
}
vm._ethernet_adapters[0].add_nio(0, nio)
location = f"{IOL_BRIDGE} 0 0"
await vm._ubridge_apply_markers(location, nio)
vm._ubridge_send.assert_any_call(
f'iol_bridge add_packet_filter {location} m1 mark "vlan 100" link lk1 pcap '
f'"{vm.project.markers_working_directory()}/{vm.id}_lk1_m1.pcap"'
)
assert vm._marker_filter_bridges[("m1", "lk1")] == location
await vm._ubridge_set_marker_filter_state("m1", False)
vm._ubridge_send.assert_any_call(f"iol_bridge enable_packet_filter {location} m1 off")
await vm.delete_marker_capture("m1", "lk1", nio)
vm._ubridge_send.assert_any_call(f"iol_bridge delete_packet_filter {location} m1")