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 . Figure 13.1.1 shows some of the available plugins.
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 .
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.
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 page as shown in Figure 13.1.3.
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.3 Viewing Installed Plugins
The entry in the 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 page and add a 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¶
A plugin update is a fix for issues in the current plugin release. When a newer version of a plugin becomes available in the official repository, update the plugin jail by clicking (Options) and Update.
Figure 13.2.1 shows updating the Plex plugin.
Fig. 13.2.1 Updating Plex Plugin
To update or upgrade the plugin jail operating system, see Jail Updates and Upgrades
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.
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.
| 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:
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:
Command to run when restarting the plugin service after changing settings.
Command used to get values for plugin configuration. Provided by the plugin creator. The command accepts two arguments for key or value pair.
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 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
Transmission
plugin is named transmission.json.
The fields of the file are described in table 13.4.2.
| 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": |
Default is
The pkg fingerprint for the artifact repository. Default is
|
"official": |
Define whether this is an official iXsystems-supported plugin.
Enter true or false. |
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
}
|
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 createdplugin.jsonfile here."name":Use the same name used within the.jsonfile."icon":Most plugins will have a specific icon. Search the web and save the icon to theicons/directory as a.png. The naming convention ispluginname.png. For example, the Transmission plugin has the icon filetransmission.png."description":Describe the plugin in a single sentence."official":Specify if the plugin is supported by iXsystems. Enterfalse.
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.jsonfile. - the plugin icon
.pngadded to theicons/directory. - an update to the
INDEXfile 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® :
[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
and
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.
| 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.