TrueNAS SCALETrueNAS SCALE Nightly Development Documentation
This content follows experimental early release software. Use the Product and Version selectors above to view content specific to a stable software release.

Setting Up a Network Bridge

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 where you need to extend a network segment or combine different types of network traffic. Bridging can be used to integrate different types of networks (e.g., wireless and wired networks) or to segment traffic within the same network. A bridge can also be used to allow a VM configured on TrueNAS to communicate with the host system. See Accessing NAS From a VM for more information.

Prepare your system for interface changes by stopping and/or removing apps, VM NIC devices, and services that can cause conflicts:

  • If you have apps running, disable them before proceeding.
  • Power off any running VMs before making interface IP changes. Remove active NIC devices.
  • If you encounter issues with testing network changes, you might need to stop any services using the current IP address, including Kubernetes and sharing services, such as SMB.

To set up a bridge interface, from the Network screen:

  1. Click Add in the Interfaces widget. The Add Interface configuration screen displays.
  1. Select Bridge from the Type dropdown list. You cannot change the Type field value after you click Save.

  2. Enter a name for the interface. Use the format bondX, vlanX, or brX where X is a number representing a non-parent interface. Read-only when editing an interface. You cannot change the Name of the interface after you click Save.

  3. (Optional but recommended) Enter any notes or reminders about this particular bridge in the Description field.

  4. Select the interfaces on the Bridge Members dropdown list.

  5. Next to Aliases click Add to enter the IP address for this bridge interface. (Optional) click Add to display an additional IP address field for each additional IP address you want to add.

  1. Click Save when finished. The created bridge shows in Interfaces with its associated IP address information.
  1. To determine if network changes are successful, click Test Changes.
  1. Once TrueNAS finishes testing the interface, click Save Changes if you want to keep the changes. Click Revert Changes to discard the changes and return to the previous configuration.
Troubleshooting Network Changes

Occasionally, a misconfigured bridge or a conflict with a running application, VM, or service can cause the network changes test to fail. Typically, this is because the bridge is configured using an IP address that is already in use. If the system does not receive a Save Changes check-in before the test times out (default 60 seconds), TrueNAS automatically reverts all unsaved changes.

The following troubleshooting options are available if you are unable to save the new bridge and network changes. Options are ordered from the least to the most disruptive. Try options one and two before proceeding with option three and then four.

  1. Ensure that there are no currently running applications.
  2. Stop any running VMs.
  3. (Optional) Go to Services. Click edit Configure to view the current configuration of sharing services including SMB and NFS. Stop any services that have a bind IP address matching the bridge IP address. Restart the service(s) after network changes are tested and saved.
  4. (Optional) Stop the Kubernetes service. Connect to a shell session and enter systemctl k3s.service stop. Press Enter. After network changes are tested and saved, restart Kubernetes with systemctl k3s.service start.