Setting Up a Network Bridge
5 minute read.
In general, a bridge refers to various methods of combining (aggregating) multiple network connections into a single aggregate network.
TrueNAS uses bridge(4) as the kernel bridge driver. Bridge(8) is a command for configuring the bridge in Linux. While the examples focus on the deprecated brctl(8) from the bridge-utilities package, we use ip(8) and bridge(8) from iproute2 instead. Refer to the FAQ section that covers bridging topics more generally.
Network bridging does not inherently aggregate bandwidth like link aggregation (LAGG). Bridging is often used for scenarios that require extending a network segment or combining different types of network traffic.
You can use bridging to integrate different types of networks (e.g., wireless and wired networks) or to segment traffic within the same network. You can also use a bridge to allow a VM, container, or app configured on TrueNAS to communicate with the host system. See Accessing NAS from Containers for more information.
Before making network interface changes:
- Stop running apps.
- Power off running virtual machines (VMs) and containers.
- Remove active NIC devices for VMs and containers.
Changing IP address(s) assigned to the primary interface can cause issues with access, so it is best to make changes outside normal working hours.
To set up a bridge interface, go to System > Network > Interfaces. Locate the interface you want to use as the bridge parent interface.
If using an existing interface, note the interface IP Address and subnet mask, then click the Edit option for the interface to open the Edit Interface screen.
If using a newly added network interface, click Add to open the Add Interface screen to configure the new interface as a bridge.
Before making a change, Note the MAC address for the interface in the Interfaces widget, click on the edit option to open the Edit Interface screen and take note of any static IP addresses associated with the interface. Disable DHCP if it is enabled, and clear the static IP addresses assigned to the interface. After clicking Save TrueNAS prompts you to test the changes before making it permanent.
Alternatively, after obtaining the MAC address and IP address information you can exit the Edit Interface screen, and then select the Reset Configuration option for the interface to clear the interface settings. After selecting Confirm and then Reset, TrueNaS prompts you to test the changes before making it permanent.
TrueNAS prompts you to test any network change before it makes the change permanent so you do not loose access to the interface or your TrueNAS system. Refer to Testing Network Interface Changes for more information on validating network interface changes.
After resetting the interface configuration, click Add to open the Add Interface screen to reconfigure the interface as documented below.
While on the System > Network screen, click Add on the Interfaces widget to open the Add Interfaces screen.
Select Bridge in Type. Name populates with the default br1 or increments to the next available number if other bridge interfaces exist on your system.
You cannot change the Type field value after clicking Save!
You cannot change the Name of the interface after clicking Save.
(Optional but recommended) Enter any notes or reminders about this particular bridge in Description.
Select Define Static IP Addresses, then click Add to the right of Static IP Addresses to show the IP address and netmask fields.
If adding an interface after resetting the configuration for an existing interface, enter the IP address from that reset interface.
If adding a new interface, enter the new static IP address.
Click Add for each IP address to associate with this interface.
If you want DHCP to assign an IP address, select Get IP Address Automatically from DHCP.
Select the interfaces to include in this bridge on the Bridge Members dropdown list.
Leave Enable Learning selected unless you want to defer interface learning until runtime. Disabling learning prevents premature state transitions and potential issues during system startup.
Click Save when finished. The created bridge shows in Interfaces with its associated IP address information.
Click Test Changes to determine if network changes are successful. See Testing Network Interface Changes
