Note
This is a TrueNAS® licensed feature only. For assistance, please contact iX Support:
| Contact Method | Contact Options |
|---|---|
| Web | https://support.ixsystems.com |
support@iXsystems.com |
|
| Telephone | Monday - Friday, 6:00AM to 6:00PM Pacific Standard Time:
|
| Telephone | After Hours (24x7 Gold Level Support only):
|
13. Plugins¶
TrueNAS® provides the ability to extend the built-in NAS services by providing two methods for installing additional software.
Plugins allow the user to browse, install, and configure pre-packaged software from the web interface. This method is easy to use, but provides a limited amount of available software. Each plugin is automatically installed into its own limited FreeBSD jail that cannot install additional software.
Jails provide more control over software installation, but requires working from the command line and a good understanding of networking basics and software installation on FreeBSD-based systems.
Look through the Plugins and Jails sections to become familiar with the features and limitations of each. Choose the method that best meets the needs of the application.
Note
Jail Storage must be configured before plugins are available on TrueNAS®. This means having a suitable pool created to store plugins.
13.1. Installing Plugins¶
A plugin is a self-contained application installer designed to integrate into the TrueNAS® web interface. A plugin offers several advantages:
- the TrueNAS® web interface provides a browser for viewing the list of available plugins
- the TrueNAS® web interface provides buttons for installing, starting, managing, and uninstalling plugins
- if the plugin has configuration options, a management screen is added to the TrueNAS® web interface for these options to be configured
View available plugins by clicking .
Note
If the list of available plugins is not displayed, open Shell and verify that the TrueNAS® system can ping an address on the Internet. If it cannot, add a default gateway address and DNS server address in .
Click REFRESH INDEX to refresh the current list of plugins.
Click a plugin icon to see the description, whether it is an Official plugin, the version available, and the number of installed instances.
To install the selected plugin, click INSTALL.
Note
A warning will display when an unofficial plugin is selected for installation.
Enter a Jail Name. A unique name is required, since
multiple installations of the same plugin are supported. Names can
contain letters, numbers, periods (.), dashes (-),
and underscores (_).
Most plugins default to NAT. This setting 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 manually configuring an IP address is preferred.
If both NAT and DHCP are unset, an IPv4 or IPv6 address can be manually entered. If desired, an IPv4 or IPv6 interface can be selected. If no interface is selected the jail IP address uses the current active interface. The IPv4 or IPv6 address must be in the range of the local network.
Click ADVANCED PLUGIN INSTALLATION to show all options for the plugin jail. The options are described in Advanced Jail Creation.
To start the installation, click SAVE.
Depending on the size of the application, the installation can take several minutes to download and install. A confirmation message is shown when the installation completes, along with any post-installation notes.
Installed plugins appear on the page as shown in Figure 13.1.1.
Note
Plugins are also added to as a pluginv2 jail. This type of jail is editable like a standard jail, but the UUID cannot be altered. See Managing Jails for more details about modifying jails.
Fig. 13.1.1 Viewing Installed Plugins
Plugins are immediately started after installation. By default, all plugins are started when the system boots. Unsetting Boot means the plugin will not start when the system boots and must be started manually.
In addition to the Jail name, the Columns menu can be used to display more information about installed Plugins.
More information such as RELEASE and VERSION is shown by clicking (Expand). Options to RESTART, STOP, UPDATE, MANAGE, and UNINSTALL the plugin are also displayed. If an installed plugin has notes, the notes can be viewed by clicking POST INSTALL NOTES.
Plugins with additional documentation also have a DOCUMENTATION button which opens the README in the plugin repository.
The plugin must be started before the installed application is
available. Click (Expand) and START. The plugin
Status changes to up when it starts successfully.
Stop and immediately start an up plugin by clicking
(Expand) and RESTART.
Click (Expand) and MANAGE to open a management or configuration screen for the application. Plugins with a management interface show the IP address and port to that page in the Admin Portal column.
Note
Not all plugins have a functional management option. See Managing Jails for more instructions about interacting with a plugin jail with the shell.
Some plugins have options that need to be set before their service will successfully start. Check the website of the application to see what documentation is available. If there are any difficulties using a plugin, refer to the official documentation for that application.
If the application requires access to the data stored on the TrueNAS® system, click the entry for the associated jail in the page and add storage as described in Additional Storage.
Click (Options) and Shell for the plugin jail in the page. This will give access to the shell of the jail containing the application to complete or test the configuration.
If a plugin jail fails to start, open the plugin jail shell from the page and type tail /var/log/messages to see if any errors were logged.
13.2. Updating Plugins¶
When a newer version of a plugin or release becomes available in the official repository, click (Expand) and UPDATE. Updating a plugin updates the operating system and version of the plugin.
Fig. 13.2.1 Updating a Plugin
Updating a plugin also restarts that plugin. To update or upgrade the plugin jail operating system, see Jail Updates and Upgrades.
13.3. Uninstalling Plugins¶
Installing a plugin creates an associated jail. Uninstalling a plugin deletes the jail because it is no longer required. This means all datasets or snapshots that are associated with the plugin are also deleted. Make sure to back up any important data from the plugin before uninstalling it.
Figure 13.3.1 shows an example of uninstalling a plugin by expanding the plugin’s entry and clicking UNINSTALL. A two-step dialog opens to confirm the action. This is the only warning. Enter the plugin name, set the Confirm checkbox, and click DELETE to remove the plugin and the associated jail, dataset, and snapshots.
Fig. 13.3.1 Uninstalling a Plugin and its Associated Jail and Dataset
13.4. Asigra Plugin¶
The Asigra plugin connects TrueNAS® to a third party service and is subject to licensing. Please read the Asigra Software License Agreement before using this plugin.
To begin using Asigra services after installing the plugin, open the plugin options and click Register. A new browser tab opens to register a user with Asigra.
The TrueNAS® system must have a public static IP address for Asigra services to function.
Refer to the Asigra documentation for details about using the Asigra platform:
- DS-Operator Management Guide:
Using the
DS-Operatorinterface to manage the pluginDS-Systemservice. Click Management in the plugin options to open theDS-Operatorinterface. - DS-Client Installation Guide:
How to install the
DS-Clientsystem.DS-Clientaggregates backup content from endpoints and transmits it to theDS-System service. - DS-Client Management Guide:
Managing the
DS-Clientsystem after it has been successfully installed at one or more locations.