90bcb32473
Switch-to-switch links were the last shape left on the relay: the switch fast path works by absorbing the *peer's* anchor, and a switch has none — its ports are its own bridge, and a kernel interface belongs to exactly one bridge, so two bridges cannot be joined by enslaving anything. Join them with a veth pair instead: one end per bridge, each side enslaving its own end and applying its own port mode to it — an access port on one side and a trunk on the other behaves like the real cable it models. uBridge's docker create_veth/delete_veth (the primitive every Docker adapter is already born from) creates and destroys the pair; the names derive from the link id (utils.kernel_anchor.kernel_cascade_names), so each side computes its own end and the names survive a restart. The pair belongs to the link, and the two ends are wired by two independent uBridge processes — the project-open batch drives different nodes concurrently — so the protocol is order-free: both sides create the pair when their own end is missing (one create wins; the loser's failure is re-checked against the kernel and "the pair is there" is not an error), and either side's teardown destroys it (deleting one veth end takes the other with it, so both converge on the same gone pair and the second delif answers ENOENT). A pre-existing end — this switch restarted, or a leftover from a previous life of the link id — is reused rather than recreated, because the other end may still be a live port of the peer switch; a stale tc qdisc is all a reused end can carry. No new wire format was needed: a cascade is an anchor NIO on both ends, the absorbed-anchor case plus the peer end's name. That also corrects the filter routing — the single-sided rule exists because an absorbed anchor is one interface, while a cascade has one per switch, so impairments go to both ends like any other kernel link. Tests: the wire format, the eligibility flip and the both-ends re-push on node start (controller); the naming contract (utils); the switch-side lifecycle — create, reuse, lost create race, delete destroys the pair (compute routes). Drive-by: the relay filter test's compute mock carried no awaitable `put`, so tests/controller/test_kernel_datapath_link.py failed when run alone while an argument-less full run passed; callers now get one.
GNS3 server repository
The GNS3 server manages emulators and other virtualization software such as Dynamips, Qemu/KVM, Docker, VPCS, VirtualBox and VMware Workstation. Clients like the GNS3 GUI and the GNS3 Web UI control the server using a HTTP REST API.
Installation
These instructions are for using GNS3, please see below for development.
Windows & macOS
Please use our Windows installer or DMG package to install the stable build along with the GNS3 VM. Note that as of GNS3 version above 3.0, you must run the server using the GNS3 VM or on a Linux system (remote, cloud or virtual machine).
Linux
Ubuntu based distributions
We build and test packages for actively supported Ubuntu versions. Other distros based on Ubuntu, like Mint, should also be supported.
Packages can be installed from our Personal Package Archives (PPA) repository:
sudo apt update
sudo apt install software-properties-common
sudo add-apt-repository ppa:gns3/ppa
sudo apt update
sudo apt install gns3-gui gns3-server
Other Linux distributions
GNS3 is often packaged for other distributions by third-parties:
PyPi
You may use PyPi in case no package is provided, or you would like to do a manual installation:
python3 -m pip install gns3-gui
python3 -m pip install gns3-server
Optional Features
GNS3 server supports optional features that can be installed as needed:
AI Features (Optional — includes AI Copilot and MCP):
python3 -m pip install gns3-server[ai-features]
AI-powered assistant for network topology design, automation, and MCP protocol support for AI agent integration.
Development (For contributors):
python3 -m pip install gns3-server[dev]
Web Wireshark (Optional):
pip install gns3-server && gns3server-web-wireshark-setup
Browser-based packet capture analysis using Wireshark in a Docker container.
Combination Installation: You can install multiple optional features together:
python3 -m pip install gns3-server[ai-features,dev]
Why optional?
- Reduces installation size for users who don't need specific features
- Supports restricted environments (government, education, corporate) where certain libraries may not be allowed
- Faster installation for basic GNS3 usage
- Allows users to choose only the features they need
Note: If you install without optional extras, the server will work normally but optional features will be disabled. You can add features later by running the appropriate install command.
Uninstalling AI Features:
To remove AI Features dependencies (AI Copilot + MCP):
gns3server-uninstall-ai-features
This will remove all AI Copilot and MCP dependencies while keeping the core functionality intact. The server will continue to work, but AI features will be disabled.
Please see our documentation for more details.
Software dependencies
In addition to Python dependencies, other software may be required, recommended or optional.
- uBridge is required, it interconnects the nodes.
- Dynamips is required for running IOS routers (using real IOS images) as well as the internal switches and hubs.
- VPCS is recommended, it is a builtin node simulating a very simple computer to perform connectivity tests using ping, traceroute etc.
- Qemu is strongly recommended as most node types are based on Qemu, for example Cisco IOSv and Arista vEOS.
- libvirt is recommended as it's needed for the NAT cloud.
- Docker is optional, some nodes are based on Docker.
- mtools is recommended to support data transfer to/from QEMU VMs using virtual disks.
- i386-libraries of libc and libcrypto are optional, they are only needed to run IOU based nodes.
Note that Docker needs the script program (bsdutils or util-linux package), when running a Docker VM and a static busybox during installation (python3 setup.py install / pip3 install / package creation).
Development
Setting up
These commands will install the server with core Python dependencies:
git clone https://github.com/GNS3/gns3-server
cd gns3-server
git checkout 3.1
python3 -m venv venv-gns3server
source venv-gns3server/bin/activate
python3 -m pip install .
python3 -m gns3server
For AI Copilot development, install with additional dependencies:
python3 -m pip install .[ai-features,dev]
For development (tests and linting):
python3 -m pip install .[dev]
You will have to manually install other software dependencies (see above), for Dynamips, VPCS and uBridge the easiest is to install from our PPA.
Docker container
Alternatively, you can run the GNS3 server in a container
bash scripts/docker_dev_server.sh
use Docker Compose
docker compose up -d
Running tests
First, install the development dependencies:
python3 -m pip install -r dev-requirements.txt
Then run the tests using pytest:
python3 -m pytest -vv tests/
API documentation
The API documentation can be accessed when running the server locally:
- On
http://IP:PORT/docsto see with Swagger UI (i.e.http://localhost:3080/docs) - On
http://IP:PORT/redocto see with ReDoc (i.e.http://localhost:3080/redoc)
The documentation can also be viewed online however it may not be the most up-to-date version since it needs manually synchronization with the current code. Also, you cannot use this to interact with a GNS3 server.
Branches
master
master is the next stable release, you can test it in your day-to -day activities. Bug fixes or small improvements pull requests go here.
3.x development brand for the next major release.
Never use this branch for production. Pull requests for major new features go here.