15. Plugins¶

FreeNAS^® 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 FreeNAS^®. This means having a suitable pool created to store plugins.

15.1. Installing Plugins¶

A plugin is a self-contained application installer designed to integrate into the FreeNAS^® web interface. A plugin offers several advantages:

the FreeNAS^® web interface provides a browser for viewing the list of available plugins
the FreeNAS^® web interface provides buttons for installing, starting, managing, and uninstalling plugins
if the plugin has configuration options, a management screen is added to the FreeNAS^® web interface for these options to be configured

View available plugins by clicking Plugins.

Figure 15.1.1 shows some of the available plugins.

Fig. 15.1.1 Viewing the List of Available Plugins

Note

If the list of available plugins is not displayed, open Shell and verify that the FreeNAS^® 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 Browse a Collection to toggle the plugins list between iXsystems plugins, which receive updates every few weeks, and Community plugins.

Click REFRESH INDEX to refresh the current list of plugins.

Click a plugin icon to see the description, whether it is an Official or Community plugin, the version available, and the number of installed instances.

To install the selected plugin, click INSTALL.

Fig. 15.1.2 Installing the Plex Plugin

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

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.

Fig. 15.1.3 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 FreeNAS^® 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.

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

15.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 15.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. 15.3.1 Uninstalling a Plugin and its Associated Jail and Dataset

15.4. Create a Plugin¶

If an application is not available as a plugin, it is possible to create a new plugin for FreeNAS^® in a few steps. This requires an existing GitHub account.

Create a new artifact repository on GitHub.

Refer to table 15.4.1 for the files to add to the artifact repository.

Table 15.4.1 FreeNAS^® Plugin Artifact Files¶
Directory/File	Description
`post_install.sh`	This script is run inside the jail after it is created and any packages installed. Enable services in `/etc/rc.conf` that need to start with the jail and apply any configuration customizations with this this script.
`ui.json`	JSON file that accepts the key or value options. For example: `adminportal: "http://%%IP%%/"` designates the web-interface of the plugin.
`overlay/`	Directory of files overlaid on the jail after install. For example, `usr/local/bin/myfile` is placed in the `/usr/local/bin/myfile` location of the jail. Can be used to supply custom files and configuration data, scripts, and any other type of customized files to the plugin jail.
`settings.json`	JSON file that manages the settings interface of the plugin. Required fields include: `"servicerestart" : "service foo restart"` Command to run when restarting the plugin service after changing settings. `"serviceget" : "/usr/local/bin/myget"` Command used to get values for plugin configuration. Provided by the plugin creator. The command accepts two arguments for key or value pair. `"options" :` This subsection contains arrays of elements, starting with the “key” name and required arguments for that particular type of setting. See options subsection example below.

This example settings.json file is used for the Quasselcore plugin. It is also available online in the iocage-plugin-quassel artifact repository.

{
        "servicerestart":"service quasselcore restart",
        "serviceget": "/usr/local/bin/quasselget",
        "serviceset": "/usr/local/bin/quasselset",
        "options": {
                "adduser": {
                        "type": "add",
                        "name": "Add User",
                        "description": "Add new quasselcore user",
                        "requiredargs": {
                                "username": {
                                        "type": "string",
                                        "description": "Quassel Client Username"
                                },
                                "password": {
                                        "type": "password",
                                        "description": "Quassel Client Password"
                                },
                                "fullname": {
                                        "type": "string",
                                        "description": "Quassel Client Full Name"
                                }
                        },
                        "optionalargs": {
                                "adminuser": {
                                        "type": "bool",
                                        "description": "Can this user administrate quasselcore?"
                                }
                        }
                },
                "port": {
                        "type": "int",
                        "name": "Quassel Core Port",
                        "description": "Port for incoming quassel connections",
                        "range": "1024-32000",
                        "default": "4242",
                        "requirerestart": true
                },
                "sslmode": {
                        "type": "bool",
                        "name": "SSL Only",
                        "description": "Only accept SSL connections",
                        "default": true,
                        "requirerestart": true

                },
                "ssloption": {
                        "type": "combo",
                        "name": "SSL Options",
                        "description": "SSL Connection Options",
                        "requirerestart": true,
                        "default": "tlsallow",
                        "options": {
                                        "tlsrequire": "Require TLS",
                                        "tlsallow": "Allow TLS",
                                        "tlsdisable": "Disable TLS"
                        }
                },
                "deluser": {
                        "type": "delete",
                        "name": "Delete User",
                        "description": "Remove a quasselcore user"
                }

        }
}

Create and submit a new JSON file for the plugin:

Clone the iocage-plugin-index GitHub repository.

Tip

Full tutorials and documentation for GitHub and git commands are available on GitHub Guides.

On the local copy of iocage-plugin-index, create a new JSON file for the FreeNAS^® plugin. The JSON file describes the plugin, the packages it requires for operation, and other installation details. This file is named pluginname.json. For example, the Madsonic plugin is named madsonic.json.

The fields of the file are described in table 15.4.2.

Table 15.4.2 Plugin JSON File Contents¶
Data Field	Description
`"name":`	Name of the plugin.
`"plugin_schema":`	Optional. Enter 2 if simplified post-install information has been supplied in `post_install.sh`. After specifying 2, echo the information to be presented to the user in `/root/PLUGIN_INFO` inside the `post_install.sh` file. See the rslsync.json and rslsync post_install.sh examples.
`"release":`	FreeBSD RELEASE to use for the plugin jail.
`"artifact":`	URL of the plugin artifact repository.
`"pkgs":`	The FreeBSD packages required by the plugin.
`"packagesite":`	Content Delivery Network (CDN) used by the plugin jail. Default for the TrueOS CDN is `http://pkg.cdn.trueos.org/iocage`.
`"fingerprints":`	`"function":` Default is `sha256`. `"fingerprint":` The pkg fingerprint for the artifact repository. Default is `226efd3a126fb86e71d60a37353d17f57af816d1c7ecad0623c21f0bf73eb0c7`
`"official":`	Define whether this is an official iXsystems-supported plugin. Enter `true` or `false`.

Listing 15.4.1 rslsync.json¶

{
  "name": "rslsync",
  "plugin_schema": "2",
  "release": "11.2-RELEASE",
  "artifact": "https://github.com/freenas/iocage-plugin-btsync.git",
  "pkgs": [
    "net-p2p/rslsync"
  ],
  "packagesite": "http://pkg.cdn.trueos.org/iocage/unstable",
  "fingerprints": {
          "iocage-plugins": [
                  {
                  "function": "sha256",
                  "fingerprint": "226efd3a126fb86e71d60a37353d17f57af816d1c7ecad0623c21f0bf73eb0c7"
          }
          ]
  },
  "official": true
}

Listing 15.4.2 post_install.sh¶

#!/bin/sh -x

# Enable the service
sysrc -f /etc/rc.conf rslsync_enable="YES"
# Start the service
service rslsync start 2>/dev/null

echo "rslsync now installed" > /root/PLUGIN_INFO
echo "foo" >> /root/PLUGIN_INFO

Here is quasselcore.json reproduced as an example:

{
  "name": "Quasselcore",
  "release": "11.1-RELEASE",
  "artifact": "https://github.com/freenas/iocage-plugin-quassel.git",
  "pkgs": [
    "irc/quassel-core"
  ],
  "packagesite": "http://pkg.cdn.trueos.org/iocage",
  "fingerprints": {
          "iocage-plugins": [
                  {
                  "function": "sha256",
                  "fingerprint": "226efd3a126fb86e71d60a37353d17f57af816d1c7ecad0623c21f0bf73eb0c7"
          }
          ]
  },
  "official": true
}

The correct directory and package name of the plugin application must be used for the "pkgs": value. Find the package name and directory by searching FreshPorts and checking the “To install the port:” line. For example, the Quasselcore plugin uses the directory and package name /irc/quassel-core.

Now edit iocage-plugin-index/INDEX. Add an entry for the new plugin that includes these fields:

"MANIFEST": Add the name of the newly created plugin.json file here.
"name": Use the same name used within the .json file.
"icon": Most plugins will have a specific icon. Search the web and save the icon to the iocage-plugin-index/icons/ directory as a .png. The naming convention is pluginname.png. For example, the Madsonic plugin has the icon file madsonic.png.
"description": Describe the plugin in a single sentence.
"official": Specify if the plugin is supported by iXsystems. Enter false.

See the INDEX for examples of INDEX entries.

Submit the plugin

Open a pull request for the iocage-plugin-index repo. Make sure the pull request contains:

the new plugin.json file.
the plugin icon .png added to the iocage-plugin-index/icons/ directory.
an update to the INDEX file with an entry for the new plugin.
a link to the artifact repository populated with all required plugin files.

15.4.1. Test a Plugin¶

Warning

Installing experimental plugins is not recommended for general use of FreeNAS^®. This feature is meant to help plugin creators test their work before it becomes generally available on FreeNAS^®.

Plugin pull requests are merged into the master branch of the iocage-plugin-index repository. These plugins are not available in the web interface until they are tested and added to a RELEASE branch of the repository. It is possible to test an in-development plugin by using this iocage command: iocage fetch -P --name PLUGIN IPADDRESS_PROPS --branch 'master'

This will install the plugin, configure it with any chosen properties, and specifically use the master branch of the repository to download the plugin.

Here is an example of downloading and configuring an experimental plugin with the FreeNAS^® Shell:

[root@freenas ~]# iocage fetch -P --name mineos ip4_addr="em0|10.231.1.37/24" --branch 'master'
Plugin: mineos
  Official Plugin: False
  Using RELEASE: 11.2-RELEASE
  Using Branch: master
  Post-install Artifact: https://github.com/jseqaert/iocage-plugin-mineos.git
  These pkgs will be installed:
...

...
Running post_install.sh
Command output:
...

...
Admin Portal:
http://10.231.1.37:8443
[root@freenas ~]#

This plugin appears in the Jails and Plugins screens as mineos and can be tested with the FreeNAS^® system.

15.5. Asigra Plugin¶

The Asigra plugin connects FreeNAS^® 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 FreeNAS^® 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.