Updated: 18 October 2026 · Applies to: NetworkManager 1.52 (Debian 13, bridge tested on a real Linux 6.12 kernel), 1.54 (Ubuntu 26.04), 1.46 (Ubuntu 24.04) and 1.56 (AlmaLinux 10, Fedora 44)
nmcli is the command-line tool of NetworkManager, so you install it with the NetworkManager package: sudo apt install network-manager on Debian and Ubuntu, sudo dnf install NetworkManager on AlmaLinux, Rocky Linux, RHEL and Fedora (where it is normally installed already). A network bridge then takes three nmcli commands: nmcli connection add type bridge for the bridge, nmcli connection add ... port-type bridge controller br0 for the network card, and nmcli connection up for the port.
1. Install nmcli
- Check whether it is there:
nmcli --version. It prints, for example,nmcli tool, version 1.52.1, orcommand not found. - Install it:
sudo apt install network-manager # Debian, Ubuntu sudo dnf install NetworkManager # AlmaLinux, Rocky Linux, RHEL, Fedora sudo systemctl enable --now NetworkManager
- Check which interfaces it manages:
nmcli device status. A device shown asunmanagedis configured by another tool.
Installing the package does not hand your network over automatically:
- Debian: NetworkManager ignores every interface defined in
/etc/network/interfaces(the package sets[ifupdown] managed=false). According to the Debian wiki, comment the interface out there and restart NetworkManager to let it take over. - Ubuntu Server: netplan gives wired interfaces to systemd-networkd, and NetworkManager leaves them unmanaged (
/usr/lib/NetworkManager/conf.d/10-globally-managed-devices.conf). Setrenderer: NetworkManagerin your netplan file and runsudo netplan apply. On Ubuntu 24.04 and 26.04, profiles you create with nmcli are saved as netplan files,/etc/netplan/90-NM-<uuid>.yaml.
On a remote server, make these changes from a console (see step 3), not over SSH.
2. nmcli connection add: the syntax
nmcli connection add type TYPE ifname DEVICE con-name NAME [setting value ...]
- type is required (ethernet, bridge, bond, vlan, wifi...). Without it:
Error: 'type' argument is required. - ifname ties the profile to one device. Leave it out and the profile fits any device of that type.
- con-name is the profile name you use later with
up,down,modifyanddelete.
sudo nmcli connection add type ethernet ifname enp1s0 con-name lan-dhcp ipv4.method auto sudo nmcli connection add type ethernet ifname enp1s0 con-name enp1s0 \ ipv4.method manual ipv4.addresses 203.0.113.10/24 ipv4.gateway 203.0.113.1 ipv4.dns 192.0.2.53
Connection 'enp1s0' (a456f6f9-644e-49db-87b0-2b13e2989eee) successfully added.
A new profile is only stored; sudo nmcli connection up NAME activates it. On Debian, AlmaLinux and Rocky Linux the profiles are files in /etc/NetworkManager/system-connections/. To change the IP address of an existing profile, see How to Change the IP Address on RHEL, AlmaLinux and Rocky Linux.
3. Before you bridge the main interface of a remote server
A bridge takes over the server's IP address from the network card. One wrong address, gateway or interface name and SSH stops answering. Work from a console that does not depend on the network: on a Ucartz VPS the VNC console (How to Access Your VPS via VNC in Virtualizor), on a dedicated server the IPMI console (How to Install an OS Using Supermicro IPMI). First note the current settings:
nmcli -f NAME,DEVICE connection show --active # the active profile, here enp1s0 ip -br addr; ip route # address and gateway nmcli -g GENERAL.HWADDR device show enp1s0 # the card's MAC address
4. Create the bridge with nmcli
- Create the bridge with the server's IP settings (use
ipv4.method autofor DHCP):sudo nmcli connection add type bridge ifname br0 con-name br0 \ ipv4.method manual ipv4.addresses 203.0.113.10/24 ipv4.gateway 203.0.113.1 \ ipv4.dns 192.0.2.53 bridge.stp no ethernet.cloned-mac-address 52:54:00:12:34:56
- Add the network card as a port of br0:
sudo nmcli connection add type ethernet ifname enp1s0 con-name br0-port1 port-type bridge controller br0
- Stop the old profile from starting at boot:
sudo nmcli connection modify enp1s0 connection.autoconnect no - Activate the port; the bridge comes up with it:
sudo nmcli connection up br0-port1
Result in our lab (Debian 13, NetworkManager 1.52.1):
$ nmcli device status DEVICE TYPE STATE CONNECTION br0 bridge connected br0 enp1s0 ethernet connected br0-port1 lo loopback connected (externally) lo $ ip -br addr lo UNKNOWN 127.0.0.1/8 ::1/128 enp1s0 UNKNOWN br0 UP 203.0.113.10/24 $ ip route default via 203.0.113.1 dev br0 proto static metric 425 203.0.113.0/24 dev br0 proto kernel scope link src 203.0.113.10 metric 425
Three things we saw in testing:
nmcli connection up br0alone is not enough while the old profile still holds the card: it answerscontroller waiting for portsand the card keeps the IP. Activate the port profile.- Without
ethernet.cloned-mac-address, br0 got a generated MAC address (2e:b7:7d:10:c3:43) instead of the card's. Networks that only accept the server's known MAC address then drop the traffic. Use your card's MAC from step 3. - Older guides write
type bridge-slave ifname enp1s0 master br0. It still works and creates the same profile; according to the NetworkManager documentation,masterandslave-typeare deprecated aliases ofcontrollerandport-typesince version 1.46.
5. Check the bridge settings
(Lab output, shortened.)
$ nmcli -f bridge connection show br0 bridge.mac-address: -- bridge.stp: no bridge.priority: 32768 bridge.forward-delay: 15 ... $ bridge link show 2: enp1s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding priority 32 cost 100
STP is off here because a server bridge with one port cannot form a loop; leave it on (bridge.stp yes) if you connect several physical ports.
6. Undo the bridge
sudo nmcli connection modify enp1s0 connection.autoconnect yes sudo nmcli connection up enp1s0 sudo nmcli connection delete br0-port1 br0
In our lab the address moved straight back to enp1s0. If an empty br0 device is still listed by ip -br link, remove it with sudo ip link delete br0.
To connect KVM virtual machines to the bridge, see How to Set Up a Network Bridge (br0) for KVM Virtual Machines. For netplan-only setups on Ubuntu, see How to Set a Static IP on Ubuntu with Netplan.
Official documentation: nmcli settings reference and Debian wiki: NetworkManager.