(408) 943-4100               V   Commercial Support

Custom Plugins

  6 minute read.

Last Modified 2021-03-26 09:17 EDT

Plugins are a technology for easily and securely deploying 3rd party applications directly on TrueNAS storage systems. The web interface allows users to deploy, start, stop, and update applications, along with configuration tasks such as assigning storage to them. Plugins are popular for content, security, development, collaboration, and backup applications for home and business use.

This feature is only supported by the TrueNAS CORE community.

Jails form the core of TrueNAS plugins. Jails are the FreeBSD container technology and are:

  • resource efficient
  • secure
  • flexible with networking infrastructure

Additionally, TrueNAS integrates the iocage application for its jail container management framework.

Each of the most popular TrueNAS plugins such as Plex Media Server, NextCloud, and SyncThing begin as FreeBSD ports: multimedia/plexmediaserver/, deskutils/nextcloudclient/, and net/syncthing/ respectively. These install to a FreeBSD system using the pkg package manager. For example, FreeBSD uses pkg install plexmediaserver and then configures the application manually.

This tutorial guides you through creating a custom plugin using the SABnzbd newsreader plugin as an example. A plugin adds metadata that provides an installation source, reasonable defaults, and user interface elements such as an icon. The components for the sabnzbd plugin are:

  • README.md: A popular convention for a file in markdown format for describing the project.
  • sabnzbd.json: The JSON “Artifact” file containing various plugin properties including an inventory of all other metadata components which may be in the same or a remote repo.
  • overlay/: An optional directory containing the files to be copied into the Jail.
  • ui.json: A file containing the plugin management interface URL and port number.
  • settings.json: An optional JSON file that contains variables used during plugin startup and for its configuration.
  • sabnzbd.png: A .png image such as sabnzbd.png that will appear in the TrueNAS plugins Index. It is used as the icon.
  • post_install.sh: A shell script ran after jail creation to perform necessary configuration steps. It runs only once.

Requirements

TrueNAS provides everything necessary for custom plugin development, but a FreeBSD system is also a good choice. The requirements are:

  • A TrueNAS or FreeBSD system running iocage.
  • An internet connection and at least 1 GiB of available disk space.
  • A publicly-accessible git repository, self-hosted or on a service like GitHub, Gitea or GitLab. GitLab can be run as its own plugin.
  • A text editor such as vi, ee, or nano, all of which are available in TrueNAS.
  • Basic knowledge of FreeBSD and shell scripting.

Creating Each Component

// and # comments are not supported in JSON. Copy any examples from the files in the Git repo using “raw” mode.

sabnzbd.json (artifact file)

{
  "name": "sabnzbd",                //The name of the Plugin and resulting Jail
  "plugin_schema": "2",             //The Plugin schema version
  "release": "11.3-RELEASE",        //FreeBSD version (not significantly newer than host)
  "artifact": "https://github.com/ConorBeh/iocage-plugin-sabnzbd.git",      //The Git repo containing the Plugin
  "properties": {                   //Jail properties that can be overridden by the user
    "nat": 1,
    "nat_forwards": "tcp(8080:8080)"
  },
  "pkgs": [                 //FreeBSD packages to be installed, one per line
    "sabnzbdplus",
  ],
  "packagesite": "https://pkg.FreeBSD.org/FreeBSD:11:amd64/latest",          //The package site, latest, quarterly, or self-hosted
  "fingerprints": {
    "iocage-plugins": [
      {
        "function": "sha256",
        "fingerprint": "b0170035af3acc5f3f3ae1859dc717101b4e6c1d0a794ad554928ca0cbb2f438"       //The checksum of the FreeBSD port
      }
    ]
  },
  "revision": "0"       //Internal version number
}

Artifact File Properties

These are commonly-used properties specified in the artifact file. Any supported iocage property can be specified. Here are a few:

  • nat: Enables Network Address Translation to utilize the host’s IP address.
  • nat_forwards: Required when NAT is enabled. Syntax: < protocol > ( < jailport >:< hostport > )
  • dhcp: Enables DHCP on the jail to allow it to automatically obtain an IP address.
  • allow_tun: Allows the creation of a tun network device inside the jail, required for VPN connections.
  • allow_raw_sockets: Allows the jail to create raw sockets.

Artifact Repository Options

The official FreeBSD repository provides latest and quarterly branches. The latest branch contains binary packages that are updated immediately, while the quarterly branch binaries are only updated every quarter, and are the default for FreeBSD releases. The fingerprint remains the same for all official FreeBSD repositories. If custom port build options are required, the preferred solution is to set up a custom Poudriere build server.

overlay/

The overlay/ is a directory of files copied into the jail after creation and before the execution of post_install.sh. The layout of these files follows the same paths as in the root jail filesystem. For example, a file placed in /overlay/usr/local/www/lighttpd/ inside the Git repo goes into /usr/local/www/lighttpd in the jail. This is very useful for providing pre-made configuration files, additional scripts, or even binaries that might not be available in the pkg repository.

ui.json

This is a small JSON file containing the address of the WebUI and port. Use the variable %%IP%% to automatically display the correct IP address. Make sure to include any extra components in the URL following the domain name or IP address, for example /admin or /web/index.

settings.json

A JSON file that is used when working with generated or user-specified data such as passwords or database names. These variables can be used in post_install.sh. In addition to these variables the servicerestart command must also be set. This command runs when a setting changes or the jail restarts, like a web server restart.

sabnzbd.png (Icon File)

A link to a .png file to show in the TrueNAS Plugins Index. The image requires a transparent background and must be 128 pixel by 128 pixel square in size to produce quality results when automatically resized.

post_install.sh

A POSIX shell script that leverages all other files to automate plugin installation. Simple plugins typically only have a few lines in this file, to enable and start a few services. Note that iocage executes the file contents simultaneously, not line by line. Remember to make the file executable before uploading it to the Git repository.

To make post_install.sh executable, enter chmod +x post_install.sh.

Common post-installation steps include:

  • Setting file and directory permissions
  • Moving, copying, and editing configuration files
  • Generating random passwords
  • Adding a user and/or group
  • Creating a database

/root/PLUGIN_INFO

A text file with easily accessible information which can be recalled again from the web interface by clicking Post Install Notes. Information can be entered into this file using echo {information/notes} >> /root/PLUGIN_INFO in post_install.sh, where {information/notes} is the relevant information about the plugin.

Git Repository Initialization

Create and initialize a Git repository and README for the plugin. Use this naming schema iocage-plugin-{PLUGIN_NAME}. For example, iocage-plugin-sabnzbd is the name of the Github repo in this example.

Put all the necessary files and directories in the newly created artifact repo. The necessary files are listed above. Next, open a pull request to the plugin hub index that adds the artifact file, icon, and entry into the INDEX file. Remember to put a link to your newly created artifact repo in the comments of the pull request. This way a moderator can fork your repo and it can be made available in the community list of plugins.

For guides on how to use Github, see Github Guides.