mirror of
https://github.com/GNS3/gns3-server.git
synced 2026-09-08 19:15:26 +03:00
0ca9ccc637
IOL interfaces come in 4-port units (Ethernet0/0-3, Ethernet1/0-3, ...),
addressed like IOU as (adapter_number, port_number 0-3):
- IOLDockerVM builds EthernetAdapter(interfaces=4) per adapter and asks
the runner for adapters x 4 interfaces (num-eth).
- DockerVM threads port_number through the NIO/capture API (the compute
routes parsed it from the URL but dropped it); single-port adapters
keep the historical bridge{N} names and command sequence, multi-port
adapters get one bridge per port (bridge{a}_{p}).
- The unix-socket NIO wiring addresses sockets flat across adapters:
adapter x ports-per-adapter + port, so single-port images keep their
exact socket layout.
- The controller port list for GNS3_IOL_RUNNER docker nodes is generated
by StandardPortFactory with the IOU naming (Ethernet{segment0}/{port0},
segment size 4); plain docker nodes keep eth{N}.
217 lines
8.6 KiB
Python
217 lines
8.6 KiB
Python
#
|
||
# Copyright (C) 2025 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/>.
|
||
|
||
"""
|
||
IOL (IOS on Linux) Docker container subclass.
|
||
|
||
Supports IOL images packaged with Cisco CML's container runner
|
||
(``iol-runner``, ``virl.lab/cmd/iol-runner``), e.g. ``iol-xe/iol-xe:17-18-02``:
|
||
a scratch image whose ENTRYPOINT is ``iol-runner -config /config/iol-config.json
|
||
-stdio``. The runner generates the license, writes the NETMAP, manages NVRAM
|
||
and muxes the IOS console onto PID 1 stdio (works with the plain ``telnet``
|
||
console type; requires a TTY, which GNS3 always allocates).
|
||
|
||
Networking does not use the container's network namespace at all: the runner's
|
||
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``). Because the netio bus
|
||
directory is private to the node, the application IDs are fixed constants
|
||
with no cross-node collisions.
|
||
|
||
This class is selected by the ``GNS3_IOL_RUNNER=1`` environment marker.
|
||
"""
|
||
|
||
import contextlib
|
||
import glob
|
||
import json
|
||
import logging
|
||
import os
|
||
import shutil
|
||
|
||
from gns3server.compute.adapters.ethernet_adapter import EthernetAdapter
|
||
from gns3server.compute.docker.docker_error import DockerHttp404Error
|
||
from gns3server.compute.docker.docker_vm import DockerVM
|
||
from gns3server.compute.docker.vendor_docker_vm import VendorDockerVM
|
||
|
||
log = logging.getLogger(__name__)
|
||
|
||
|
||
class IOLDockerVM(VendorDockerVM):
|
||
"""
|
||
VendorDockerVM subclass for iol-runner images.
|
||
|
||
Extra opt-in knob (beyond the inherited vendor ones):
|
||
|
||
* ``GNS3_IOL_MEMORY=<MB>`` — IOL router memory passed via the generated
|
||
config (default 2048). The template ``memory`` field caps the whole
|
||
container: keep it at IOL memory + ~512 MB headroom or the kernel
|
||
OOM-killer will fire.
|
||
|
||
The marker itself forces ``GNS3_SKIP_INIT`` and the unix-socket NIO wiring,
|
||
and auto-adds the ``/config`` and ``/tmp/run`` persistent volumes, so a
|
||
template containing only ``GNS3_IOL_RUNNER=1`` is fully configured.
|
||
"""
|
||
|
||
_IOL_CONFIG_DIR = "/config"
|
||
_IOL_RUN_DIR = "/tmp/run"
|
||
|
||
def _parse_vendor_environment(self):
|
||
|
||
super()._parse_vendor_environment()
|
||
# The image has no shell (scratch): init.sh could neither run (its
|
||
# #!/bin/sh shebang doesn't exist) nor wait for eth interfaces that
|
||
# are never created. The console is IOS itself on PID 1 stdio.
|
||
self._gns3_init = False
|
||
self._unix_socket_nio = True
|
||
self._unix_socket_dir = "/tmp"
|
||
|
||
self._iol_memory = 2048
|
||
if self._environment:
|
||
for _line in self._environment.splitlines():
|
||
_line = _line.strip().rstrip(",")
|
||
if _line.startswith("GNS3_IOL_MEMORY="):
|
||
try:
|
||
memory = int(_line.split("=", 1)[1].strip())
|
||
if memory > 0:
|
||
self._iol_memory = memory
|
||
except ValueError:
|
||
pass
|
||
|
||
@DockerVM.adapters.setter
|
||
def adapters(self, adapters):
|
||
"""
|
||
Override: one IOL adapter is a 4-port unit — the IOU model. The
|
||
template's adapter count is the number of units (2 adapters =
|
||
Ethernet0/0-3 + Ethernet1/0-3); the generated config asks the runner
|
||
for adapters × 4 interfaces and links address ports as
|
||
(adapter_number, port_number 0-3).
|
||
"""
|
||
|
||
if len(self._ethernet_adapters) == adapters:
|
||
return
|
||
|
||
self._ethernet_adapters.clear()
|
||
for _ in range(0, adapters):
|
||
self._ethernet_adapters.append(EthernetAdapter(interfaces=4))
|
||
|
||
log.debug(
|
||
"IOL container '%s': number of 4-port Ethernet adapters set to %d",
|
||
self._name, adapters,
|
||
)
|
||
|
||
def _persistent_volume_list(self, image_info, include_network_config=True):
|
||
"""
|
||
Override: the runner requires ``/config`` (its config file, generated
|
||
below) and ``/tmp/run`` (its working directory: startup-config and
|
||
NVRAM live there — NETMAP and the netiomux sockets are ephemeral and
|
||
stay in the container's own /tmp). Auto-add both so a minimal
|
||
template cannot be misconfigured.
|
||
"""
|
||
|
||
volumes = super()._persistent_volume_list(image_info, include_network_config)
|
||
for needed in (self._IOL_CONFIG_DIR, self._IOL_RUN_DIR):
|
||
if not any(needed == v or needed.startswith(v.rstrip("/") + "/") for v in volumes):
|
||
volumes.append(needed)
|
||
return volumes
|
||
|
||
async def start(self):
|
||
|
||
await self._prepare_iol_runtime()
|
||
await super().start()
|
||
|
||
async def restart(self):
|
||
"""
|
||
Override: the base restart is a bare ``docker restart`` — the runner
|
||
would read a stale config (no adapter-count/memory refresh) and
|
||
uBridge would keep wiring to the previous run's sockets. Stop
|
||
gracefully (SIGTERM lets the runner flush NVRAM) and start again.
|
||
"""
|
||
|
||
await self.stop(graceful=True)
|
||
await self.start()
|
||
|
||
async def _prepare_iol_runtime(self):
|
||
"""
|
||
Regenerate the node's runtime files before the container starts:
|
||
|
||
* ``<working_dir>/tmp/run/`` must exist or the IOL process dies at
|
||
boot (the runner writes NETMAP there but does not create it).
|
||
* ``<working_dir>/config/iol-config.json`` is rewritten on every
|
||
start so adapter-count and memory changes take effect.
|
||
* Sockets and netio bus directories left in the wiring directory by a
|
||
previous (possibly SIGKILLed) run are removed — the runner rebinds
|
||
them on boot and would fail on a stale file.
|
||
|
||
``tmp/run`` (startup-config, NVRAM) is never touched. Neither is
|
||
anything while the container is already running (idempotent start of
|
||
a live node: the sockets belong to the running runner).
|
||
"""
|
||
|
||
try:
|
||
state = await self._get_container_state()
|
||
except DockerHttp404Error:
|
||
state = "stopped"
|
||
|
||
os.makedirs(os.path.join(self.working_dir, "tmp", "run"), exist_ok=True)
|
||
self._write_iol_config()
|
||
|
||
if state == "running":
|
||
return
|
||
|
||
wiring_dir = self._unix_socket_wiring_dir()
|
||
for pattern in ("s??.sock", "c??.sock"):
|
||
for stale in glob.glob(os.path.join(wiring_dir, pattern)):
|
||
with contextlib.suppress(OSError):
|
||
os.unlink(stale)
|
||
for netio_dir in glob.glob(os.path.join(wiring_dir, "netio*")):
|
||
shutil.rmtree(netio_dir, ignore_errors=True)
|
||
|
||
def _write_iol_config(self):
|
||
"""
|
||
Write the runner's config file on the host side of the /config volume.
|
||
The runner drops to user-id/group-id after its setup, so everything it
|
||
creates is owned by the server user — which is also what lets the
|
||
(unprivileged) uBridge write into the node's socket directory.
|
||
"""
|
||
|
||
config = {
|
||
"binary": "/binary.iol",
|
||
"memory": self._iol_memory,
|
||
"num-eth": self.adapters * 4, # every adapter is a 4-port unit
|
||
"num-serial": 0, # GNS3 docker adapters are ethernet-only
|
||
"local-app": 1,
|
||
"remote-app": 2,
|
||
"user-id": os.getuid(),
|
||
"group-id": os.getgid(),
|
||
}
|
||
config_file = os.path.join(self.working_dir, "config", "iol-config.json")
|
||
os.makedirs(os.path.dirname(config_file), exist_ok=True)
|
||
with open(config_file, "w", encoding="utf-8") as f:
|
||
json.dump(config, f, indent=2)
|
||
f.write("\n")
|
||
log.debug("Wrote iol-runner config for '%s': %s", self._name, config)
|
||
|
||
async def _fix_permissions(self):
|
||
"""
|
||
Override: no-op. The generated config maps the runner to the server's
|
||
uid/gid, so no root-owned files ever appear in the volumes, and this
|
||
image has no shell for the container-side busybox pass anyway.
|
||
"""
|
||
|
||
self._permissions_fixed = True
|