Resource icon

Create an unofficial iocage plugin

Joined
Jul 10, 2016
Messages
521
Jurgen Segaert submitted a new resource:

Create an unofficial iocage plugin - This resource will walk you through the process of setting up an iocage plugin

Scope
This resource will walk you through the process of setting up an iocage plugin. The intent is to familiarize people with the basic layout of an iocage plugin, so that they start building plugins and contribute to them community. :)

Note that there’s way more to plugins that is mentioned in this document. For more information, please refer to the official documentation: https://doc.freenas.org/11.2/plugins.html#create-a-plugin...

Read more about this resource...
 

Ericloewe

Server Wrangler
Moderator
Joined
Feb 15, 2014
Messages
20,175
Awesome, sounds nice and simple, as it should be.
 

Ericloewe

Server Wrangler
Moderator
Joined
Feb 15, 2014
Messages
20,175
Sounds pretty easy to me, although I haven't taken the dive that is needed to determine where all the sharp corners lie...
 

danb35

Hall of Famer
Joined
Aug 16, 2011
Messages
15,462
One issue will be interacting with the user to gather needed information, and present stuff to the user. My script needs to know a FQDN for the jail (since it gets a cert from Let's Encrypt for the jail), and it needs to let the user know what the randomly-generated default admin password is. It also needs to determine its time zone, though it might be possible to retrieve that from FreeNAS itself...
 

Ericloewe

Server Wrangler
Moderator
Joined
Feb 15, 2014
Messages
20,175
I think that iocage includes the functionality required to expose those parameters in the FreeNAS GUI.
 

GaroRobe

Dabbler
Joined
Dec 16, 2017
Messages
12
I think that iocage includes the functionality required to expose those parameters in the FreeNAS GUI.

That's the issue I encountered - the functionality is documented (well, kinda...) and even coded (e.g. in quasselcore or redmine - settings.json). But I absolutely don't see any way to utilize those in UI.
It's either still not implemented or I'm just slow.

And personally, I'd prefer the later - I'm really eager to make UI-configurable reverse proxy. So far it's probably the most tedious thing to make and I reckon there should be other guys beside me who enjoy proper domain names for home services.
 
Joined
Jul 10, 2016
Messages
521
That's the issue I encountered - the functionality is documented (well, kinda...) and even coded (e.g. in quasselcore or redmine - settings.json). But I absolutely don't see any way to utilize those in UI.
It's either still not implemented or I'm just slow.

I also haven't seen this functionality show anywhere in the UI; it seems very promising but I don't think this is implemented yet. :(
 

GaroRobe

Dabbler
Joined
Dec 16, 2017
Messages
12
I also haven't seen this functionality show anywhere in the UI; it seems very promising but I don't think this is implemented yet. :(

If I may, there is another topic that's pretty underdocumented (and would be nice to mention in tutorial) - plugin update. Namely:

1. Logic/algorithm - e.g. it's completely opaqueto me how does FreeNAS/iocage determines available version upgrades (artifact repo hash?) or even how to implement version numeration for plugin (and if it's even supported for 3rd party stuff)
2. Guidelines (actually, should be in official docs - or did I miss them again?)
3. Best/worst practices (consequences for added/removed/installed packages, postinstall scripts reentrancy, permissions, overlays collision etc.)

Could you answer those or direct me to the answers?

P.S.: By the by, do you know anything about how ui.json works? What keys are expected and if I could bind my own actions to new ones?
 
Last edited:
Joined
Jul 10, 2016
Messages
521
If I may, there is another topic that's pretty underdocumented (and would be nice to mention in tutorial) - plugin update.

Yeah, the only item in the documentation with regard to updating plugins is this:
Code:
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.
Updating plugins does deserve a section in the resource, so I'll add something. I don't have any inside information; all I know comes from testing and browsing the source code.

1. Logic/algorithm - how does FreeNAS/iocage determines available version upgrades
It looks like this is done in the FreeNAS middleware:
If anybody is has formal more documentation, guidelines or best/worst practices, please do post. :)
 

Apolitosz

Cadet
Joined
Oct 31, 2015
Messages
5
Great writeup, thanks for putting it together.

Two questions:
- I was wondering if it would be possible to have the files necessary for the plugin installation stored somewhere where it's not publicly accessible? Ie my private GitLab repo or local files. One workaround I could think of (haven't tested) is to have github installed in an another jail and serve the files from there so those are only accessible from the LAN. The reasoning behind this, is that I would like to make some plugins just for myself (in many cases a customized version of an another official plugin, or something very specific for my use case)
- How would one prompt users during the installation of the plugin (I plan to install the plugins with CLI) to provide some parameters. Ie in case of the OpenVPN plugin (https://github.com/gitbulb/iocage-plugin-openvpn) the passphrase for the CA is hardcoded in the overlay/root/vars but can be changed with iocage set -P "ca_key_passphrase=Secret1" openvpn. Does that mean that we can provide these parameters with iocage fetch -P --name ./openvpn.json when the installation is kicked off? If not, should it be the post_install.sh which prompts for use input or that would be a bad practice in general?

Thanks,
Apolitosz
 

GaroRobe

Dabbler
Joined
Dec 16, 2017
Messages
12
Great writeup, thanks for putting it together.

Two questions:
- I was wondering if it would be possible to have the files necessary for the plugin installation stored somewhere where it's not publicly accessible? Ie my private GitLab repo or local files. One workaround I could think of (haven't tested) is to have github installed in an another jail and serve the files from there so those are only accessible from the LAN. The reasoning behind this, is that I would like to make some plugins just for myself (in many cases a customized version of an another official plugin, or something very specific for my use case)
- How would one prompt users during the installation of the plugin (I plan to install the plugins with CLI) to provide some parameters. Ie in case of the OpenVPN plugin (https://github.com/gitbulb/iocage-plugin-openvpn) the passphrase for the CA is hardcoded in the overlay/root/vars but can be changed with iocage set -P "ca_key_passphrase=Secret1" openvpn. Does that mean that we can provide these parameters with iocage fetch -P --name ./openvpn.json when the installation is kicked off? If not, should it be the post_install.sh which prompts for use input or that would be a bad practice in general?

Thanks,
Apolitosz
AFAIK, you can point artifact to any git repo. iocage most likely doesn't care. Just edit your manifest.

STILL I'd rather prefer a more customizable pre-install or post-install UI. An ability to add a textfield to enter a key would solve the issue, wouldn't it?
 
Joined
Jul 10, 2016
Messages
521
  1. For private repos, you can use the SSH syntax for your URL and login with SSH key. This was implemented a while ago, see https://redmine.ixsystems.com/issues/42653 I don't seen why a locally hosted Gitlab wouldn't work either. That being said, if you make any changes/improvements to existing plugins, why not share back with the community? ;)
    I read somewhere (can't find the link now) that there is functionality in the works to allow users to roll their own plugin repos, instead of/in addition to the official one at https://github.com/freenas/iocage-ix-plugins/
  2. You can't prompt for stuff during the post_install script. You can only echo some instructions on how to change the passphrase that will displayed in the post-install popup. I have a feature request out there to add GUI support for the iocage specific parameters (the iocage set -P "passphrase=value <jail> stuff) but for now users need to go into the jail shell and manually type this. Feel free to add a comment in the ticket https://redmine.ixsystems.com/issues/51180 as that may help prioritize development.
    To make it more user friendly for now, you could write a simple manual-post-install-config shell script that uses dialog, is deployed as part of the plugin install and should be started manually the first time after the installation.
 

danb35

Hall of Famer
Joined
Aug 16, 2011
Messages
15,462
Well, I haven't tried to move my own Nextcloud script to this style, but I am banging on the official FreeNAS Nextcloud plugin a bit. Is there an "official" way within the post_install.sh script to get the IP address of the jail? Or is it just a matter of JAIL_IP=$(ifconfig | grep inet | cut -d ' ' -f 2)?
 

Junicast

Patron
Joined
Mar 6, 2015
Messages
206
Thank you for this howto. It really helped me very much.
I have a question though:

Code:
iocage fetch -P -n tetris.json
doesn't seem to work for me. It says
Code:
/zroot/iocage/.plugins/github_com_freenas_iocage-ix-plugins_git/-n.json was not found

I need to mention I'm not on FreeNAS but on FreeBSD 12.0 which uses iocage 1.2
Those are the files I created btw:

When I instead run
Code:
iocage fetch -P webservernginx.json

the jail is being created but some weird stuff happens:

Code:
root@shared_webhost_freebsd:~/hostcage # iocage fetch -P webservernginx.json
Plugin: webservernginx
  Official Plugin: False
  Using RELEASE: 12.0-RELEASE
  Using Branch: 12.0-RELEASE
  Post-install Artifact: https://github.com/imp1sh/iocage-plugin-webservernginx.git
  These pkgs will be installed:
    - nginx-full
    - php74 php74-extensions
    - php74-composer
    - php74-gd
    - php74-json
    - php74-mbstring
    - php74-mysqli
    - php74-opcache
    - php74-openssl
    - ImageMagick6
    - php74-pecl-memcache
    - php74-xml
    - php74-zip

Testing Host DNS response to pkg.FreeBSD.org
Testing webservernginx's SRV response to pkg.FreeBSD.org
Testing webservernginx's DNSSEC response to pkg.FreeBSD.org

Installing plugin packages:
  - nginx-full...
  - php74 php74-extensions...
    - php74 php74-extensions failed to install, retry #1
    - php74 php74-extensions failed to install, retry #2
    - php74 php74-extensions failed to install, retry #3
  - php74-composer...
    - php74-composer failed to install, retry #1
    - php74-composer failed to install, retry #2
    - php74-composer failed to install, retry #3
  - php74-gd...
    - php74-gd failed to install, retry #1
    - php74-gd failed to install, retry #2
    - php74-gd failed to install, retry #3
  - php74-json...
    - php74-json failed to install, retry #1
    - php74-json failed to install, retry #2
    - php74-json failed to install, retry #3
  - php74-mbstring...
    - php74-mbstring failed to install, retry #1
    - php74-mbstring failed to install, retry #2
    - php74-mbstring failed to install, retry #3
  - php74-mysqli...
    - php74-mysqli failed to install, retry #1
    - php74-mysqli failed to install, retry #2
    - php74-mysqli failed to install, retry #3
  - php74-opcache...
    - php74-opcache failed to install, retry #1
    - php74-opcache failed to install, retry #2
    - php74-opcache failed to install, retry #3
  - php74-openssl...
    - php74-openssl failed to install, retry #1
    - php74-openssl failed to install, retry #2
    - php74-openssl failed to install, retry #3
  - ImageMagick6...
    - ImageMagick6 failed to install, retry #1
    - ImageMagick6 failed to install, retry #2
    - ImageMagick6 failed to install, retry #3
  - php74-pecl-memcache...
    - php74-pecl-memcache failed to install, retry #1
    - php74-pecl-memcache failed to install, retry #2
    - php74-pecl-memcache failed to install, retry #3
  - php74-xml...
    - php74-xml failed to install, retry #1
    - php74-xml failed to install, retry #2
    - php74-xml failed to install, retry #3
  - php74-zip...
    - php74-zip failed to install, retry #1
    - php74-zip failed to install, retry #2
    - php74-zip failed to install, retry #3

pkg error:
  - php74 php74-extensions :,php74-composer :,php74-gd :,php74-json :,php74-mbstring :,php74-mysqli :,php74-opcache :,php74-openssl :,ImageMagick6 :,php74-pecl-memcache :,php74-xml :,php74-zip :

Refusing to fetch artifact and run post_install.sh!
webservernginx had a failure
Exception: SystemExit Message: 1
Partial plugin destroyed
 
Joined
Jul 10, 2016
Messages
521
Hi Peter,

You are correct; the syntax was slightly changed in newer versions in iocage. This syntax will take effect in FreeNAS 11.3.
More information in this ticket: https://jira.ixsystems.com/browse/NAS-101625

To troubleshoot any specific issues with a plugin, I recommend to add the option --keep_jail_on_failure so that it doesn't destroy the plugin jail when something goes wrong.

Also, some of the jail's defaults are different between a standard jail and a plugin jail. In addition, those defaults have changed over time. As an example, the network settings will default to vnet=on for plugins, if you do not specify a gateway, the networking in the jail will not work and it won't be able to install packages.
 
Last edited:
Joined
Jul 10, 2016
Messages
521
For future reference: using today's defaults and syntax for iocage, you would install the example as follows:

#Using shared IP, you have to explicitly turn off VNET:
iocage fetch -P tetris.json ip4_addr="em0|192.168.0.210/24" vnet=off

# Or you can use DHCP:
iocage fetch -P tetris.json vnet=on dhcp=on
 

Junicast

Patron
Joined
Mar 6, 2015
Messages
206
Well I somehow could solve the problem on my own, sorry for bothering you. There was an error in the json file having both of the packages in one line:
Code:
php74 php74-extensions
 
Top