Netify Agent Plugins

Introduction

• Plugin Types
• Agent Version Compatibility
• Plugin Loader
• Plugin Configuration
• Latest Version
• Older Versions

Netify plugins were originally introduced in version 4 as a concept to extend functionality. With version 5, the plugin framework was completely refactored. It allowed developers to:

• reduce the number of libraries and dependencies
• create a minimalist footprint for storage-constrained environments (ex. embedded devices)
• allow for a more stable core code base
• increased performance
• reduced integration time
• allowed for more flexibility

Plugin Types

There are two types of Netify plugins:

• Processor Plugins
• Sink Plugins

Processor Plugins are a type of plugin that can access the Netify Agent’s internal memory tracking each flow and performing a ‘process’ action that results in an output of a specific type of data structure. 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 of 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 projects (ex. agent and plugin code)
• Follow the advice from the Netify project and developer teams

Identifying an incompatible plugin is quite straightforward. 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.?.?.?

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.

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

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.

Latest Version

Version 5 Plugin Documentation

Older Versions

Version 4 Plugin Documentation