Accessing NAS from VMs and Containers
8 minute read.
Virtual Machines and Containers in TrueNAS 25.04TrueNAS 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 in 25.04.2 (or later) are created and appear on the Virtual Machines screen.
VMs created in 25.04.0 or 25.04.1 using the Instances feature continue to function and appear on the Containers screen.
VMs created in 24.10 or earlier are located depending on migration path:
You do not need to migrate existing VMs from the Containers screen to the Virtual Machines screen at this time. We are developing additional guidance for these legacy VMs for the TrueNAS 25.10 release.
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).
Manually create a bridge interface if you have only one physical interface.
Assign a NIC other than the primary one your TrueNAS server use if you have more than one physical interface. This method makes communication more flexible but does not offer the potential speed benefits of a bridge.
Containers 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.
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.
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:
- 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
After adding the bridge and 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.
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.
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.
To edit the NIC attached to an existing VM:
Go to Instances, select the instance you want to use to access TrueNAS storage, and locate the NIC widget.
Click Add and select the secondary interface from the MAC VLAN dropdown list.
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.
