Why do my QEMU nodes start but my Docker nodes don't?

GNS3 only asks uBridge for elevated network access when a node needs host interfaces: Docker containers, VMware VMs, and Cloud or NAT nodes bound to a real interface. QEMU, Dynamips, IOU and VPCS links use plain UDP tunnels, so they keep working even when uBridge has no capabilities.

Can I just run GNS3 with sudo?

It hides the error, but it runs the whole GUI and server as root, and the projects it creates end up owned by root. The Ubuntu package itself recommends giving uBridge the capabilities instead, so that less code runs with elevated privileges.

Do I need to do this in the GNS3 VM?

No. The GNS3 VM ships with uBridge already set up. This error comes from a GNS3 server running directly on a Linux desktop or server, usually the local server.

The fix worked, then broke after an update. Why?

File capabilities are stored on the file itself. When an update or a rebuild replaces the ubridge binary, the new file has none until the package script or setcap sets them again. Check with getcap and set them again if the output is empty.

GNS3 "uBridge requires root access": how to fix it

On Linux, a Docker node, a NAT node or a VMware VM refuses to start and GNS3 reports uBridge requires root access or the capability to interact with network adapters. A close cousin appears when you draw a link: uBridge is not available, path doesn't exist, or you just installed GNS3 and need to restart your user session to refresh user permissions. Both mean the GNS3 server, running as your user, cannot run uBridge with the network rights it needs.

Why it happens

uBridge is the small helper GNS3 uses to move packets between nodes. For most links it only relays UDP, which needs no special rights. But a container node, a VMware VM, or a Cloud or NAT node bound to a host interface needs uBridge to open TAP and raw Ethernet interfaces. Linux only allows that with the CAP_NET_ADMIN and CAP_NET_RAW capabilities, as the GNS3 FAQ on uBridge permissions explains.

Before it starts one of those nodes, the GNS3 server checks three things, in has_privileged_access(): is the server running as root, is the uBridge binary owned by root with the setuid bit, or does the binary carry the CAP_NET_RAW file capability. If none is true, you get the "requires root access" error.

This is also why the problem looks selective. QEMU, Dynamips, IOU and VPCS nodes keep starting and linking normally, because their links are plain UDP tunnels. Only the node types that touch real or virtual host interfaces fail.

Running the whole GNS3 GUI with sudo makes the error go away, but it is a poor fix: every project file it writes is then owned by root. The Ubuntu package recommends the capability route instead, because less of the code runs with elevated privileges.

How you end up there depends on how GNS3 was installed:

Ubuntu PPA. Installing the ubridge package asks "Should non-superusers be able to run GNS3?". If you answer Yes, the package creates a ubridge group, makes the binary root:ubridge with mode 754, sets the capabilities and adds members of sudo to the group. If you answer No, the binary gets no capabilities, and Docker nodes fail.
Not in the group yet. With the Yes answer, only members of ubridge may execute the binary. Until you log out and back in, your session doesn't have the new group, the server cannot execute uBridge, and you get the "uBridge is not available" message.
pipx installs. The GNS3 Linux install guide installs GNS3 on Debian through pipx, which doesn't include uBridge at all. Kali users hit the same wall, because there is no official package for Kali.
A replaced binary. Capabilities live on the file. A rebuild or a copy creates a file without them, as in gns3-server#2481, where getcap printed nothing.

The fix

1. Look at the binary

command -v ubridge
ubridge -v
ls -l "$(command -v ubridge)"
getcap "$(command -v ubridge)"

If command -v prints nothing, check ls -l /usr/bin/ubridge. If the file exists with group ubridge, you only lack the group or a fresh session: see steps 2 and 5. If there is no file, go to step 4. If getcap prints nothing, the binary has no capabilities: go to step 2 or 3.

2. Ubuntu with the GNS3 PPA: reconfigure the package

Run the package question again and answer Yes:

sudo dpkg-reconfigure ubridge

Then add yourself to the groups the GNS3 guide lists. ubridge is the one that matters here; docker matters for Docker nodes:

sudo usermod -aG ubridge,libvirt,kvm,wireshark,docker $(whoami)

3. Any other install: set the capabilities yourself

If uBridge came from another package or from your own build, give it the two capabilities. This is the command from the GNS3 FAQ, applied to wherever your binary lives:

sudo setcap cap_net_admin,cap_net_raw=eip "$(command -v ubridge)"

You need to run it again each time the binary is replaced.

4. No uBridge at all: build it

On Debian with pipx, Kali or any distribution without a package, build uBridge from the uBridge repository. It needs the libpcap headers:

sudo apt install build-essential libpcap-dev git
git clone https://github.com/GNS3/ubridge.git
cd ubridge
make
sudo make install

make install copies the binary to /usr/local/bin and sets the capabilities with setcap, so non-root users can run it.

5. Start a new session

Group changes only apply to new logins. Log out of your desktop and back in, or reboot, as the GNS3 guide says. Then start GNS3 again. Restarting only the GNS3 window is not enough if the server process was started from the old session.

How to check it worked

Check the binary and your groups:

getcap "$(command -v ubridge)"
id -nG

getcap should show cap_net_admin,cap_net_raw=eip on the binary. id -nG lists the groups of your current session, so ubridge must appear there, not only in /etc/group. Then start the Docker or NAT node that failed. It should go green, and a link from it should carry traffic.

If it still fails

GNS3 uses another binary. The server runs whatever ubridge_path points to under [Server] in ~/.config/GNS3/2.2/gns3_server.conf, or the first ubridge on your PATH if the key is absent. If you fixed /usr/bin/ubridge but a copy in /usr/local/bin comes first, fix that one too, or remove it.
The server runs as another user. If gns3server runs as a service under a dedicated account, that account needs the group membership, not your desktop user.
The next error is about Docker. Can't connect to Docker daemon is a separate problem: your user can't reach the Docker socket. Joining the docker group and starting a new session usually solves it.
The node starts but has no internet. That is a NAT or address problem, covered in GNS3 Docker containers with no internet. Packet captures on Docker links also depend on uBridge, see GNS3 Wireshark capture not working.
You'd rather not touch the host. Run the nodes on the GNS3 VM instead of the local server. It ships with uBridge already set up.

For the other common GNS3 errors, see the GNS3 troubleshooting guide.

Or skip uBridge for a lab of containers

If your lab is only Linux containers, you may not need GNS3's packet plumbing at all. Isothrum's editor runs in the browser, needs no account, and exports the lab you draw as a Docker Compose file, with any Docker image on each node. You start it with docker compose up, and Docker creates the networks itself. It doesn't fix uBridge, but it is one less component to grant root-level rights to.