TrueNAS Stable Version Documentation
This content follows TrueNAS 25.10 (Goldeye) releases.
Use the Product and Version selectors above to view content specific to a different software release.
Accessing NAS from VMs and Containers
6 minute read.
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.
