7a9a514ea3
A correctness read-through of the five delivered datapath documents, plus
the two code comments that carried the same stale vocabulary.
Datapath selection: the VendorDockerVM selector is `console_type=docker_exec`
alone (`GNS3_SKIP_INIT` and friends are behavior knobs of the chosen class);
the cross-compute and anchor-less fallbacks are named for what they are; the
Ethernet-switch endpoint is the documented exception to the anchoring rule,
and the IOL runner container is called out as the Docker node that does not
anchor on a veth.
Filter vocabulary: the stateful eBPF program evaluates four modes
(nth → quota → window → flow), GNS3 exposes three of them, and window_drop
joins the kernel-only list; the correl suffixes gate on the `rate` token as
the extension-build marker.
group_fwd_mask: the 0xfffd port mask is applied inside uBridge's `brctl addif`
itself, not as a separate command — the link-creation sequences and the
operation tables no longer show an arrow the server never sends. Same class
of fix for `link set up` on the IOL anchor (addif already brought it up; the
command only pushes a suspended anchor back down) and for the QEMU carrier
replication (QMP `set_link`, gated by `replicate_network_connection_state`).
Lifecycles and stop orders re-worded around the invariant rather than the
node type: the fd holder must release before the devices are deleted, which
is QEMU's process-first order, IOU's uBridge-first order and Dynamips'
hypervisor-NIO-first order. Deferred wiring for a stopped endpoint is
documented as the common path it is, and the Dynamips "stop is not a close"
note now says what recovery from a dead hypervisor actually requires.
Dynamips specifics: a c7200 needs an adapter in slot 1 (slot 0 is the fixed
I/O slot), the tap-fd direction is stated correctly (writes inject into the
kernel, reads return what the kernel transmits), and the anchor registry is
name-keyed against the controller's port matrix by convention, not derivation.
IOL port bridge naming: `bridge{bay}` on unit 0, `bridge{bay}_{unit}`
elsewhere; the leg swap happens on link delete/re-create or a datapath
switch, while suspend is an in-place NIO update and a project reopen is a
fresh build.
Verified and Roadmap sections: the in-repo e2e suite is distinguished from
the isolated-instance development harness (IOU), assertions are stated with
their bounds and capability gates, and the roadmap entries collapse into the
one remaining project — VXLAN/GENEVE for cross-compute links.
Code comments: `flow` added to the documented mode order in the eBPF apply
path, and the `nio_bridge` module docstring corrected on which filter types
run on the kernel datapath (bpf via cls_bpf, frequency_drop/quota/window_drop
via the eBPF classifier — neither is relay-only any more).
This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.
GNS3 Server Documentation
License
This documentation is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0).
⚠️ Important - ShareAlike Requirement: If you create derivative works based on this documentation (including software that incorporates substantial portions of the documentation), your work must also be licensed under CC BY-SA 4.0 or a compatible license (such as GPLv3).
- 📄 Full License Text: See docs/LICENSE
- 🔗 License URL: https://creativecommons.org/licenses/by-sa/4.0/
- 📖 Compatibility: https://creativecommons.org/compatiblelicenses
Dual License Structure:
- 📚 Documentation: CC BY-SA 4.0 (this directory)
- 💻 Software Code: GPLv3 (see root LICENSE)
Technical documentation for the GNS3 server project, covering features, AI Copilot, development setup, and known issues.
Directory Structure
docs/
├── README.md # This file
├── development-setup.md # Ubuntu 24.04 development environment setup
├── openapi.json # OpenAPI specification
├── features/ # Feature documentation
│ ├── compute-controller-setup.md # Controller + Compute architecture & configuration
│ ├── statistics-api.md # Aggregated statistics API for monitoring
│ ├── vnc-websocket-console.md # Browser-based VNC console via WebSocket
│ └── web-wireshark-business-process.md # Web Wireshark (Docker + xpra packet capture)
├── design/ # Design proposals & roadmaps (not yet implemented)
│ └── docker-image-type.md # Docker image types: vendor profile discriminator + registry
├── gns3-copilot/ # AI Copilot feature documentation
│ ├── netmiko_devices.md # Netmiko supported devices (366 types)
│ ├── template-based-configuration-roadmap.md # Future: template-based config with HITL
│ └── implemented/ # Implemented features
│ ├── chat-api.md # Chat API (SSE, session management)
│ ├── llm-model-configs.md # LLM model configuration system
│ ├── command-security.md # Command security and filtering
│ ├── context-window-management.md # Context window optimization
│ ├── node-control-tools.md # Node start/stop/suspend tools
│ └── multi-vendor-device-support.md # Multi-vendor device support
└── bugs/ # Known issues & bug reports
└── telnet-server-connection-race-condition.md
Features
Image inventory synchronization
Image Manager's Sync Images action reconciles the catalog with the configured
image directories. Automatic synchronization uses filesystem events and periodic
scans (auto_discover_images, image_sync_interval, default 900 seconds).
New and changed images are checksummed; missing records retain their IDs and
template associations and become available again when restored at the same path.
The /v3/images/sync API supports dry-run and forced checksum verification.
Database migration d9e8a2b7c401 is required when upgrading an existing catalog.
Atomic image publication requires filesystem hard-link support.
Controller + Compute Setup (features/compute-controller-setup.md)
Architecture and minimum configuration for setting up GNS3 Controller with remote Compute nodes. Covers compute node config, controller registration, and multi-compute deployment.
Statistics API (features/statistics-api.md)
Aggregated server statistics API (GET /v3/statistics) for monitoring dashboards. Collects compute resources, project/node/link counts, and Web Wireshark container status in a single request.
VNC WebSocket Console (features/vnc-websocket-console.md)
Browser-based VNC console access via WebSocket. The Controller acts as WebSocket-to-WebSocket relay, and Compute bridges WebSocket to TCP for QEMU/Docker VMs. Supports noVNC clients.
API Error Responses (features/api-error-responses.md)
Unified error response format across all GNS3 API endpoints. Documents HTTP status codes, error types, and client-side error handling patterns.
Web Wireshark (features/web-wireshark-business-process.md)
Web-based packet capture analysis using Docker + xpra HTML5 client. Zero-install Wireshark experience directly in the browser, integrated with GNS3 topologies.
Marker (Traffic Insight) (features/marker-traffic-insight.md)
Real-time traffic insight via per-link BPF markers and project-level inherited definitions. A marker taps a link in uBridge, emitting match notifications and pcap capture on BPF hit; definitions fan out to every capable link automatically.
Marker Tag Replay (features/marker-tag-replay.md)
Aggregate playback across links keyed by tag: once every marker under a tag is paused, their pcaps merge into one timestamp-ordered timeline; frames are decoded on demand via tshark into an isomorphic JSON protocol tree. The cross-link delta of the same packet measures the intermediate node's forwarding latency.
Docker exec Console (Vendor NOS) (features/docker-exec-console.md)
Console for vendor NOS containers (SR Linux, XRd, …) whose CLI is a TUI off PID 1: runs the vendor CLI via the Docker exec API, plus GNS3_SKIP_INIT/GNS3_INTERFACE_NAMES boot knobs and SKIP_INIT volume persistence.
Cisco XRd Control Plane (features/vendor-nos-xrd.md)
Cisco XRd as a GNS3 Docker router: vendor path + shm/device injection (GNS3_SHM_SIZE/GNS3_DEVICES), config-file injection (extra_configs), udev masking (GNS3_MASK_UDEV) so privileged systemd containers don't disturb the host, and the host-readiness check.
IOL Images with iol-runner (features/iol-runner-docker.md)
Cisco CML containerized IOL (e.g. iol-xe/iol-xe:17-18-02) as GNS3 Docker routers: generic unix-socket NIO (GNS3_UNIX_SOCKET_NIO — adapters wired via AF_UNIX datagram socket pairs instead of TAP/netns) plus IOLDockerVM (GNS3_IOL_RUNNER=1 — per-start config generation, /tmp/run preparation, stale-socket cleanup, console on PID 1 stdio).
Design & Roadmaps (design/)
Docker Image Types (design/docker-image-type.md)
Proposed image_type discriminator on Docker templates plus a compute-side profile registry: vendor parameters graduate from environment markers into schema-gated fields, generic-feature applicability becomes declared capability data, and the existing markers remain as a compatibility fallback. Not a new node type — vendor images are content, not mechanism.
GNS3 AI Copilot (gns3-copilot/)
Implemented Features
| Feature | Description | Status |
|---|---|---|
| Chat API | SSE streaming, session management, token statistics | Implemented |
| LLM Model Configs | Multi-level model config (system/group/user) | Implemented |
| Command Security | Command filtering, dangerous operation detection, HITL | Implemented |
| Context Window Management | Token optimization, content filtering, compression | Implemented |
| Node Control Tools | Start/stop/suspend with batch ops and progress tracking | Implemented |
| Multi-Vendor Support | Cisco, Huawei, Ruijie, VPCS with custom Netmiko drivers | Implemented |
Reference
- Netmiko Supported Devices — 366 device types (154 SSH, 55 Telnet, 3 custom GNS3 drivers)
Roadmap
- Template-Based Configuration with HITL — Jinja2 templates with human-in-the-loop confirmations for device configuration and node creation
Known Issues (bugs/)
- Telnet Server Connection Race Condition —
getpeername()error when client disconnects during connection setup (High severity, Open) - Docker Link UDP Self-Loop — intermittent one-way link (both ends handed the same UDP port by an allocation race); fixed (Medium severity)
Development Setup (development-setup.md)
Quick-start guide for Ubuntu 24.04: install via PPA, set up dependencies, and run gns3-server from source.
Related Documentation
- GNS3 Server API Documentation — Interactive API docs (also available locally via
redoc.html) - GNS3 Web UI Documentation
- LangGraph Documentation
Last updated: 2026-09-01