316e7002c1
uBridge's window mode gained the semantics the B.2 spec asked for — `tc window_drop <if> <start> <outage> <pct> [<period> [<jitter>]]`: a single outage that traffic passes before *and* after, recurring flaps with period >= outage, and a per-cycle jitter — so the kernel-only `window_drop` filter type is now exposed: - validation mirrors the tc grammar (3-5 params, ranges, period >= outage, jitter cap) and adds window_drop to KERNEL_ONLY_FILTERS; filter_inactive_filters keeps start=0 — unlike every other filter a zero first parameter means "the outage starts now", not "disabled". - `_ubridge_apply_ebpf_drops` sends `tc window_drop` (positional pass-through) and turns the mode off explicitly when absent, under the same ebpf=1 gate. - FILTERS entry (Start/Outage/Chance/Period/Jitter) + available_filters. The schedule is relative to the apply: reconcile re-sets the classifier on every apply, so any filter change, node restart or link reset restarts the window. Verified on a two-container kernel link, 15/15: a single outage [1000, 1500, 100] arrives per-seq as [0..4, 13..19] (passing before the window, dropped inside, passing after); recurring 1000/2000 ms = 52 % round trip (duty cycle); period == outage = permanent outage; period < outage = 409 before uBridge; jittered flap keeps the ~50 % duty cycle; 30 % chance on a permanent window = 53 % round trip against the per-direction theory 1-0.7^2 = 51 %; coexist with netem; node restart restores; available_filters kernel vs relay (409 + hidden); teardown clean. P6b re-run as a regression on the same uBridge build: 13/13. Worth recording for the next rebuild: the first delivered window program loaded as root but reported ebpf=0 through gns3-server — the verifier's non-root path loses the loop counter's bound, treats the catch-up loop as unbounded and rejects the *whole* program (E2BIG, 8193 pending states), which also took frequency_drop and quota down, with ebpf=0 as the only symptom. Smaller trip caps did not help; the loop had to go (uBridge 572ca0c), on top of a Makefile header-dependency fix (53e34bb) that had been shipping a stale program object.
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