Network Bridges in TrueNAS: What They Are, Why They Matter

There's this weird gap in tech documentation where the people who know enough to understand why you'd use something assume you already know what it is, and the people explaining what it is never get around to the practical benefits. Network bridges in TrueNAS live squarely in that gap.

Tom from Lawrence Systems just dropped a walkthrough on setting up bridges in TrueNAS that's worth your time if you're running containers or VMs. Not because it's flashy—it's five minutes of clicking through network settings—but because it solves a specific, annoying problem you might not realize you have yet.

The Setup (and Why It Feels Backwards)

Here's the part that trips people up: to create a network bridge in TrueNAS, you first have to remove the IP address from your network adapter. Feels like walking backwards into a room, right?

Tom walks through this in TrueNAS 25.10.1 (current as of February 2025, and yes, he's already testing the nightlies for version 26). The process goes like this: you've got a network adapter with a static IP assigned—say, 172.16.16.33. You need to remember that adapter name (something elegant like en01np0) because you're about to make it a member of the bridge you're creating.

"We're going to first edit and remove the IP address of this," Tom explains. "I'm going to leave it as defined static, but please note I've defined no static."

Then you create the bridge interface (BR0, BR1, whatever makes sense to you), assign it that same IP address you just removed, and designate your physical network interface as a bridge member. The critical part: you don't test the changes before adding the bridge, because testing changes while you have no IP address means losing access to the interface entirely. Not ideal when you're working remotely.

What This Actually Does

Okay, so you've created an abstraction layer between your network interface and your IP address. Cool story—what's the point?

The magic is in how bridges handle MAC addresses. When you connect a container to a bridge, that container gets its own IP address on the same network interface. Not through NAT, not through port forwarding—it's on the network like any other device. Tom demonstrates this by spinning up a Debian container (Trixie, for the nerds keeping track) and running ip a inside it:

"You can see that it got an IP address. And a reason for that is because of the way bridges work. Bridges allow you to add more MAC addresses to them. So this works not going through the primary IP but going through the same network interface but having its own dedicated IP."

This is different from Docker app containers in TrueNAS. We're talking about LXC containers (which TrueNAS calls "incus containers" in version 25 and will officially call LXC containers in version 26). These containers work best when they're attached to bridges.

The Real Benefit: Hardware Swaps

Here's where this gets practical. Say you've got ten containers running, all attached to your network interface. Now you need to swap out that network card—maybe it's flaky, maybe you're upgrading to 10GbE, whatever.

Without a bridge, you'd need to reconfigure each container's network settings individually. With a bridge, you just change which physical interface the bridge uses, and everything connected to that bridge comes along for the ride.

"One of the advantages of using a bridge, if you ever have a lot of containers attached to a bridge and you want to change out a network interface, you can just change what interfaces are attached to the bridge and then that will apply to all things attached to that bridge interface," Tom notes.

It's the difference between editing one setting and editing N settings, where N is the number of containers you're running. Future you will appreciate this.

VLANs: Where This Gets Interesting

The VLAN part is where bridges move from "nice to have" to "okay this is actually elegant." Tom creates a second bridge (BR20) and attaches it to VLAN 20 instead of the primary network. This bridge doesn't even need an IP address—it's just there to route traffic.

Now when you create a container, you can choose which bridge to attach it to. Containers on BR0 talk to your main network. Containers on BR20 talk to VLAN 20. You've essentially created network segregation at the container level without touching your containers' configs—you're just choosing which bridge they connect to at creation time.

This is cleaner than it sounds. No tagging traffic inside containers, no complex routing rules, just "this container goes here, that container goes there."

What TrueNAS Isn't Telling You

Tom explicitly doesn't explain what a bridge is in networking terms—"there's lots of documentation you can find on Linux bridges," he says, which is both true and kind of hilarious because Linux bridge documentation ranges from impenetrable kernel docs to forum posts that assume you already know.

For context: a network bridge operates at layer 2 (the data link layer, where MAC addresses live). It's fundamentally different from a router, which operates at layer 3 with IP addresses. Think of it like a smart switch that connects multiple network segments while making them look like one network. In the TrueNAS case, you're connecting your physical network interface to virtual interfaces (your containers) through software.

TrueNAS is built on Debian, which means it's using standard Linux networking utilities. The bridge setup Tom's showing isn't TrueNAS-specific magic—it's leveraging tools that have been in the Linux kernel for years. Which means if you understand this once, you understand it everywhere.

The Part Nobody Mentions

Here's what I find interesting: Tom's demonstrating this in version 25.10.1 and mentions it looks identical in the version 26 nightlies. The networking interface in TrueNAS has been stable for a while now. That's... actually kind of remarkable in a space where UIs get redesigned every release.

Stability in infrastructure tools is underrated. When you're managing storage and network configuration, "it works the same way it did last year" is a feature, not a bug.

Tom's planning follow-up videos on containers in TrueNAS, including one on Proxmox Backup. If you're running this kind of setup, bridges aren't optional context—they're the foundation everything else is built on. Better to understand them now than to reverse-engineer them later when something breaks.

—Yuki Okonkwo, AI & Machine Learning Correspondent