12. Plugins — FreeNAS®11.2-BETA1 User Guide Table of Contents

# 12. 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 GUI. This method is easy to use, but provides a limited amount of available software. Each plugin is automatically installed into its own FreeBSD jail.

Jails provide more control over software installation but require 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 that application’s needs.

## 12.1. Install

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

- the FreeNAS® GUI provides a browser for viewing the list of available plugins
- the FreeNAS® GUI provides buttons for installing, starting, managing, and deleting plugins
- if the plugin has configuration options, a screen will be added to the FreeNAS® GUI for these options to be configured

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

Fig. 12.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/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 Save. In the example shown in Figure 12.1.2, Plex Media Server is selected for installation.

Fig. 12.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. It then installs the plugin and adds it to the Plugins ‣ Installed page as shown in Figure 12.1.3.

Tip

Installed plugins are also added to the Jails page. This page is also used to manage installed software.

Fig. 12.1.3 Viewing Installed Plugins

The entry in the Plugins ‣ Installed section displays the plugin name, boot status, state, release, IP4 and IP6 addresses, and whether it is a template.

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

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.

## 12.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.

## 12.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 12.3.1, Quasselcore has been installed and the Delete button has been clicked. A pop-up message asks the user if they are sure that they want to delete. This is the only warning. The plugin and the associated jail are permanently deleted when Confirm is set and Delete is clicked.

Fig. 12.3.1 Deleting an Installed Plugin

## 12.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 12.4.1 for the files to add to the artifact repository.

Table 12.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 subection 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 12.4.2 lists and describes each required entry.

Table 12.4.2 Plugin json File Contents
Data Field | Description
--- | ---
`"name":` | Name of the plugin.
`"release":` | FreeBSD release to use for the plugin jail.
`"artifact":` | URL of the plugin artifact repo.
`"pkgs":` | Port of the plugin.
`"packagesite":` | 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 repo. Default is 226efd3a126fb86e71d60a37353d17f57af816d1c7ecad0623c21f0bf73eb0c7
`"official":` | Defines if this an official iXsystems supported plugin. Enter true or false.

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 newly created `plugin.json` file here.
- “name”: Use the same name from 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”: Add any notes about the plugin.
- “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.

## 12.5. Official Plugins

table 12.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 12.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’s 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.
BitTorrentSync | Resilient, fast and scalable file sync software for enterprises and individuals.
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.
Nextcloud | Access, share and protect files, calendars, contacts, communication & 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.
SickRage | Automatic Video Library Manager for TV Shows.
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.
TinyTinyRSS | Open source web-based news feed (RSS/Atom) aggregator, designed to allow reading news from any location.
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

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