Plugins

Introduction

Plugin Types

There are two types of Netify plugins:

Processor Plugins are a type of plugin that can access the Netify Agent’s internal memory tracking each individual flow and performs a ‘process’ action that results in an output of a specific type of data structures. Processor plugins are usually linked to a Sink plugin, so that the data structures that are being generated can be accessed - either locally or remotely.

Sink Plugins can be thought of as an 'output mechanism' - a way in which the data originating from a processor plugin is transported or stored.

Agent Version Compatibility

Netify plugins must adhere to version compatibility, the equivalent to an Application Binary Interface or ABI. The easiest way to avoid ABI issues is to follow these recommendations:

  • Stick to versions coming from the same source (ex. repository or private download)
  • If building from source, use the latest tagged stable release for all project (ex. agent and plugin code)
  • Follow the advice from the netify project and developer teams

Identifying an incompatible plugin is quite straight forward. On upgrading a plugin or agent, it will likely become apparent the functionality is no longer working. To confirm, use the -V flag. Any plugin with "?.?.?" is incompatible with the agent and should be upgraded or downgraded. In the example below, the HTTP sink plugin is compatible with the agent, whereas the log plugin is not. 

sudo netifyd -V
...
..
.
Sink plugins:

 sink-http: 1.0.31
    /etc/netifyd/netify-sink-http.json
    /usr/lib64/libnetify-sink-http.so.0.0.0
 sink-log: 1.0.29
    /etc/netifyd/netify-sink-log.json
    /usr/lib64/libnetify-sink-log.so.?.?.?

Installation

Instructions for installing the various plugins depend on the environment, packaging and availability/licensing. See each plugin's installation section for more details.

Plugin Loader

All plugins have an associated "loader" configuration file located in /etc/netifyd/plugins.d. You may remove the loader configuration completely - this would have the effect of not loading the plugin, however, this would be a heavy-handed means of disabling a plugin. A better method would be to set the plugin to disabled within the configuration file or rename the configlet to end in something other than .conf that would prevent the agent from initalizing the plugin.

Plugin configuration files are prefixed with a 2-digit numeric value followed by a 'dash' (ex. 10-netify-sink-log.conf). The numeric value determines the order a plugin is loaded.

The layout and contents of the plugin loader configuration share a similar structure. Below, we show an example of the Netify Sink Log plugin loader configuration file. 

[sink-log]
enable = yes
plugin_library = /usr/lib64/libnetify-sink-log.so.0.0.0
conf_filename = ${path_state_persistent}/netify-sink-log.json

Line 1, [sink-log] defines the section or 'tag' name. This tag name must be unique and can be used to chain plugins together. For example, The Netify Proc Core plugin will reference this tag in its configuration (not to be confused with the load configuration) in order to know where to send the data structures.

Failure to define unique tags will cause the agent to fail to start.

Line 2, enable determines whether the plugin gets loaded (yes) or not (no). To avoid having to edit and save this file directly, a shortcut can be executed from the CLI: 

netifyd --enable-plugin netify-sink-log       # Enables plugin
netifyd --disable-plugin netify-sink-log      # Disables plugin

Line 3, plugin_library defines the shared object library location. Under the vast majority of cases, this will not need changing from its default value.

Finally, line 4, conf_filename tells the loader for the specific tag what configuration file to use.

As previously notes, more than one instance for any given plugin can be instantiated. This can be done in one of two ways. First, two distinct loader configuration files can be created, using a unique tag in each file. Example:

Filename: /etc/netifyd/plugins.d/10-netify-sink-log.conf 
[sink-log-temp-dir]
enable = yes
plugin_library = /usr/lib64/libnetify-sink-log.so.0.0.0
conf_filename = ${path_state_persistent}/netify-sink-temp-log.json
Filename: /etc/netifyd/plugins.d/20-netify-sink-log.conf 
[sink-log-root-dir]
enable = yes
plugin_library = /usr/lib64/libnetify-sink-log.so.0.0.0
conf_filename = ${path_state_persistent}/netify-sink-root-log.json
Notice how the [tags] are unique as well as pointing to different configuration files.

Alternatively, you can place more than one configuration inside a loader.

Filename: /etc/netifyd/plugins.d/00-netify-sink-log.conf 
[sink-log-temp-dir]
enable = yes
plugin_library = /usr/lib64/libnetify-sink-log.so.0.0.0
conf_filename = ${path_state_persistent}/netify-sink-temp-log.json

[sink-log-root-dir]
enable = yes
plugin_library = /usr/lib64/libnetify-sink-log.so.0.0.0
conf_filename = ${path_state_persistent}/netify-sink-root-log.json

Plugin Configuration

Each instance of a plugin loader has its own, unique, configuration file as specified in the conf_filename directive. For more information on how to configure a plugin, see the "Configuration" section in the documentation specific to a plugin. For example, for the Sink Log plugin, click here.

Next Steps

Documentation


Netify Agent Plugins


Technical Support

Haven't found the answers you're looking for?

Contact Us