d4b57d49fb
Surface the netem extensions delivered in uBridge feature/tc-netem-ext as GNS3 filter types: rate (tc-style bandwidth string), reorder (needs delay), gemodel (Gilbert-Elliot bursty loss, exclusive with packet_loss), duplicate, seed and limit, plus the delay jitter distribution and the loss/dup correlation parameters. All are kernel-datapath only — the relay's packet-filter registry has no equivalent, so available_filters hides them on relay links, setting one on a created relay link returns 409, and the project-load path drops them with a warning (update_filters runs before the datapath is decided, so it cannot reject there). Validation mirrors the tc grammar: reorder requires delay, gemodel and packet_loss are mutually exclusive, a distribution requires jitter > 0, rate is integer+unit capped at 100gbit. The translation in DockerVM._netem_command_parts emits the frozen grammar order and gates extension keywords on the 'tc capabilities' netem token list (probed once per uBridge process; a plain delay/loss/corrupt/dup filter never probes, keeping old uBridge builds untouched; the correl suffix has no token and gates on 'rate' as the extension-build marker). Reconcile became reset-before-set: the kernel's netem change merges optional attributes (rate, correlation, reorder, corrupt, gemodel, distribution, seed keep their previous value when the new message omits them), so removing a parameter needs an explicit 'tc reset' — the bpf_drop filters are re-added right after in the same flow, so the clsact churn is invisible. The capability check runs before the reset so a failed update leaves the previous qdisc in place. e2e (isolated instance, kernel link): 24/24 — rate 512kbit adds exactly 2x the per-packet serialization to the RTT (45.5 ms for 1400-byte pings), paretonormal jitter + rate-cleared leak check, reorder gap 5, gemodel 50% bursty loss, duplicate, loss 30% correl 50%, seed 42 + limit 5000 visible in the qdisc dump, suspend/resume and node restart keep the filters, relay link rejects rate with 409, teardown leaves no netem. Full unit suite: 1916 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