How does the plugin system work? Documentation Added - WIP

Hi Tom, This is my latest , hard coded path name, but TEST as name.

 

https://raw.githubusercontent.com/petersm1/Unraid-6/master/openvpnclient.plg

 

//Peter

Get rid of this:

<FILE Name="/var/log/plugins/openvpnclient">
<INLINE>
<![CDATA[

]]>
</INLINE>
</FILE>

Plugin should not mess with anything in /var/log/plugins.  The plugin manager uses that directory to create symlinks to the plg files of installed plugins.

Other things:

- By (my) convention, only page files should start with a capital letter (in fact they have to).

- You can put base64 inline so that you don't have to bring in icons from some other url, just create them inline.

- There is the notion of "anonymous" files useful for temporary scripts.  An example of this is 'Remove script' at the end.  So for example, for your cleanup file do this:

############################################
# cleanup file
############################################
<FILE Run="/bin/bash">
<INLINE>
<![CDATA[
rm -rf /tmp/openvpn
rm -f /etc/rc.d/rc.openvpnclient
rm -rf /usr/local/emhttp/plugins/openvpnclient
rm -rf /dev/net
mkdir /dev/net
mknod /dev/net/tun c 10 200

mkdir /tmp/openvpn
mkdir /var/run/openvpn
]]>
</INLINE>
</FILE>

Nice plugin BTW!

Thanks tom,

now I see this ...

/usr/local/sbin/plugin install https://raw.githubusercontent.com/petersm1/Unraid-6/master/openvpnclient.plg 2>&1 2>&1
plugin: installing: https://raw.githubusercontent.com/petersm1/Unraid-6/master/openvpnclient.plg
plugin: skipping: /boot/packages/openvpn-2.3.2-x86_64-1.txz already exists
plugin: running: /boot/packages/openvpn-2.3.2-x86_64-1.txz

+==============================================================================
| Skipping package openvpn-2.3.2-x86_64-1 (already installed)
+==============================================================================


plugin: skipping: /boot/config/plugins/openvpnclient/device_status.png already exists
plugin: skipping: /boot/config/plugins/openvpnclient/new_config.png already exists
plugin: skipping: /boot/config/plugins/openvpnclient/information.png already exists
plugin: skipping: /boot/config/plugins/openvpnclient/openvpnclient.png already exists
plugin: running: 'anonymous'
mkdir: cannot create directory '/var/run/openvpn': File exists
plugin: run failed: /bin/bash retval: 1

That is bug in your plugin.  The /var/run/openvpn directory already exists from an earlier run.

In your cleanup script replace:

mkdir /var/run/openvpn

with:

mkdir -p /var/run/openvpn

rm -r /var/run/openvpn/*

 

Other things:

- By (my) convention, only page files should start with a capital letter (in fact they have to).

Fixed in the OP.

Tom,  Can you try?

I only change this , still no icon, bit plugin installing, now its little late, continue tomorrow ,,,,

mkdir /var/run/openvpn

with:

mkdir -p /var/run/openvpn

It works for me.  There is this in the plugin install window:

/boot/config/plugins/openvpnclient/openvpnclient.cfg: line 7: a: command not found

But I see the icons and it seems to be installed correctly.  I'm running (unreleased beta9) and did make some changes plugin code - I'll have to boot a beta8 server to verify again.

It works for me.  There is this in the plugin install window:

 

/boot/config/plugins/openvpnclient/openvpnclient.cfg: line 7: a: command not found

 

But I see the icons and it seems to be installed correctly.  I'm running (unreleased beta9) and did make some changes plugin code - I'll have to boot a beta8 server to verify again.

I just installed it on beta8 and it is working.

FYI, back in May I re-wrote my ssh plugin to take advantage of the v6 plugin structure, including the install, remove and check methods. 

 

Copy attached here in case it's helpful.

 

Also can be installed by entering https://raw.githubusercontent.com/overbyrn/unraid-v6-plugins/master/ssh.plg into the Install Extension section of the v6 Extentions WebGui.

A couple of suggestions:

Based on a post by Tom:

Other things:

- By (my) convention, only page files should start with a capital letter (in fact they have to).

/usr/local/emhttp/plugins/ssh/Ssh.page                                 # page file for webGui menu system
/usr/local/emhttp/plugins/ssh/Ssh.php                                  # webGui page code

It seems that the page file and the php have to both be exactly the same name.  I think his idea here is to insure the icons are in alphabetic order in the settings page.

Also the versioning standard seems to be year.month.day for plugins.

FYI, back in May I re-wrote my ssh plugin to take advantage of the v6 plugin structure, including the install, remove and check methods. 

 

Copy attached here in case it's helpful.

 

Also can be installed by entering https://raw.githubusercontent.com/overbyrn/unraid-v6-plugins/master/ssh.plg into the Install Extension section of the v6 Extentions WebGui.

 

A couple of suggestions:

 

Based on a post by Tom:

Other things:

- By (my) convention, only page files should start with a capital letter (in fact they have to).

 

/usr/local/emhttp/plugins/ssh/Ssh.page                                 # page file for webGui menu system
/usr/local/emhttp/plugins/ssh/Ssh.php                                  # webGui page code

 

It seems that the page file and the php have to both be exactly the same name.  I think his idea here is to insure the icons are in alphabetic order in the settings page.

 

Also the versioning standard seems to be year.month.day for plugins.

Right, if you have a php file then it has to be same name as page file only with php extension.  The page file itself, beyond the '---' separator is interpreted as "markdown", but with markdown, anything within <> tags is passed straight through (we use markdown extra).

Example, suppose you have "HelloWorld.page" like this:

Menu=Tasks
Title="Hello Word"
---
**Hello world!**

<?php
echo "Here is some php.<br>"
?>

So you don't really need separate php files.

You could do the same thing using two files like this:

HelloWorld.page:

Menu=Tasks
Title="Hello Word"
---
**Hello world!**

HelloWorld.php:

<?php
echo "Here is some php.<br>"
?>

As for versioning - yes standardizing on "YYYY.MM.DD-RR" (-RR is optional "revision").  But anything will work as long as a php strcmp() function comparing the versions of your plugin works correctly to tell newer version from older version.

Tom, thanks for the explanation. I've previously used info gleaned from the code in plgman to help understand the new plugin structure (install/remove/check, anon scripts etc).

I appreciate you're working on plugin documentation and I imagine it's low priority, but I'd be interested in anything you can share as I'm currently going through all my plugins (dropbox, ssh, btsync, beets, airvideo, lms, denyhosts, nzbget) and making them v6 compliant. It'd be great to get them right first time.

Regards,

overbyrn

After I boot up unRAID with no plugins I see this in /var/log/plugins:

total 4
-rw-r--r-- 1 root root  1 Aug 31 19:33 openvpnserver
lrwxrwxrwx 1 root root 49 Aug 31 19:33 unRAID-OS -> /usr/local/emhttp/plugins/unRAID-OS/unRAID-OS.plg

What is the openvpnserver file?  Is this correct?  It is not a symlink.

After I boot up unRAID with no plugins I see this in /var/log/plugins:

 

total 4
-rw-r--r-- 1 root root  1 Aug 31 19:33 openvpnserver
lrwxrwxrwx 1 root root 49 Aug 31 19:33 unRAID-OS -> /usr/local/emhttp/plugins/unRAID-OS/unRAID-OS.plg

 

What is the openvpnserver file?  Is this correct?  It is not a symlink.

It's leftover from a previous install of older openvpnserver plugin.

After I boot up unRAID with no plugins I see this in /var/log/plugins:

 

total 4
-rw-r--r-- 1 root root  1 Aug 31 19:33 openvpnserver
lrwxrwxrwx 1 root root 49 Aug 31 19:33 unRAID-OS -> /usr/local/emhttp/plugins/unRAID-OS/unRAID-OS.plg

 

What is the openvpnserver file?  Is this correct?  It is not a symlink.

 

It's leftover from a previous install of older openvpnserver plugin.

This is on a test server that I loaded the openvpnclient as a test.  My other server has never had that installed and it also has it.

After a clean re-boot - no plugins?  How do I get rid of it?

EDIT: After a safe mode boot:

total 4
-rw-r--r-- 1 root root  1 Aug 31 19:33 openvpnserver
lrwxrwxrwx 1 root root 49 Aug 31 19:33 unRAID-OS -> /usr/local/emhttp/plugins/unRAID-OS/unRAID-OS.plg

In the ram image?  Both files are dated the same day and time.

6b8 was released 8/31.

total 4
-rw-r--r-- 1 root root  1 Aug 31 19:33 openvpnserver
lrwxrwxrwx 1 root root 49 Aug 31 19:33 unRAID-OS -> /usr/local/emhttp/plugins/unRAID-OS/unRAID-OS.plg

 

In the ram image?  Both files are dated the same day and time.

 

6b8 was released 8/31.

I just opened the beta8 bzroot archive in 7-zip and it is there.

Yeah, my mistake, fixed in beta9.

When I am updating a plugin I want to remove the /usr/local/emhttp/plugin/ directory for my plugin before the update is applied so any changes in the files will be written.  What is the best way to do that?

When I am updating a plugin I want to remove the /usr/local/emhttp/plugin/ directory for my plugin before the update is applied so any changes in the files will be written.  What is the best way to do that?

I have figured out how to do this, but I wonder if an 'update' method would be appropriate.

When I am updating a plugin I want to remove the /usr/local/emhttp/plugin/ directory for my plugin before the update is applied so any changes in the files will be written.  What is the best way to do that?

 

I have figured out how to do this, but I wonder if an 'update' method would be appropriate.

I used a combination of check, update and install methods from /usr/local/emhttp/plugins/plgMan/plugin.

No.  This is what I am talking about:

<!--
The 'update' script.
-->
<FILE Run="/bin/bash" Method="update">
<INLINE>
rm -f -r /usr/local/emhttp/plugins/&name;
</INLINE>
</FILE>

No.  This is what I am talking about:

 

<!--
The 'update' script.
-->
<FILE Run="/bin/bash" Method="update">
<INLINE>
rm -f -r /usr/local/emhttp/plugins/&name;
</INLINE>
</FILE>

Yes, I get what you meant.  What I was meaning is that within the 'plugin' script, the general methodology looks to be that a check method is used to perform a check of the local version against remote version, the update method is used to download the later version to tmp and then subsequently calls the install method to perform the install (again).

So if you build your install method to ensure it tears down the areas you need refreshing, then calling the update method will perform an installation, creating new versions of the files where required.

You can also call multiple methods, allowing the same bash script to be used across more than one method;

<!--
The 'install' script.
-->
<FILE Name="/tmp/plugins/tmp" Run="/bin/bash" Method="install update" Type="text">
<INLINE>
if [ ! -d /tmp/plugins/builtin/&name; ]; then
  mkdir -p /tmp/plugins/builtin
  mv /usr/local/emhttp/plugins/&name; /tmp/plugins/builtin
else
  rm -r /usr/local/emhttp/plugins/&name;
fi
tar -xf /boot/config/plugins/&name;/&name;-&version;.tar.gz -C /usr/local/emhttp/plugins
mv /usr/local/emhttp/plugins/&name;-&version; /usr/local/emhttp/plugins/&name;
</INLINE>
</FILE>

No.  This is what I am talking about:

 

<!--
The 'update' script.
-->
<FILE Run="/bin/bash" Method="update">
<INLINE>
rm -f -r /usr/local/emhttp/plugins/&name;
</INLINE>
</FILE>

Yes, I get what you meant.  What I was meaning is that within the 'plugin' script, the general methodology looks to be that a check method is used to perform a check of the local version against remote version, the update method is used to download the later version to tmp and then subsequently calls the install method to perform the install (again).

 

So if you build your install method to ensure it tears down the areas you need refreshing, then calling the update method will perform an installation, creating new versions of the files where required.

 

You can also call multiple methods, allowing the same bash script to be used across more than one method;

 

<!--
The 'install' script.
-->
<FILE Name="/tmp/plugins/tmp" Run="/bin/bash" Method="install update" Type="text">
<INLINE>
if [ ! -d /tmp/plugins/builtin/&name; ]; then
  mkdir -p /tmp/plugins/builtin
  mv /usr/local/emhttp/plugins/&name; /tmp/plugins/builtin
else
  rm -r /usr/local/emhttp/plugins/&name;
fi
tar -xf /boot/config/plugins/&name;/&name;-&version;.tar.gz -C /usr/local/emhttp/plugins
mv /usr/local/emhttp/plugins/&name;-&version; /usr/local/emhttp/plugins/&name;
</INLINE>
</FILE>

So 'method="update"' works?  I couldn't get it to work.

I'm having a problem with the 'echo' text I'm trying to display in the progressFrame.  The text is showing up, but is only half visible.  Half of the text line is behind the footer.  I am using update.htm for the progressFrame.  Is there an adjustment I need to make in my HTML body to leave room for the progressFrame?

First I like to propose a simplification in the "plugin" installer script and *not* store any -stale- plugins, just forget/ignore older plugin versions. I think that is less confusing for the end-user.

Next, I would like to make a feature request to the "plugin" manager which allows plugins to be installed as "system plugin", meaning they get installed in the directory '/boot/plugins' instead of '/boot/config/plugins'.

To make this work an additional attribute can be introduced, see example below

<?xml version='1.0' standalone='yes'?>

<!DOCTYPE PLUGIN [

<!ENTITY name      "webGui">

<!ENTITY author    "Bergware">

<!ENTITY version  "3.0.0">

<!ENTITY category  "Core Functionality">

<!ENTITY pluginURL "https://raw.github.com/...">

]>

<PLUGIN  name="&name;"

        author="&author;"

        version="&version;"

        category="&category;"

        pluginURL="&pluginURL;"

        system="true">

The new attribute 'system' defaults to 'false' but can be set to 'true' to have the plugin installation changed.

This requires an update to the "plugin" installer script, for example:

  // register successful install

  // absence of "configfile" attribute indicates normal plugin; presence indicates a VM plugin

  $configfile = plugin("configfile", $plugin_file, $error);

  if ($configfile === false) {

    // Bergware change: add user or system plugin selection

    $system = plugin("system", $plugin_file, $error);

    $target = $system === false ? "/boot/config/plugins/$plugin" : "/boot/plugins/$plugin";

    if ($target != $plugin_file) copy($plugin_file, $target);

    symlink($target, "/var/log/plugins/$plugin");

First I like to propose a simplification in the "plugin" installer script and *not* store any -stale- plugins, just forget/ignore older plugin versions. I think that is less confusing for the end-user.

What do we do when, not if, there is a bug in the updated plug-in and we need to roll-back to a working version?

Or is that what you mean by forget/ignore? If so, what do you mean by "forget/ignore?

First I like to propose a simplification in the "plugin" installer script and *not* store any -stale- plugins, just forget/ignore older plugin versions. I think that is less confusing for the end-user.

 

What do we do when, not if, there is a bug in the updated plug-in and we need to roll-back to a working version?

This was my immediate thought when I read the suggestion.

If, for some unseen circumstances, the updated plugin 'breaks' someone's system, they need a way to, quickly and easily, revert to the last known good working version.