TrueNAS Enterprise
TrueNAS SCALE
TrueNAS CORE
Compare Editions
TrueCommand
Software Status
FreeNAS
Compare Systems
F-Series
M-Series
H-Series
R-Series
Mini Series
Download TrueNAS SCALE
Download TrueNAS CORE
Get TrueNAS Enterprise
Contact an Enterprise SpecialistTrueNAS CORE Version Documentation
This content follows the TrueNAS CORE 13.0 releases. Use the Product and Version selectors above to view content specific to different TrueNAS software or major version.
Plugin Management
6 minute read.
This feature is generally available in TrueNAS CORE and supported by the TrueNAS Community. iXsystems customers with TrueNAS Enterprise hardware and an iXsystems Support contract can contact Support about accessing these features.
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.
To see the plugin catalog, go to the Plugins screen.
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 are organized into two Collections:
- iXsystems maintained plugins
- Open Source plugins created and maintained by the TrueNAS community.
By default, the iXsystems-supported plugins are shown. To view the community-supported plugins, open Browse a Collection and select Community.
To install a plugin, click the plugin icon and Install. This example shows installing Tarsnap, a popular backup solution.
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. You use a dynamically-generated address with DHCP or define static IP addresses for the plugin jail. 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 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 following special characters: exclamation point (!), hypen (-), underscore (_), period (.), asterisk (*), single quote (’), open parenthesis ((), and closed parenthesis ()). If the random password includes other special characters it can result in failed authentication.
After a plugin is installed, the Plugins screen shows the added entry.
Click chevron_right 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.
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!
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.
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.
Expand the snapshot entry, click filter_none, and define the path and name of the new dataset to create from the snapshot. Then go to Storage > Pools, open the more_vert for the new dataset, and click Promote Dataset.
To remove a plugin, go to Plugins, expand the installed plugin entry, and click delete. Confirm the plugin removal by typing in the name of the plugin jail and selecting Confirm.
Uninstalling can take a few moments while the plugin deletes from both Plugins and Jails. The plugin dataset also deletes from POOL/iocage/jails/ and any jail snapshots from Storage > Snapshots.