feat: allocate IOL Docker application IDs from a pool disjoint from IOU

IOL interface MACs derive from the application ID (aabb.cc{app}{iface}),
so ids must be unique across opened projects sharing computes — the same
reason IOU has its allocator. IOL Docker nodes draw from the upper half
(512-1022, netiomux's fixed peer is 1023) so the two node types can
neither collide nor starve each other; IOU behavior is unchanged.

The controller sniffs the same GNS3_IOL_RUNNER environment marker the
compute uses to select IOLDockerVM (both the nested-properties and
template/top-level-kwarg shapes), stores the id in node properties like
IOU does, and passes it through the Docker create payload. Without an
allocation the compute falls back to a stable node-derived id in the
same upper range.

gns3server/compute/docker/iol_docker_vm.py

@@ -29,8 +29,10 @@ netiomux exposes per-interface AF_UNIX datagram sockets in the container's
 ``/tmp`` (``s%02d.sock`` receive, ``c%02d.sock`` send — raw Ethernet frames),
 wired by the generic ``GNS3_UNIX_SOCKET_NIO`` capability of VendorDockerVM
 (uBridge reaches them through a per-node runtime directory bound at /tmp —
-see ``VendorDockerVM._unix_socket_host_dir``). The local application ID is
-derived from the node ID so that linked nodes get distinct MACs.
+see ``VendorDockerVM._unix_socket_host_dir``). The controller allocates the
+IOL application ID (upper half of the id space, disjoint from IOU's) so that
+linked nodes get distinct MACs; without an allocation a stable node-derived
+fallback is used.
 
 This class is selected by the ``GNS3_IOL_RUNNER=1`` environment marker.
 """
@@ -91,6 +93,27 @@ class IOLDockerVM(VendorDockerVM):
                     except ValueError:
                         pass
 
+        # Application ID allocated by the controller (upper half of the id
+        # space, disjoint from IOU's); None until the create payload carries it.
+        self._application_id = None
+
+    @property
+    def application_id(self) -> int:
+        """
+        IOL application ID: drives interface MACs (aabb.cc{app}{iface}) and
+        the NVRAM file name. Falls back to a stable per-node value in the
+        IOL Docker half of the id space when no allocation is available
+        (raw compute API use, topologies created before allocation existed).
+        """
+
+        if self._application_id is None:
+            return 512 + int(self.id.replace("-", ""), 16) % 511
+        return self._application_id
+
+    @application_id.setter
+    def application_id(self, value) -> None:
+        self._application_id = int(value)
+
     @DockerVM.adapters.setter
     def adapters(self, adapters):
         """
@@ -194,11 +217,12 @@ class IOLDockerVM(VendorDockerVM):
             "num-eth": self.adapters * 4,  # every adapter is a 4-port unit
             "num-serial": 0,  # GNS3 docker adapters are ethernet-only
             # IOL derives interface MACs from the local application ID
-            # (aabb.cc00.0<app><iface>0); every node needs a distinct one or
-            # linked routers share MACs and drop each other's frames as loops.
-            # Derived from the node ID: stable across restarts, unique enough
-            # (CML allocates per-lab sequential IDs for the same reason).
-            "local-app": int(self.id.replace("-", ""), 16) % 1022 + 1,
+            # (aabb.cc{app}{iface}); every node needs a distinct one or
+            # linked routers share MACs and drop each other's frames as
+            # loops. Allocated by the controller per node (upper half of
+            # the id space, disjoint from IOU's — CML does the same with
+            # its per-deployment iol_app_id).
+            "local-app": self.application_id,
             "remote-app": 1023,  # netiomux's fake peer application ID
             "user-id": os.getuid(),
             "group-id": os.getgid(),

gns3server/controller/node.py

@@ -30,6 +30,7 @@ from .controller_error import (
 from .node_types import BUILTIN_NODE_TYPES
 from .ports.port_factory import PortFactory, StandardPortFactory, DynamipsPortFactory
 from ..utils.images import images_directories
+from ..utils.application_id import is_iol_runner_environment
 from ..utils import macaddress_to_int, int_to_macaddress
 from ..config import Config
 
@@ -804,7 +805,7 @@ class Node:
             self._ports = DynamipsPortFactory(self._properties)
             return
         elif self._node_type == "docker":
-            if "GNS3_IOL_RUNNER=" in (self._properties.get("environment") or ""):
+            if is_iol_runner_environment(self._properties.get("environment")):
                 # IOL adapters are 4-port units (the IOU model): ports are
                 # Ethernet0/0-3, Ethernet1/0-3, … addressed as
                 # (adapter_number, port_number 0-3).

gns3server/controller/project.py

@@ -40,7 +40,7 @@ from .udp_link import UDPLink
 from .link import _UNSET
 from ..config import Config
 from ..utils.path import check_path_allowed, get_default_project_directory
-from ..utils.application_id import get_next_application_id
+from ..utils.application_id import get_next_application_id, is_iol_runner_environment
 from ..utils.asyncio.pool import Pool
 from ..utils.packet_filter_validation import validate_bpf_syntax
 from ..utils.asyncio import locking
@@ -69,6 +69,21 @@ def open_required(func):
     return wrapper
 
 
+def _is_iol_docker_kwargs(kwargs) -> bool:
+    """
+    Whether add_node() kwargs describe an iol-runner Docker node. The
+    environment can arrive nested in a ``properties`` dict or as a top-level
+    kwarg (the template path spreads it), matching the two shapes IOU
+    application-id injection handles.
+    """
+
+    if "properties" in kwargs.keys():
+        environment = (kwargs.get("properties") or {}).get("environment")
+    else:
+        environment = kwargs.get("environment")
+    return is_iol_runner_environment(environment)
+
+
 class Project:
     """
     A project inside a controller
@@ -159,7 +174,7 @@ class Project:
             assert self._status != "closed"
             self.dump()
 
-        self._iou_id_lock = asyncio.Lock()
+        self._application_id_lock = asyncio.Lock()
         # Serialise the "ensure project exists on this compute" check in
         # _create_node: without it, concurrent node creations all pass the
         # `compute not in _project_created_on_compute` check before any has
@@ -646,7 +661,7 @@ class Project:
             self._computes.append(compute.id)
 
         if node_type == "iou":
-            async with self._iou_id_lock:
+            async with self._application_id_lock:
                 # IOU application IDs must be allocated serially to avoid duplicates.
                 # The lock must also cover _create_node() because get_next_application_id()
                 # checks in-memory nodes (self._nodes), which are only registered
@@ -658,6 +673,23 @@ class Project:
                 elif "application_id" not in kwargs.keys() and not kwargs.get("properties"):
                     kwargs["application_id"] = get_next_application_id(self._controller.projects, self._computes)
                 node = await self._create_node(compute, name, node_id, node_type, **kwargs)
+        elif node_type == "docker" and _is_iol_docker_kwargs(kwargs):
+            # IOL Docker nodes derive interface MACs from the application ID
+            # exactly like IOU; they draw from the disjoint upper half of the
+            # id space so the two node types can neither collide nor starve
+            # each other.
+            async with self._application_id_lock:
+                if "properties" in kwargs.keys():
+                    properties = kwargs.get("properties") or {}
+                    if "application_id" not in properties:
+                        properties["application_id"] = get_next_application_id(
+                            self._controller.projects, self._computes, iol_docker=True
+                        )
+                elif "application_id" not in kwargs.keys():
+                    kwargs["application_id"] = get_next_application_id(
+                        self._controller.projects, self._computes, iol_docker=True
+                    )
+                node = await self._create_node(compute, name, node_id, node_type, **kwargs)
         else:
             node = await self._create_node(compute, name, node_id, node_type, **kwargs)
         self.emit_notification("node.created", node.asdict())

gns3server/schemas/compute/docker_nodes.py

@@ -69,7 +69,9 @@ class DockerCreate(DockerBase):
     Properties to create a Docker node.
     """
 
-    pass
+    application_id: Optional[int] = Field(
+        None, ge=1, le=1022, description="IOL application ID for iol-runner images (allocated by the controller)"
+    )
 
 
 class DockerUpdate(DockerBase):

gns3server/utils/application_id.py

@@ -13,6 +13,7 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
 
 from gns3server.controller.controller_error import ControllerError
 
@@ -20,13 +21,32 @@ import logging
 
 log = logging.getLogger(__name__)
 
+# IOU draws from the lower half: uBridge's iol_bridge uses application_id + 512
+# for its netio peer endpoint. IOL Docker nodes (iol-runner images) draw from
+# the upper half: their netiomux peer is the fixed id 1023. Both node types
+# derive interface MACs from the id (aabb.cc{app}{iface}), so the two pools
+# must stay disjoint — a shared id silently blackholes traffic between the
+# nodes as a MAC loop.
+IOU_APPLICATION_ID_POOL = range(1, 512)
+IOL_DOCKER_APPLICATION_ID_POOL = range(512, 1023)
 
-def get_next_application_id(projects, computes):
+
+def is_iol_runner_environment(environment) -> bool:
+    """
+    Whether a Docker node environment carries the GNS3_IOL_RUNNER marker —
+    the same signal the compute uses to select the IOLDockerVM class.
+    """
+
+    return "GNS3_IOL_RUNNER=" in (environment or "")
+
+
+def get_next_application_id(projects, computes, iol_docker=False):
     """
     Calculates free application_id from given nodes
 
     :param projects: all projects managed by controller
     :param computes: all computes used by the project
+    :param iol_docker: allocate for an IOL Docker (iol-runner) node instead of IOU
     :raises HTTPConflict when exceeds number
     :return: integer first free id
     """
@@ -38,12 +58,26 @@ def get_next_application_id(projects, computes):
         if project.status == "opened":
             nodes.extend(list(project.nodes.values()))
 
-    used = {n.properties["application_id"] for n in nodes if n.node_type == "iou" and n.compute.id in computes}
-    pool = set(range(1, 512))
+    if iol_docker:
+        used = {
+            n.properties["application_id"]
+            for n in nodes
+            if n.node_type == "docker"
+            and n.compute.id in computes
+            and "application_id" in n.properties
+            and is_iol_runner_environment(n.properties.get("environment"))
+        }
+        pool = set(IOL_DOCKER_APPLICATION_ID_POOL)
+        limit = "511 IOL Docker nodes"
+    else:
+        used = {n.properties["application_id"] for n in nodes if n.node_type == "iou" and n.compute.id in computes}
+        pool = set(IOU_APPLICATION_ID_POOL)
+        limit = "512 nodes"
     try:
         application_id = (pool - used).pop()
         return application_id
     except KeyError:
         raise ControllerError(
-            "Cannot create a new IOU node (limit of 512 nodes across all opened projects using the same computes)"
+            f"Cannot create a new {'IOL Docker' if iol_docker else 'IOU'} node "
+            f"(limit of {limit} across all opened projects using the same computes)"
         )