Description of plugins¶
Introduction¶
A plugin consists of software which Test Agents use to collect measurements in a network. As of Paragon Active Assurance version 3.1.0, these plugins are visible in the Control Center GUI.
Plugins are currently used mainly by Test Agent Applications; on Test Agent Appliances, only the Netflix plugin can currently run. Nonetheless, “Test Agent” will be used as a shorthand in what follows.
Note
If you have followed the installation instructions, Control Center is already equipped with all plugins needed by Test Agents. However, it is also possible to upload further plugins to Control Center, as mentioned in the section Custom plugins below.
When a Test Agent is configured in a test or monitor to run a particular plugin, the Test Agent will download it from Control Center, then configure it for measurement as specified in the test or monitor. The setup of tests and monitors in the Paragon Active Assurance GUI still works the same way, and the plugin system integrates seamlessly with it.
Notes on product versions¶
The concept of plugins was introduced overtly in Paragon Active Assurance 3.1.0.
In Paragon Active Assurance versions prior to 3.1.0, the plugins were bundled with the Test Agent Application core; however, from version 3.1.0 onward, the Test Agent downloads all plugins dynamically from Control Center.
How do plugins work?¶
A plugin comes in a file with the extension .nap. This file contains the plugin executable and any dependencies that are required to run it.
When a test or monitor is started, the Test Agent will receive a measurement configuration that tells it to start running the required plugin or plugins (in this paragraph, we assume there is only one). If the Test Agent does not have the plugin locally, it will start by downloading the plugin from Control Center over its management connection. Once the download has completed, the Test Agent will start the plugin executable as a child process, and the plugin will then be assigned its configuration parameters. Finally, the plugin will start producing metrics and events, which are uploaded to Control Center.
Each plugin has an equivalent task (for example, TCP) associated with it in the Control Center GUI.
When a task is run as part of a test or monitor, Control Center will split the task configuration into multiple measurement configurations, one for each instance of the plugin that should run on the Test Agents specified in the task configuration (that is, one measurement configuration for each Test Agent interface involved).
Plugin versions¶
Since the plugins are not tied to a particular Control Center version, and since it is possible to upload new plugins at any time, plugins need their own versioning scheme.
Note
The versions of official Paragon Active Assurance plugins will follow the Control Center version. However, this is not a general requirement.
This also means that a single Control Center can have multiple plugin versions available. However, to keep metrics consistent within each account, only a single version of a given plugin can be enabled in an account at a time. This also lets the account admin pick the plugin version to use for all Test Agents and decide when to upgrade the plugins.
Setting the enabled plugin version for an account¶
To edit the current enabled plugin version, use the plugin CLI in the Control Center shell:
export ACCOUNT_SHORT_NAME=myaccount
export PLUGIN_VERSION=http@3.1.1
ncc plugins edit enabled-version --account $ACCOUNT_SHORT_NAME $PLUGIN_VERSION
where $ACCOUNT_NAME is the account short name and $PLUGIN_VERSION contains the plugin name (here, “http”) and version separated by a @ delimiter.
For further information about this command, type
ncc plugins edit enabled-version --help
You can also do bulk update operations applying to all plugins and/or all accounts:
This command updates a specified plugin to its latest version for all accounts in the database:
ncc plugins edit enabled-version --all-accounts $PLUGIN_VERSION
This command updates all plugins to their latest versions for all accounts in the database:
ncc plugins edit enabled-version --all-accounts --all-plugins
Plugin platforms¶
In addition to multiple plugin versions, Paragon Active Assurance has support for multiple plugin platforms for each version.
A .nap plugin package is specific to a single platform, for example x86_64. This means that a single plugin version can consist of multiple .nap packages, one for each platform. Below is an example of what the hierarchy may look like:
Plugin xyz
Plugin version 2
Platform A
Platform B
Plugin version 1
Platform A
Note that there is no requirement that all plugin versions support all plugin platforms.
Pre-bundled plugins¶
All plugins for a release of Paragon Active Assurance are found in a separate Debian package that will have been installed in Control Center if the instructions in the Installation Guide have been followed.
This means that in a default installation, you do not need to upload any plugins manually.
Custom plugins¶
It is also possible to upload new plugins that are not tied to a particular release of Control Center or of Test Agents.
Currently all plugins are written by Juniper. The company’s aim is to authorize partners and other external parties to write plugins; however, this will be realized at a later date.
Uploading custom plugins¶
Again, please note that you do not normally need to upload any plugins as all the plugins you need are installed along with Control Center.
However, if you receive a new plugin version from Juniper that is not part of the normal release cycle, you will need to upload it to Control Center.
To upload a plugin, you must be a superuser or have access to the Control Center shell so that you can use the CLI.
As mentioned above, the .nap file for the plugin contains a single plugin platform. This means that you will need to upload one file for each platform you want to use.
Use this command:
sudo -u netrounds ncc plugins upload $FILE
where $FILE is the .nap file to upload.
Note
The command requires sudo in order to successfully store the plugin file on disk in the plugins directory.
For further information about using the above command, type
ncc plugins --help
Enabling a plugin¶
To enable a separately uploaded plugin, set its version to the current enabled version as mentioned above.
Note
Important: When a separately uploaded plugin is enabled, its corresponding task appears not in its usual place in the GUI but in the category Dynamic plugins. See this page for more information.
Disabling a plugin¶
Note
You can only disable a plugin that has been uploaded separately. Plugins that are preinstalled with Control Center cannot be disabled.
To disable a plugin in all accounts:
ncc plugins edit disable myplugin --all-accounts
To disable a plugin in a specific set of accounts:
ncc plugins edit disable myplugin --accounts account_a,account_b