TrueNAS CORETrueNAS CORE Nightly Development Documentation
This content follows experimental early release software. Use the Product and Version selectors above to view content specific to a stable software release.


As of TrueNAS CORE 13.3, this feature is untested and provided without support to the TrueNAS Community.

Users with a critical need to use containers or virtualization solutions in production should migrate to the tested and supported virtualization features available in TrueNAS SCALE. TrueNAS Enterprise customers can contact iXsystems to schedule a TrueNAS SCALE deployment. See CORE to SCALE Migrations for more information.

Plugins allow extending the built-in NAS services by installing additional software. A plugin is a pre-packaged application that is installed into a FreeBSD jail. The plugin jail is limited to installing and using only the plugin software.

Before getting started...
  1. Create a data pool if one does not exist. A pool must be available for plugin storage.
  2. Verify the system is connected to the internet.
  3. Go to Network > Interfaces, edit the intended plugin interface, and set Disable Hardware Offloading.

Installing a Plugin

To see the plugin catalog, go to the Plugins screen.

First time in this menu?

Going to the Jails or Plugins screen for the first time prompts you to select a location on the system for storing Jail related data.


By default, this location stores all data related to jails and plugins, including downloaded applications, data managed by the jail or plugin, and any jail snapshots.

  • Disconnecting or deleting the pool that stores jail data can result in permanent data loss!
  • Make sure you back up any critical data or snapshots that are stored in a jail before changing the storage configuration.

To change the Jails and Plugins storage location, click , select a new pool, and click CHOOSE.

Plugins Catalog
Figure 1: Plugins Catalog
I don't see anything?

If the catalog does not load:

  1. Go to Network > Global Configuration and confirm the addresses entered in Default Gateway and DNS Servers are correct.
  2. Connect to a shell session and enter ping followed by an Internet address. The output confirms the system is connected to the Internet.

Plugins are organized into two collections:

  • iXsystems maintained plugins.
  • Community for open source plugins created and maintained by the TrueNAS community.

By default, the Plugins screen shows the iXsystems-supported plugins. To view the community-supported plugins, click on Browse a Collection and select Community.

Installation Options

To install a plugin, click on the plugin icon, then Install. This example shows installing Tarsnap, a popular backup solution.

Installing the Tarsnap Plugin
Figure 2: Installing the Tarsnap Plugin

Enter a name for the plugin in Jail Name and adjust the networking settings as needed.

Most plugins default to using Network Address Translation (NAT) for their Internet connection. Select DHCP to use a dynamically-generated address. Clear the DHCP checkbox to enter static IP addresses for the plugin jail or to select NAT. Using NAT is recommended as it does not require manual configuration of multiple available IP addresses and prevents addressing conflicts on the network.

Some plugins default to DHCP as their management utility conflicts with NAT. Keep these plugins set to DHCP unless a manually configured IP address is preferred.

Plugins can take several minutes to download and install. A dialog confirms when the installation completes and shows any post-install notes. You can view the post-install notes later by expanding the entry for the installed plugin in Plugins and clicking Post Install Notes.


If a plugin download or update fails with an unable to fetch an artifact or download a package error, you might need to investigate your networking environment. Some home routers can have a security feature that prevent DHCP enabled plugins (or bridged devices with virtual MAC addresses) from resolving addresses.

Also, sometimes additional DNS validation is required that is not supported by the router or the router has a caching resolver that is holding on to a stale record. A couple of possible solutions are to hard reset your router to clear any stale records or try using an alternate DNS server for the plugin.

S3 Secret Keys

If the plugin requires an S3 secret key, and you use a random password generation program, check the character string produced for disallowed characters. The AWS secret key allows using upper and lowercase alphanumeric characters (a-z, A-Z, digits 0-9), and the exclamation point (!), hypen (-), underscore (_), period (.), asterisk (*), single quote (’), open parenthesis ((), and closed parenthesis ()) special characters. If the random password includes other special characters it can result in failed authentication.

Post-Installation Configuration

After a plugin is installed, the Plugins screen shows the added entry.

Plugins List With Installed
Figure 3: Plugins List With Installed

Click to manage the plugin state, update the plugin application, configure the plugin jail mount points to storage datasets, and, when supported, open a link to the management portal for the plugin application.

Plugin jails are preconfigured and require very little tuning. However, jail properties are available in the event a setting needs to change. To update or reconfigure the plugin jail, go to the Jails screen and expand the entry for one of the plugin jails. Click   and stop the jail before changing it.

Installed Plugin Options
Figure 4: Installed Plugin Options

Removing a Plugin

Uninstalling a plugin destroys all datasets or snapshots that are associated with the plugin!

Back up any important data stored in the plugin jail before deleting it!

Backing up Jail Data

To find data stored in a jail, go to Storage > Pools and expand the entry for the pool that stores plugin and jail data. Expand the iocage and jails datasets to find the plugin jail storage dataset.

Storage Pools Jails Dataset Location
Figure 5: Storage Pools Jails Dataset Location

One option to back up stored data is to create a local replication. You can configure the replication task to run periodically and automatically back up new changes to the jail dataset.

To convert a jail snapshot into a new storage dataset, go to Storage > Snapshots and find a snapshot of the jail dataset.

Storage Snapshots Jails Location
Figure 6: Storage Snapshots Jails Location

Expand the snapshot entry, click , and define the path and name of the new dataset to create from the snapshot. Then go to Storage > Pools, open the for the new dataset, and click Promote Dataset.

Uninstalling a Plugin

To remove a plugin, go to Plugins, expand the installed plugin entry, and click . Confirm the plugin removal by typing in the name of the plugin jail and selecting Confirm.

Plugins Uninstall
Figure 7: Plugins Uninstall

Uninstalling can take a few moments while the plugin is deleted from both Plugins and Jails. The plugin dataset also deletes from POOL/iocage/jails/ and any jail snapshots from Storage > Snapshots.


  • MinIO Plugin: Describes how to configure the MinIO plugin on TrueNAS CORE and gives migration instructions from the deprecated S3 built-in service.

    • Plex Plugin: Describes how to install the Plex application as a plugin on TrueNAS CORE.

      • Custom Plugins: Describes how to configure plugins on TrueNAS CORE.