Containers

The Containers screen allows users to add, edit, or manage Linux containers.

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.

The screen header displays a Pool is not selected status before a pool for containers is selected. See Global Settings for more information.

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

The Containers screen displays No Containers before you create the first container.

The Configuration dropdown menu includes Global Settings, Manage Volumes, and Map User/Group IDs options.

Create New Container at the top right of the screen opens the Create Container wizard.

Configuration on the Containers screen header displays service-level settings that apply to all containers.

• Global Settings opens the Global Settings screen.
• Manage Volumes opens the Volumes screen.
• Map User/Group IDs opens the Map User And Group IDs screen.

Global Settings opens the Global Settings screen showing global options that apply to all containers, including selecting the storage pool for containers and network settings.

The Pool dropdown list shows a list of available pools on the system. [Disabled] deactivates the pool and disables the containers service.

The screen header displays a Pool is not selected status before a pool for containers is selected.

Default Network settings configure global networking defaults for the containers service.

The Volumes screen lists all volumes currently configured for the containers service.

Create Volume opens the Create New Volume dialog to configure a new containers volume.

Import Zvols opens the Import Zvol dialog to import an existing Zvol as a containers volume.

Upload ISO opens a file browser to select an .iso file from the client computer and upload it to TrueNAS for use in containers.

Create Volume on the Volumes screen opens the Create New Volume dialog.

Create creates the new volume.

Import Zvols on the Volumes screen opens the Import Zvol dialog.

delete Delete on an image row deletes that image. A Delete volume dialog displays.

Confirm and then Continue deletes the image. Delete is disabled for active images.

The Map User and Group IDs screen allows users to manually configure UID and GID mappings inside containers.

Existing mappings are shown in a table containing the group or user name, host ID, and container ID. delete Delete on a row deletes that mapping.

The Users or Groups tabs display mappings for individual user or group accounts, respectively.

Existing mappings are shown in a table containing the group or user name, host ID, and container ID. delete Delete on a row deletes that mapping.

Set creates the mapping. Changes take effect immediately, but containers might require a restart to reflect the changes.

The Create Container configuration wizard displays all settings to set up a new container.

The Container Configuration settings specify the container name and operating system image.

The CPU & Memory settings specify the number of virtual CPU cores to allocate to the container and memory size.

The Environment settings configure optional environment variables to run on boot or execute. These settings are only available for containers and cannot be used with VMs.

Add displays a set of environment fields.

The Disks settings allow mounting storage volumes to a container. Container options include creating a new dataset or using an existing one.

Add displays a set of fields to create or mount a disk.

The Proxies settings allow you 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.

Add displays a set of proxy configuration settings.

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

See Accessing NAS from VMs and Containers for more information.

Network Settings

Setting	Description
Use default network settings	Select to use default network settings to connect the container to the host using the automatic bridge defined in Global Settings. Selected by default. Disable to display the Bridged NICs (if available) and Macvlan NICs settings.
Bridged NICs	Select an existing bridge on the TrueNAS host to connect to the container. Displays when one or more existing bridge interface(s) are available.
Macvlan NICs	Select an existing interface to create a virtual network interface based on it, assigning a unique MAC address so the container 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.

USB Devices displays a list of available devices to attach to a container, allowing the device to function as if physically connected.

GPU Devices displays available GPU devices to attach to a container, enabling it to utilize hardware acceleration for graphics or computation tasks.

The Containers table lists each configured container, displaying its name, type, current state, and options to restart or stop it. Stopped containers show the option to start the container.

The Details for Container widgets show information and management options for the selected container.

The restart_alt button restarts or the stop_circle button stops a running container.

The Stop Options window defines when the container stops, immediately or after one of 30 seconds, 1 minute, or 5 minutes occurs.

The play_circle button starts a stopped container.

Search above the Containers table allows entering the name of a container to locate a configured container.

The checkbox on each container row shows the Bulk Actions dropdown.

The Bulk Actions dropdown list allows you to apply actions to one or more containers on your system. Options are Start All Selected, Stop All Selected, and Restart All Selected.

The Details for Container widgets display information and configuration options for the selected container.

The General Info widget displays the container status, autostart setting, base image, CPU, memory, and secure boot configuration. It includes the Edit and Delete buttons for the container.

Delete opens the Delete dialog.

Edit opens an Edit Container: Container configuration screen populated with editable settings also found on the install wizard screen for the container.

The Delete dialog asks for confirmation to delete the selected container.

Confirm activates the Continue button. Continue starts the delete operation.

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

Add opens a list of available USB Devices, GPUs, TPM, and PCI Passthrough devices.

Add Device under PCI Passthrough opens the Add PCI Passthrough Device screen.

The Disks widget shows the storage devices attached to the container, along with their associated paths. It allows you to manage the disks, including adding new ones or modifying existing ones.

Add opens the Add Disk screen for adding new disks to the container.

For existing disks, the more_vert actions include options to Edit or Delete the disk mount.

For VMs, the widget displays the current root disk size. The root disk stores the OS and serves as the boot disk for the VM. Change opens the Change Root Disk Setup dialog.

The Add/Edit Disk screen allows you to configure a new disk or modify an existing one attached to a container.

Add/Edit Disk Settings

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

Save applies changes.

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

Confirm activates the Continue button. Continue starts the delete operation.

The Change Root Disk Setup dialog allows you to configure the size of the disk a VM stores its OS on and boots from, and change the root disk I/O bus.

Save applies changes.

The NIC Widget displays the network interfaces (NICs) attached to the container, along with their names and types. It allows you to add new NICs and manage existing ones.

Add opens a menu with available NIC choices, allowing you to select and attach a new NIC to the container.

For existing NICs, the more_vert actions menu allows you to delete the NIC.

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

Confirm activates the Continue button. Continue starts the delete operation.

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

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

For existing proxies, the more_vert actions menu includes options to Edit or Delete the proxy.

The Add/Edit Proxy screen allows you to configure or modify a proxy setting attached to a container.

Save applies changes.

The Delete Item dialog asks for confirmation to delete the selected proxy configuration.

Confirm activates the Continue button. Continue starts the delete operation.

The Idmap widget shows the user ID (UID) and group ID (GID) mappings used by the container to translate IDs between the host and the container or VM. It provides details such as the Host ID, Maprange, and NS ID for both UIDs and GIDs. These settings are only available for containers and cannot be used with VMs.

• Host ID shows the starting ID used by the host for mapping to the container IDs.
• Maprange indicates the range of IDs that the host allocates for the container.
• NS ID represents the namespace ID used for the mapping.

For example, if the Host ID is 2147000001 and the Maprange is 458752, the container UID 0 (root) is mapped to the host UID 2147000001. This ensures proper isolation and user/group identity management between the host and the container.

The Tools widget provides quick access to various tools and utilities for managing your container. You can open a shell, console, or VNC session directly from this widget.

Shell opens an Container Shell session for command-line interaction with the container.

Serial Console (VM only) opens an Container Console session to access the system console for the container.

VNC (VM only) opens 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).

The Metrics widget displays real-time graphs that monitor container performance, including CPU usage, memory usage, and disk I/O pressure.

CPU (%) shows the percentage of CPU usage over time.

Memory (MiB) displays the memory usage in MiB over time.

Disk I/O Full Pressure (%) tracks the disk input/output pressure as a percentage over time.

The Edit Container: Container screen settings are a subset of those found on the Create Container Wizard screens. It includes the general Container Configuration and CPU and Memory settings for all containers. Additionally, containers include Environment settings. VMs include VNC and Security settings. To edit device, disk, network, or proxy settings, use the Containers Widgets on the Containers screen.

The Container Configuration settings on the Edit screen allow you to modify basic parameters for the container, such as startup behavior.

Autostart automatically starts the container when the system boots.

The CPU & Memory settings on the Edit screen are the same as those in the Create Container wizard.

The VNC settings on the Edit screen are the same as those in the Create Container wizard. These settings are only available for VMs and cannot be used with containers.

The Environment settings on the Edit screen are the same as those in the Create Container wizard. These settings are only available for containers and cannot be used with VMs.

Add displays a set of environment fields.

The Security settings on the Edit screen allow you to enable Secure Boot for the container, ensuring that only trusted, signed software runs during the startup process. These settings are only available for VMs and cannot be used with containers.

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.

Select attaches the selected device.