0c4ec8c38c
Consume the eBPF impairment classifier delivered in uBridge feature/tc-precision: frequency_drop becomes the exact every-Nth mode (tc nth_drop; -1 = drop everything maps to every 1st) and the new kernel-only quota type is the byte-cap mode (tc quota_drop, 100 = hard cutoff). KERNEL_UNSUPPORTED_FILTERS is gone entirely — kernel/relay eligibility is now purely topological. Both modes gate on ebpf=1 from the per-process tc capabilities probe (error names the setcap fix); the cleanup path (modes off) only talks to the eBPF commands when the probe reported them. Reconcile is a plain re-set: the netem reset-before-set already detaches the program and clears uBridge's per-interface registry, so a mode set after it is a fresh load+attach. Documented semantic difference: the relay counts both directions through one bridge counter, the kernel counts per direction — N=3 round-trip loss is 1-(2/3)^2 = 55.6% on kernel vs ~1/N on relay (measured 57%). window_drop is NOT exposed: the delivered implementation advances the window with no gap, making 'outside the window packets pass' unreachable (needs outage/period fields — recorded in the spec); flow_drop awaits a parameter-shape decision. Also fixes a pre-existing restart bug the e2e exposed: _bridges (relay bridge names) was never cleared on stop, so restarting a node with a relay link skipped 'bridge create' and failed on add_nio_udp. e2e (isolated instance): 13/13 — pref-1 tc_impair classifier on both veths, 57% round-trip for N=3, -1 = exact 100%, quota hard cutoff, delay coexistence, clean teardown, suspend/resume, node restart, relay-leg frequency_drop regression through an Ethernet switch. Full suite: 1925 passed.
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