HOWTO: Plugin Development

Technical documentation
February 10, 2010

Introduction

NexentaStor plugin contains one or more debian packages. Typically, each debian package realizes a separate part of the plugin that extends functionality of the management server OR management console OR management GUI. NexentaStor open source portal presents various examples, with plugins consisting of one or more debian "parts".

The NexentaStor open source portal contains a (growing) number of open source plugins. The site has documentation as well, at: http://www.nexentastor.org/projects/site/documents

Registration not required - you can download any plugin and take a quick look. Scroll through the existing documentation first, and then clone (via Mercurial) one of the open source plugins, for instance:

Each of the above is a separate NexentaStor plugin. The first 'oracle-backup' plugin is NMC-only - that is, it "plugs" itself only into Nexenta Management Console. Note again that this website contains many more plugins; the 3 above are selected purely for illustration purposes.

Mercurial source control and management system mentioned above is a well known and popular cross-platform, distributed revision control tool for software developers. We use Mercurial to develop all our software and collaborate with partners and open source developers.

Definitions and Conventions

  • NexentaStor plugin consists of one or more debian packages
  • NexentaStor plugin may "plug" itself into NMS, NMC, NMV - or any combination of the above
  • for NMS side plugin named "myplugin", the corresponding debian package must be called "nms-myplugin"
  • NMS side plugin "myplugin" minimally consists of:
    • metafile.pm
    • Myplugin.pm
    • debian/changelog
    • debian/control
    • debian/rules
    • debian/copyright

In addition, please note:

  • metafile.pm declares version, name, and other properties common to all plugins
  • For metafile.pm - use one of the existing open source plugins and do some renaming and e-assigning
  • metafile.pm must provide construct() method - and actually construct at least the plugin's interface object
  • At software upgrade or install time, NMS side plugin installs itself under /var/lib/nza/plugins/nms on the appliance
  • At startup NMS loads and constructs all plugins it finds under /var/lib/nza/plugins/
  • Plugins that fail to initialize are discarded - NMS will run even if a given plugin fails to construct or initialize itself
  • "interface object" is a D-Bus object that extends NexentaStor Storage Appliance API (SA-API) by providing new interfaces
  • By convention, interface objects have "IPC" suffix - see open source examples
  • Interface object is normally derived from NZA::ObjectIPC - the root of the appliance's interface object hierarchy
  • Interface object may or may not use "implementation object" to implement the new APIs it provides
  • In the API declarations, API-DELEGATE-IMPL specifier means that the method is called on the implementation object, and API_EXECUTE allows the interface object itself to provide implementation

Function calls and Callbacks

All NexentaStor plugins have full access to the documented NexentaStor Storage Appliance API (SA-API). A plugin uses the API to execute direct function calls on the core appliance's software.

In the opposite direction, the plugin may optionally use callback notifications, to extend the functionality of the core appliance's software. The callbacks are placed in multiple "strategic" points inside the software; the corresponding function names are often prefixed with "before" - to indicate that the callback is invoked before certain action, and respectively "after" - to indicate that the action has just been executed.

The callbacks are documented at:

http://www.nexentastor.org/projects/site/wiki/PluginAPI

Complete list of NexentaStor commercial plugins is available here.

Getting Started

  1. Copy one of the existing plugins (see some references above)
  2. Remove all unrelated code, rename the files appropriately
  3. Add your own code
  4. Depending on the type of the plugin debian "part" (nms or nmc or nmv): copy your new files under /var/lib/nza/plugin/[nms/nmc/nmv/]
  5. Restart NMS ('svcadm restart nms')
  6. Optionally, restart NMC and/or NMV

At this point you should be able to "see" your new plugin in action.

Building Plugin

  • As NexentaStor plugins are debian packages, these are built using the dpkg-buildpackage tool
  • To build package, and include sources, use
dpkg-buildpackage -sa
  • To build only a binary package, use
dpkg-buildpackage
  • Building a package generates files with following extensions
    • .changes : This file defines all the files that make up the package, and other package metadata
    • .deb : This is the actual debian package
    • .tar.gz : This contains the sources (if -sa option was specified)
    • .dsc : Debian source control package (if -sa option was specified)

Installing and Testing Plugin

  • Your plugin package can be installed using the dpkg command. Syntax is dpkg -i ".deb file"
dpkg -i testplugin_1.2.3-build1.deb
  • If required, you will also need to install any dependencies your plugin requires
apt-get install package1 package2 ..

Depending on the type of plugin (i.e. NMC/NMS/NMV), you can now open the nexenta console, or the web interface to test your plugin's functionality.

Uploading a package to nexentastor.org repository

Uploading a package to our repository at apt.nexentastor.org is simple.

  • Install dput
apt-get install dput
  • Modify /etc/dput.cf, and change the default_host_main to nexentastor
default_host_main = nexentastor
  • In the plugin parent directory (where the .changes file is present), run dput "changesfile"
dput testplugin_1.2.3-build1.changes
  • This will upload your plugin into our incoming queue.

We will then review your plugin, and include it in the repository.

References

Downloads