Accessing NAS from VMs and Containers
7 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 Apps and the Containers screens to verify all apps and containers are stopped. If still running, stop all apps and containers listed on the Applications and the Containers screens.
Go to Virtual Machines, expand each VM, and click Power Off to stop each VM. Powering off the VM disconnects any NIC device used by the VM, where stopping the VM might not.
Go to System > Network and take a screenshot showing your Interfaces and the Global Configuration widgets.
Click the icon for the interface, to open the Edit Interface screen. Click the x to the right of Static IP Addresses to remove the current static IP address assignment, and then click Save.
Click Add to open the Add Interface screen. Configure the interface:
a. Set Type to Bridge. Name automatically populates with the correct name. You cannot change the Type field value or the name after clicking Save!
b. (Optional) Enter a short description for the bridge. This is optional but recommended if configuring multiple bridges on your system to help identify their use or location.
c. Select Define Static IP Addresses, then click Add to the right of Static IP Addresses. Enter the IP address and select the netmask for the interface edited in step 4 above. Refer to the screenshot if you do not remember the IP address and netmask.
d. Select the interface name in Bridge Members. You only need to add the interface name edited in step 4 above. 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.
e. Click Save.
TrueNAS shows the bridge on the Interfaces widget.
Click Test Changes. See Testing Network Changes above for details on testing and saving network changes.
TrueNAS shows the bridge as working.
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.
