Note

This is a TrueNAS® licensed feature only. For assistance, please contact iX Support:

Contact Method Contact Options
Web https://support.ixsystems.com
Email support@iXsystems.com
Telephone

Monday - Friday, 6:00AM to 6:00PM Pacific Standard Time:

  • US-only toll-free: 855-473-7449 option 2
  • Local and international: 408-943-4100 option 2
Telephone

After Hours (24x7 Gold Level Support only):

  • US-only toll-free: 855-499-5131
  • International: 408-878-3140 (international calling rates will apply)

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 Plugins.

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 Network ➞ Global Configuration.

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 or 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.

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 Plugins page as shown in Figure 13.1.1.

Note

Plugins are also added to Jails 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.

_images/plugins-available.png

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 Jails page and add storage as described in Additional Storage.

Click  (Options) and Shell for the plugin jail in the Jails 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 Jail 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.

_images/plugins-update.png

Fig. 13.2.1 Updating a 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.

_images/plugins-delete-example.png

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-Operator interface to manage the plugin DS-System service. Click Management in the plugin options to open the DS-Operator interface.
  • DS-Client Installation Guide: How to install the DS-Client system. DS-Client aggregates backup content from endpoints and transmits it to the DS-System service.
  • DS-Client Management Guide: Managing the DS-Client system after it has been successfully installed at one or more locations.