Containers

Containers allow users to configure linux containers in TrueNAS.

Linux containers, powered by LXC, offer a lightweight, isolated environment that shares the host system kernel while maintaining its own file system, processes, and network settings. Containers start quickly, use fewer system resources than virtual machines (VMs), and scale efficiently, making them ideal for deploying and managing scalable applications with minimal overhead.

You must choose a pool before you can deploy a container. The Containers screen header displays a Pool is not selected status before a pool for containers is selected. See Choosing the Containers Pool below for more information about pool selection.

After setting the pool, Initialized shows on the screen header.

For more information on screens and screen functions, refer to the UI Reference article on Containers Screens.

Use the Configuration dropdown to access the Global Settings, Manage Volumes, and Map User/Group IDs options.

Click Global Settings on the Configuration menu to open the Global Settings screen, showing global options that apply to all containers. Use these options to configure the storage pool for containers and network settings.

You must set a pool before you can add any containers.

Select Enabled to enable container storage.

Use the Pool dropdown to select one or more pools and click Save.

We recommend users keep the container use case in mind when choosing a containers pool. Select a pool with enough storage space for all the containers you intend to host.

For stability and performance, we recommend using SSD/NVMe storage for the containers pool due to their faster speed and resilience for repeated read/writes.

Select additional pools to allow containers to access shared resources.

To select a different pool for containers to use, use the Pool dropdown to select a different pool.

Deselect Enabled to deactivate the pool and disable the containers service.

Use the Default Network settings on the Global Settings screen to define how containers connect to the network. These settings apply to all new containers, unless configured otherwise.

Select Automatic from the Bridge dropdown list to use the default network bridge for communication between containers and the TrueNAS host. To specify an existing bridge, select one from the dropdown list. See Accessing NAS from VMs and Containers for details.
When Bridge is set to Automatic, the IPv4 Network and IPv6 Network settings display.

Enter an IPv4 address and subnet (e.g., 192.168.1.0/24) in IPv4 Network to assign a specific network for containers. Leave this field empty to allow TrueNAS to assign the default address.

Enter an IPv6 address and subnet (e.g., fd42:96dd:aef2:483c::1/64) in IPv6 Network or leave this field empty to allow TrueNAS to assign the default address.

Adjust these settings as needed to match your network environment and ensure proper connectivity for containers.

Click Manage Volumes on the Configuration menu to open the Volumes screen, which lists all the volumes currently configured for the containers service.

Click Create Volume to open the Create New Volume dialog to configure a new volume.

Click Import Zvols to open the Import Zvol dialog to import an existing Zvol as a volume.

Click Create Volume on the Volumes screen to open the Create New Volume dialog.

Enter a name for the volume.

Enter a size for the volume, for example 1 GiB.

Click Create to create the new volume.

Click Import Zvols on the Volumes screen to open the Import Zvol dialog.

Importing a zvol as a volume allows its lifecycle to be managed, including backups, restores, and snapshots. This allows portability between systems using standard tools.

Enter the path or browse to select an existing Zvol in Select Zvols.

Select Clone to clone and promote a temporary snapshot of the zvol into a custom storage volume. This option retains the original zvol while creating an identical copy as a container volume.

Select Move to relocate the existing zvol to the ix-virt dataset as a volume.

Click Configuration > Manage Volumes to access the Volumes screen. Click delete on a volume row to delete that volume. The Delete volume dialog displays.

Select Confirm and then click Continue to delete the volume. TrueNAS disables the delete icon for active images to prevent accidental deletion.

Containers run as isolated environments from the host system.
To give container processes access to host files and datasets, you must map user and group IDs (UIDs and GIDs) between the host and the container.

Click Map User/Group IDs from the Configuration dropdown to open the Map User and Group IDs screen.
This screen allows you to configure how user and group IDs (UIDs and GIDs) appear inside containers.

By default, user and group accounts within a container are assigned UIDs and GIDs from a private range starting at 2147000001.
This mapping ensures security isolation for containers. You can override these mappings to meet specific access requirements.

Select Users or Groups to view mappings for individual user or group accounts.

Existing mappings appear in a table that lists the user or group name, host ID, and container ID.
Click delete Delete on a row to remove a mapping.

To add a new mapping:

• Type an account name to search or select it from the dropdown.
• Enable Map to the same UID/GID in the container to use the same ID from the host in containers.
  This makes the selected user or group ID appear the same inside and outside the container.
• Disable Map to the same UID/GID in the container to assign a different container ID.
  Enter the container UID or GID you want to use—for example, 1000.

Only local users and groups are supported for ID mapping in containers.
Domain accounts from Active Directory or other directory services are not supported.

Click Set to create the mapping.
Changes apply immediately, though restarting the container can be required for them to take effect.

Mapped IDs control access to mounted host datasets.
For example, if you map a host user with UID 3000 to UID 1000 inside the container:

1. Assign permissions on the host dataset to UID 3000.
2. Inside the container, perform actions as UID 1000.

This setup grants user 1000 in the container the same access to the dataset as user 3000 has on the host.
Assigning dataset permissions to a host user is not enough to grant container permissions to all users—you must also map that user and ensure the correct user and UID is used inside the container.

Incorrect or missing mappings can cause permission errors when containers access host paths.

To safely allow container root processes to access host datasets, TrueNAS provides a built-in unprivileged root user for containers truenas_container_unpriv_root.

This user has UID 2147000001 and is used automatically to represent the container root on the host. No manual ID mapping is required.

To grant container root access to host data:

1. Assign permissions on the host dataset to the truenas_container_unpriv_root user.
2. Access the dataset from inside the container as root.

When the container root accesses the path, it uses the host permissions of truenas_container_unpriv_root.

This approach provides secure, controlled access for container root processes without exposing host root privileges.

Click Create New Container to open the Create Container configuration wizard.

To create a new container:

1. Configure the container configuration settings.

   

   a. Enter a name for the container.

   Name Requirements

   A container name must meet these criteria:

   • It must be between 1 and 63 characters long.

   • It can only include letters, numbers, and dashes from the ASCII character set.

   • It cannot begin with a number or a dash.

   • It cannot end with a dash.

   b. Click Browse Catalog to open the Select Image screen.

   

   Search or browse to choose a Linux image. Click Select in the row for your desired image.

2. (Optional) Configure CPU and memory settings.

   

   Enter values for CPU Configuration and Memory Size or leave blank to allow the container access to all host CPU and memory resources. To configure resource allocation:

   a. Enter the number of virtual CPU (vCPU) cores to allocate in CPU Configuration.

   Set to an integer to expose that number of full vCPU cores to the instance.

   Set to a range or comma-separated list to pin vCPUs to specific physical cores. For better cache locality and performance, select cores that share the same cache hierarchy or NUMA node. For example, to assign cores 0,1,2,5,9,10,11, enter 1-2,5,9-11.

   b. Allocate RAM in Memory Size.

   This field accepts human-readable input (Ex. 50 GiB, 500M, 2 TB). If units are not specified, the value defaults to mebibytes (MiB). The minimum value is 32 MiB.

3. (Optional) Configure environment variables to run on boot or execute.

   

   a. Click Add to display a set of environment fields.

   b. Enter the name of the environment variable to set (for example, LANG).

   c. Enter the value to assign to the environment variable (for example, en_US.UTF-8).

   Click Add again to configure additional environment variables.

   Click close to delete a configured environment variable.

4. (Optional) Configure disk settings to mount storage volumes for the container. You can create a new dataset or use an existing one.

   

   a. Click Add in the Disks section to display a set of fields to mount a disk.

   b. To create a new dataset, enter a path or browse to select a parent dataset from the dropdown list of datasets on the system. Then click Create Dataset, enter a name for the new dataset in the Create Dataset window, and click Create.

   To use an existing volume, enter a path or browse to select an existing dataset from the Source dropdown list.

   c. Enter the file system Destination path to mount the disk in the container, for example /media or /var/lib/data.

   d. Click Add again to mount additional storage volumes.

5. (Optional) Configure proxy settings to forward network connections between the host and the container. This routes traffic from a specific address on the host to an address inside the container, or vice versa, allowing the container to connect externally through the host.

   

   a. Click Add in the Proxies section to display a set of proxy configuration settings.

   b. Select the protocol option from the Host Protocol dropdown list to set the connection protocol for the TrueNAS host as TCP or UDP.

   c. Enter a port in Host Port to define the TrueNAS port to map to the container port on the container, for example 3600.

   d. Select the connection protocol for the container in Instance Protocol. Options are TCP or UDP.

   e. Enter the port number within the container in Instance Port, for example 80, to map to the host port.

6. Configure the Network section settings to define how the container connects to the host and external networks. Options include the default network bridge, an existing bridge interface, or a MACVLAN.

   

   • Use default network settings: Enable to connect the instance to the host using the automatic bridge defined in Global Settings. Disable to show the Bridged NICs (if available) and Macvlan NICs settings.

   

   • To configure non-default network settings, select one or more interface options:

     • Bridged NICs: Use to connect an existing bridge interface to the instance.
     • Macvlan NICs: Use to create a virtual network interface based on an existing interface. A MACVLAN assigns a unique MAC address to the virtual interface so the instance appears 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.

7. (Optional) Configure USB devices to attach available devices to the container by selecting one or more in USB Devices. This allows the device to function as if physically connected.

   

8. (Optional) Configure GPU devices in the GPU Devices section to attach available GPU devices, enabling the container to utilize hardware acceleration for graphics or computation tasks.

Select one or more devices.

TrueNAS does not have a list of approved GPUs at this time but TrueNAS does support various GPUs from NVIDIA, Intel, and AMD. As of 24.10, TrueNAS does not automatically install NVIDIA drivers. Instead, users must manually install drivers from the UI. For detailed instructions, see Installing NVIDIA Drivers.

9. Click Create to deploy the container.

TrueNAS 25.04.2 introduces the Virtual Machines screen for creating and managing VMs.

You cannot create new virtual machines using the Containers screen in 25.04.2 or later. New VM creation is only available through the Virtual Machines screen.

Virtual machines created using the previous Instances feature in earlier 25.04 versions remain fully functional and continue to appear in the Containers screen for management purposes. You can manage these existing VMs using the same tools and procedures described in the Managing Containers section.

Virtual machines automatically migrated from TrueNAS 24.10 to 25.04.2 appear in the new Virtual Machines screen and use the updated VM management interface.

Created containers appear in a table on the Containers screen. The table lists each configured container, displaying its name, type, current status, and options to restart or stop it. Stopped containers show the option to start the container.

Select the checkbox to the left of Name (select all) or select one or more container rows to access the Bulk Actions dropdown.

Enter the name of a container in the Search field above the Containers table to locate a configured container.

Click restart_alt to restart or stop_circle to stop a running container. Choosing to stop a container shows a choice to stop immediately or after a small delay.

Click play_circle to start a stopped container.

Select a container row in the table to populate the Details for Container widgets with information and management options for the selected container.

Apply actions to one or more selected containers on your system using Bulk Actions.

Use the dropdown to select Start All Selected, Stop All Selected, or Restart All Selected.

After selecting the container row in the table to populate the Details for Container widgets, locate the General Info widget.

Click Edit to open the Edit Container: Container screen. The Edit Container: Container screen settings are a subset of those found on the Create Container screen. It includes the general Container Configuration and CPU and Memory settings for all containers. Additionally, containers include Environment settings, and VMs include VNC and Security settings.

Select Autostart to automatically start the container when the system boots.

For containers, CPU Configuration and Memory Size can be configured or left blank to allow the container access to all host CPU and memory resources. For VMs, CPU and memory configurations are required.

To edit resource allocation:

When VNC access is enabled, remote clients can connect to VM display sessions using a VNC client. These settings are only available for VMs and cannot be used with containers.

Stop the container before editing VNC settings.

These settings are only available for containers and cannot be used with VMs.

These settings are only available for VMs and cannot be used with containers.

After selecting the container row in the table to populate the Details for Container widgets, locate the General Info widget.

Click Delete to open the Delete dialog.

Select Confirm to activate the Continue button. Click Continue to delete the container.

Use the Devices widget to view all USB, GPU, Trusted Platform Module (TPM), and PCI Passthrough devices attached to the container.

Click Add to open a list of available USB Devices, GPUs, TPM, and PCI Passthrough devices to attach. Select a device to attach to a container.

To attach a PCI passthrough device, click Add Device under PCI Passthrough on the device list to open the Add PCI Passthrough Device. PCI passthrough assigns a physical PCI device, such as a network card or controller, directly to a VM, allowing it to function as if physically attached. The Add PCI Passthrough Device screen lists the available physical PCI devices that can be attached to a container.

Use Search Devices or the Type dropdown to filter available devices. The selected PCI device(s) must not be in use by the host or share an IOMMU group with any device the host requires.

Click Select to attach the selected device.

Use the Disks widget to view the storage devices attached to the container, along with their associated paths.

Click Add to open the Add Disk screen for adding new disks to the container.

Click the more_vert icon to the right of an existing disk to open the actions menu. Select to either Edit or Delete the disk mount.

For VMs, use the Disks widget to manage the root disk size and I/O Bus. The root disk stores the OS and serves as the boot disk for the VM. Click Change to open the Change Root Disk Setup dialog.

Click Add to open the Add Disk screen for adding new disks to the container.

Click the more_vert icon to the right of an existing disk to open the actions menu. Select Edit to edit the disk mount.

For VMs, click Select Volume to open the Volumes screen to create or select a volume to attach. Enter a Boot Priority value to set the order in which to boot disks. By default, the root disk is set to 1, which is the highest priority. Select the I/O Bus for the disk. Options are NVMe, Virtio-BLK, and Virtio-SCSI.

For containers, enter or browse to select the host Source path for the disk. For a new dataset, enter or browse to select the parent path. Enter the Destination path to mount the disk in the container.

Click Save to apply changes.

Click the more_vert icon to the right of an existing disk to open the actions menu. Select Delete to delete the disk mount.

The Delete Item dialog asks for confirmation to delete the selected disk mount.

Click Confirm to activate the Continue button. Click Continue to start the delete operation.

Click Change to the right of the root disk to open the Change Root Disk Setup dialog.

Enter a new root disk size in GiB, such as 20.

Select the Root Disk I/O Bus. Options are NVMe, Virtio-BLK, and Virtio-SCSI.

Click Save to apply changes.

Use the NIC Widget to view the network interfaces (NICs) attached to the container, along with their names and types.

Click Add to open a menu with available NIC choices. Select a NIC from the dropdown to attach it to the container.

Click the more_vert icon to the right of an existing NIC to open the actions menu. Select Delete to delete the NIC mount.

Click Confirm to activate the Continue button. Click Continue to start the delete operation.

Use the Proxies widget to view the network proxy settings configured for the container. It allows you to manage these settings, including adding, editing, or removing proxies. Proxies are available for containers only and cannot be used with VMs.

Click Add to open the Add Proxy screen to configure a new proxy for the container.

For existing proxies, click more_vert to open the actions menu with options to Edit or Delete the proxy.

Use the Add Proxy or Edit Proxy screen to configure or modify a proxy setting attached to a container.

Select a Host Protocol to set the connection protocol for the TrueNAS host. Options are TCP or UDP.

Enter a port number in Host Port to map to the container port on the container, for example 3600.

Select an Instance Protocol to set the connection protocol for the container. Options are TCP or UDP.

Enter a port number for the container in Instance Port, for example 80.

Click Save to apply changes.

For existing proxies, click more_vert to open the actions menu. Select Delete to remove the proxy configuration.

Click Confirm to activate the Continue button. Click Continue to start the delete operation.

After selecting the container row in the table to populate the Details for Container widgets, locate the Tools widget. You can open a shell, console, or VNC session directly from this widget.

Click Shell to open an Instance Shell session for command-line interaction with the container.

For VMs, click Serial Console to open an Instance Console session to access the system console for the container.

For VMs, click VNC to open a VNC connection using your preferred client. It uses a VNC URL scheme (for example, vnc://hostname.domain.com:5930) to launch the session directly in the application. If your environment does not support VNC URLs, you can manually connect using a VNC client by entering the host name or IP address followed by the port number without vnc:// (for example, hostname.domain.com:5930 or IP:5930).