13. Plugins

Warning

This section describes the plugin system implemented in the 11.2 release of FreeNAS®. Any plugins created or installed with a previous version of FreeNAS® must be managed with the Legacy Web Interface.

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.

13.1. Install

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 deleting plugins
  • if the plugin has configuration options, a screen will be added to the FreeNAS® web interface for these options to be configured

To install a plugin, click Plugins ‣ Available. Figure 13.1.1 shows some of the available plugins.

_images/plugins-available.png

Fig. 13.1.1 Viewing the List of Available Plugins

The Available Plugins page lists the plugin name, description, current version, and whether the plugin is officially supported.

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/or DNS server address in Network ‣ Global Configuration.

Click  (Options) and Install for the desired plugin. Set DHCP to automatically configure IP settings, or manually enter an IPv4 or IPv6 address. Click ADVANCED PLUGIN INSTALLATION to show all options for the plugin jail. The options are described in Advanced Jail Creation.

Click SAVE when finished configuring the plugin jail. In the example shown in Figure 13.1.2, Plex Media Server is selected for installation.

_images/plugins-install-example.png

Fig. 13.1.2 Installing the Plex Plugin

The installation takes a few minutes because the system downloads and configures a jail to store the plugin application. A confirmation message displays at the bottom of the screen after successfully installing a plugin. When applicable, post-install notes are displayed after a successful install. Installed plugins appear in the Plugins ‣ Installed page as shown in Figure 13.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.

_images/plugins-installed.png

Fig. 13.1.3 Viewing Installed Plugins

The entry in the Plugins ‣ Installed section displays the plugin jail name, status, IPv4 and IPv6 addresses, plugin application version, and FreeBSD release.

The plugin must be started before the installed application is available. Click  (Options) and Start. The plugin Status changes to up when it starts successfully.

Stop and immediately start an up plugin by clicking  (Options) and Restart.

Click  (Options) and Management to open a management or configuration screen for the application. For example, clicking Management for an installed Plex plugin opens the Plex web interface in a new browser tab.

Note

Not all plugins have a functional management option. See Managing Jails for more instructions about interacting with a plugin jail with the shell.

Always review plugin configuration options before attempting to start it. Some plugins have options that need to be set before their service will successfully start. To help with installing a new application, check the website of the application to see what documentation is available.

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 a 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. Update

When a newer version of a plugin becomes available in the official repository, update the plugin jail by navigating to the Jails page and clicking  (Options) and Update.

An update is a fix for issues in the current release of the plugin. Plugins can be updated by running iocage update PLUGIN on the command line.

An upgrade replaces the old release with a new release. Plugins can be upgraded by running iocage upgrade PLUGIN on the command line.

13.3. Delete

Installing a plugin creates an associated jail. Deleting a plugin deletes the associated jail because it is no longer required. Before deleting a plugin, make sure that there is no data or configuration in the jail that needs to be saved. Back up that data first if needed.

In the example shown in Figure 13.3.1, plex has been installed and the Delete button has been clicked. A pop-up message asks for verification that the plugin is to be deleted. This is the only warning. The plugin and the associated jail are permanently deleted when Confirm is set and DELETE is clicked.

_images/plugins-delete-example.png

Fig. 13.3.1 Deleting an Installed Plugin

13.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 13.4.1 for the files to add to the artifact repository.

Table 13.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-ix-plugins GitHub repository.

Tip

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

On the local copy of iocage-ix-plugins, create a new file for the plugin to be added to FreeNAS®. The naming convention is pluginname.json. For example, the Transmission plugin has a .json file named transmission.json.

Add fields to this .json file. table 13.4.2 lists and describes each required entry.

Table 13.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 dependent pkgs for the plugin to work.
"packagesite": Content Delivery Network (CDN) the plugin jail uses. 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 13.4.1 rslsync.json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
  "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 13.4.2 post_install.sh
1
2
3
4
5
6
7
8
9
#!/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-ix-plugins/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 icons/ directory as a .png. The naming convention is pluginname.png. For example, the Transmission plugin has the icon file transmission.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-ix-plugins repo. Make sure the pull request contains:

  • the new plugin.json file.
  • the plugin icon .png added to the 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.

13.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-ix-plugins 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 ‣ Installed screens as mineos and can be tested with the FreeNAS® system.

13.5. Official Plugins

table 13.5.1 lists and describes all plugins supported by iXsystems. Adding “unofficial” plugins to FreeNAS® is supported by following the process outlined in Create a Plugin.

Table 13.5.1 Official FreeNAS® plugins
Name Description
BackupPC BackupPC is a high-performance, enterprise-grade system for backing up Linux, WinXX and MacOSX PCs and laptops to a server disk.
Bacula Bacula is an open-source, enterprise-level computer backup system for heterogeneous networks.
BRU Server BRU Server™ Backup and Recovery Software by TOLIS Group, Inc.
ClamAV ClamAV is an open source antivirus engine for detecting trojans, viruses, malware & other malicious threats.
CouchPotato CouchPotato is an automatic NZB and torrent downloader.
Deluge Bittorrent client using Python, and libtorrent-rasterbar.
Emby Home media server built using mono and other open source technologies.
GitLab GitLab is a fully integrated software development platform.
irssi Irssi is an IRC client.
Jenkins Jenkins is a self-contained, open source automation server which can be used to automate all sorts of tasks related to building, testing, and delivering or deploying software.
Jenkins (LTS) Jenkins Long-Term Support releases.
Madsonic Open-source web-based media streamer and jukebox.
MineOS Self-contained Minecraft server.
Nextcloud Access, share and protect files, calendars, contacts, communication and more at home and in the enterprise environment.
PlexMediaServer The Plex media server system.
Plex Media Server (PlexPass) Premium service for Plex media server system.
qBittorrent qBittorrent is a cross-platform client for the BitTorrent protocol that is released under the GNU GPL, version 2.
Quasselcore Quassel Core is a daemon/headless IRC client, part of Quassel, that supports 24/7 connectivity. Quassel Client can also be attached to it.
radarr A fork of Sonarr to work with movies in the style of Couchpotato.
Redmine Flexible project management web application.
Resilio Sync Formerly known as BitTorrent Sync. Resilient, fast and scalable file sync software for enterprises and individuals.
Sonarr PVR for Usenet and BitTorrent users.
Subsonic Open-source web-based media streamer and jukebox.
Syncthing Personal cloud sync.
Tarsnap Online encrypted backup service (client).
Transmission Fast and lightweight daemon BitTorrent client.
WeeChat WeeChat is a free and open-source Internet Relay Chat client, which is designed to be light and fast.
XMRig XMRig is a high performance Monero (XMR) CPU miner
ZoneMinder A full-featured, open source, state-of-the-art video surveillance software system.

If there are any difficulties using a plugin, refer to the official documentation for that application.