Accessing NAS from VMs and Containers

Virtual Machines and Containers in TrueNAS 25.04

TrueNAS 25.04 introduces support for Containers (Linux system containers), enabling lightweight isolation similar to jails in TrueNAS CORE.

TrueNAS 25.04.2 reintroduces “classic virtualization” with the Virtual Machines feature.

Virtual machines created in 25.04.0 or 25.04.1 using the Instances feature continue to function and appear in the Containers screen. New VMs and those migrated from 24.10.2.2 to 25.04.2 use the Virtual Machines screen.

Virtual machines automatically migrate from TrueNAS 24.10 to 25.04.2. No manual migration of virtual machines is required.

We are actively updating Tutorials and UI Reference articles to reflect these changes. Please use the Docs Hub Feedback button (located to the right of any article) to report documentation issues or request improvements to the Containers or Virtual Machines documentation.

Containers (Linux system containers) are an experimental feature intended for community testing only. Functionality could change significantly between releases, and containers might not upgrade reliably. Use this feature for testing purposes only—do not rely on it for production workloads. Long-term stability is planned for future TrueNAS Community Edition releases.

Make all configuration changes using the TrueNAS UI. Operations using the command line are not supported and might not persist on upgrade.

For assistance or to discuss this feature with other TrueNAS users, visit our community forums.
To report bugs, submit an issue on TrueNAS Jira.

If you want to access your TrueNAS directories from within a virtual machine or container hosted on the system, you have multiple options:

  • Allow TrueNAS to create an automatic bridge (default)

  • If you have only one physical interface, you can manually create a bridge interface.

  • If you have more than one physical interface, you can assign a NIC other than the primary one your TrueNAS server uses. This method makes communication more flexible but does not offer the potential speed benefits of a bridge.

    Instances (Linux containers or VMs) allow you to configure a MACVLAN NIC, which creates a virtual interface based on an existing physical one. The assigned unique MAC address allows the instance to appear as a separate device on the network.

A MACVLAN NIC on the same physical interface as the TrueNAS host cannot directly communicate with the host. MACVLAN sends traffic directly to the external network without passing through the host network stack. The host does not recognize MACVLAN packets as local, so any traffic between them must be routed through an external switch, use a separate NIC, or use a network bridge.

Using Default Network Settings

Leave Use default network settings selected while creating a new instance to allow TrueNAS to automatically assign the default network bridge. This is the simplest way to allow communication between containers and the TrueNAS host.

Default Network Settings
Figure 1: Default Network Settings

Creating a Bridge: Single Physical Interface

If your system only has a single physical interface, and you prefer to manually configure a network bridge, complete these steps.

Before making network interface changes:

  1. Stop running apps.
  2. Power off running virtual machines (VMs) and containers.
  3. Remove active NIC devices for VMs and containers.

Sharing services such as SMB that use the IP address(s) assigned to the primary interface might cause issues with testing network changes. To resolve issues, stop sharing services such as SMB, change the interface, and test the connection. Restart the service when complete.

To set up a bridge interface:

  1. Go to Network > Interfaces and find the active interface you want to use as the bridge parent interface. Note the interface IP Address and subnet mask. Click the interface to open the Edit Interface screen.

  2. Clear the DHCP checkbox, if enabled. Note the IP address and mask under Aliases. Click the X next to the listed alias to remove the IP address and mask. The Aliases field now reads No items have been added yet. Click Save.

    The Interfaces widget displays the edited interface without IP information.

  3. Click Add to open the Add Interface screen. Select Bridge from the Type dropdown list. You cannot change the Type field value after clicking Save!

  4. Enter a name for the interface. Use the correct format based on the interface type:

    bondX* for a LAGG interface vlanX for a VLAN interface brx for a bridge interface

    Where X is a number representing a non-parent interface. Assign the first bridge interface br0.

    You cannot change the Name of the interface after clicking Save.

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

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

  7. Click Add to the right of Aliases to show the IP address fields, and enter the IP address for this bridge interface. Click Add again to show additional IP address fields for each additional IP address you want to add.

  8. Click Save when finished. The created bridge shows in Interfaces with its associated IP address information.

  9. Click Test Changes to determine if network changes are successful. See Testing Network Interface Changes

  10. After TrueNAS finishes testing the interface, click Save Changes 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 cannot 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 options three and 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 running apps. After network changes are tested and saved, restart apps.
  1. To assign the bridge to a VM or container, go to Instances, select the instance you want to use to access TrueNAS storage, and locate the NIC widget. Click Add and select the new bridge interface from the dropdown list.
Add NIC
Figure 10: Add NIC

You can now access your TrueNAS storage from the container. You might have to set up shares or users with home directories to access certain files.

Assigning a Secondary NIC: Multiple Physical Interfaces

If you have more than one NIC on your system, you can assign container traffic to a secondary NIC. Configure the secondary interface as described in Managing Interfaces before attaching it to an instance.

If you are creating a new instance, use the Network settings to disable Use default network Settings and select the secondary NIC from Macvlan NICs.

Non-Default Network Settings
Figure 11: Non-Default Network Settings

To edit the NIC attached to an existing VM:

  1. Go to Instances, select the instance you want to use to access TrueNAS storage, and locate the NIC widget.

  2. Click Add and select the secondary interface from the MAC VLAN dropdown list.

VM Access Examples

Linux Example

Linux VMs and containers can access TrueNAS storage using FTP, SMB, and NFS.

In the example below, the Linux VM uses FTP to access a home directory for a user on TrueNAS.

Windows Example

Windows VMs can access TrueNAS storage using FTP and SMB.

The example below shows the Windows VM accessing an SMB share on TrueNAS.