89d7f866cb
The SKIP_INIT volume bridge replicated init.sh's seed + mount --bind script via docker exec *after* the container started. That copied the mechanism but not the invariant that makes init.sh safe — the entrypoint position, which guarantees the volume is in place before the application runs. The exec runs concurrently with the NOS boot, so whether the NOS loaded its persisted config or the overlay's factory copy was a timing race: - single node stop/start on an idle system won it (exec ~1s, SR Linux reads its startup config at ~2-4s) — the save/stop/start round-trip passed; - a server restart + project reload lost it (concurrent node starts queue on the Docker API, delaying the exec by seconds) — SR Linux booted factory while the persisted config.json sat intact on the host; - XRd was immune (systemd boots tens of seconds before XR touches /xr-storage), which is why the race was never observed on it. Replace the bridge entirely: - new DockerVM._prepare_volumes hook (no-op in the base class) runs in create() after the image is present, before the container is created; VendorDockerVM overrides it to seed each volume's host directory from the image (throwaway docker create container + docker cp -a, nothing executes). The .gns3_perms marker gates the seeding: a volume that ever started is never re-seeded, so saved configuration is never overwritten with factory content (also the upgrade path for existing nodes). - VendorDockerVM._mount_binds now binds the volumes directly at their real in-container paths (/etc/opt/srlinux) instead of /gns3volumes aliases, so the persisted config is visible to the NOS from the very first process. - _setup_skip_init_volumes and its start() call are gone; the container-side _fix_permissions targets the volume paths directly (the direct binds exist for the whole container lifetime, unlike the old bridge). The volume-list computation (validation + overlap de-duplication) moves into DockerVM._persistent_volume_list so create-time seeding and _mount_binds cannot drift apart.
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)
├── 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
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.
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.
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-08-14