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

  1. Check whether it is there: nmcli --version. It prints, for example, nmcli tool, version 1.52.1, or command not found.
  2. Install it:
    sudo apt install network-manager          # Debian, Ubuntu
    sudo dnf install NetworkManager           # AlmaLinux, Rocky Linux, RHEL, Fedora
    sudo systemctl enable --now NetworkManager
  3. Check which interfaces it manages: nmcli device status. A device shown as unmanaged is 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). Set renderer: NetworkManager in your netplan file and run sudo 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, modify and delete.
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

  1. Create the bridge with the server's IP settings (use ipv4.method auto for 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
  2. 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
  3. Stop the old profile from starting at boot: sudo nmcli connection modify enp1s0 connection.autoconnect no
  4. 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 br0 alone is not enough while the old profile still holds the card: it answers controller waiting for ports and 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, master and slave-type are deprecated aliases of controller and port-type since 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.

Related services

KVM VPS hosting

NVMe SSD and full root access, with Free Basic Managed Support.

Unmanaged dedicated servers

full root access and free IPMI KVM, with Free Basic Managed Support.

Managed dedicated servers

our engineers look after the server for you, from $135 a month.

Was this answer helpful?

Still stuck? Open a ticket