Containers Screens

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

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

The Configuration dropdown opens options to configure global container settings:

• Settings opens the Settings screen to configure the preferred pool and default network.
• Map User/Group IDs opens the Map User and Group IDs screen to configure UID and GID mappings.

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

The Settings screen displays global options that apply to all containers, including an optional preferred storage pool and default network settings.

Preferred Pool specifies an optional default storage pool for container data. When no preferred pool is configured, TrueNAS prompts for pool selection at container creation.

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

The Map User and Group IDs screen allows users to manually configure UID and GID mappings between the TrueNAS host and containers. It opens after clicking Configuration on the Containers screen header and selecting Map User/Group IDs.

Existing mappings appear in a table listing the user or group name, host ID, and container ID. delete Delete on a row removes that mapping.

Set creates the mapping. Changes apply immediately, though restarting the container might be required for them to take effect.

The Add Container screen displays basic configuration fields and an Advanced Options button for additional settings.

The basic settings are always visible and configure essential container properties.

Advanced Options shows additional configuration settings.

The Storage settings only show when a preferred pool is configured in Settings.

The CPU Configuration settings bind the container to specific CPU cores.

The Time Configuration settings control container time zone and shutdown behavior.

The Init Process settings configure the initialization process for the container.

The Environment Variables settings configure optional environment variables to run on boot or execute.

Add shows a set of environment variable fields each time you click it.

The ID Mapping settings configure how user and group IDs (UIDs/GIDs) inside the container map to UIDs/GIDs on the TrueNAS host. This setting is available at container creation only and cannot be changed after the container is created.

Setting ID Map Type to Privileged removes all UID isolation between the container and the TrueNAS host. Container processes running as root have direct host root access. Use only when an application explicitly requires it and you understand the security implications.

Capabilities settings control Linux capabilities, which are special permissions that divide root privileges into distinct units.
Allows containers to perform specific privileged operations without granting full root access.

Device configuration (network interfaces, USB devices, GPU devices, and file system mounts) is performed after container creation using the detail cards on the Containers screen.
See Containers Cards for information on configuring devices.

The Containers table lists each configured container name, current state, autostart setting, and live resource metrics: CPU %, Memory MiB, and Disk I/O % Full Pressure (shown as N/A when the container is stopped or metrics are unavailable).
Stopped containers show the option to start the container.

The Details for Container cards 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 how the container stops:

• Wait for graceful stop - Sends a shutdown signal and waits indefinitely for the container to stop gracefully. Does not force kill the container.
• Wait for graceful stop, then force - Sends a shutdown signal and waits for the shutdown timeout (default 30 seconds) for the container. Force-kills the container if still running after the timeout expires.
• Force stop immediately - Immediately force kills the container without attempting graceful shutdown.

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 cards display information and configuration options for the selected container.

The General Info card displays container configuration details including Description, Autostart, Dataset, CPU Set, Container Time, Shutdown Timeout, Init Process command, and Capabilities Policy. Init Working Directory, Init User, and Init Group also display when configured. 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 USB Devices card displays USB devices attached to the container, allowing hardware passthrough for USB peripherals.

Add opens a list of available USB devices to attach to the container.

The GPU Devices card displays GPU hardware attached to the container for graphics or computation acceleration.

TrueNAS supports GPU passthrough for containers with the following GPU vendors:

Add opens a list of available GPU devices. GPU devices only appear in the list if:

• The physical GPU hardware is installed and detected by TrueNAS
• The NVIDIA GPU drivers are installed via System > Advanced Settings
• The GPU device is not currently allocated to another container or VM

The Filesystem Devices card displays file system mounts that provide the container with access to host directories and datasets.
File system devices allow containers to read and write data to TrueNAS datasets or host paths.

Add opens fields to configure a new file system device mount.

For existing filesystem devices, the more_vert actions menu includes options to Edit or Delete the filesystem device.

See Configuring Filesystem Devices in the Containers tutorial for configuration procedures.

The NIC Devices card displays network interfaces (NICs) attached to the container.

Each NIC displays the network interface name and MAC address in the format: {interface_name} ({mac_address}). For example: br0 (aa:bb:cc:dd:ee:ff) or br0 (Default Mac Address).

NIC modifications are restricted when there are pending network interface changes on the TrueNAS system. If the card displays a warning about pending changes, apply or revert those network changes before modifying container NICs.

Add opens a menu with available network interfaces grouped by type.

The Add/Edit NIC Device dialog configures network interface settings for the container.

Add or Update applies the NIC configuration.

For existing NICs, the more_vert actions menu provides options to Edit or Delete the NIC.

NICs can only be modified when the container is stopped.

The Tools card provides quick access to the container shell.

Shell opens a Container Shell session for command-line interaction with the container. The shell is only available when the container is running.

The Edit Container: Container screen includes most settings from the Add Container Screen except Image, Pool, and ID Map Type.

Settings available in edit mode include Name, Description, Autostart, and all Advanced Options (CPU Configuration, Time Configuration, Init Process, Environment Variables, and Capabilities).

Note that the Init Process command field cannot be changed after creation, but Init Working Directory, Init User, and Init Group remain editable.

Device, disk, network, and other settings are configured via the Containers Cards on the Containers screen.

The screen has Basic settings (Name, Description, Autostart) visible by default, with an Advanced Options button to expand additional configuration sections.

For detailed field descriptions, see the Add Container Screen section. The Edit screen uses the same fields except Image, Pool, ID Map Type, and the Init Process command (none of which can be changed after creation).

TrueNAS Enterprise

Autostart in HA Environments

In High Availability configurations, containers with autostart enabled automatically restart on the new active controller after a failover. Ensure containers have static IP addresses configured to maintain network connectivity after failover. See Containers in High Availability Environments for details.