Linux, FreeBSD, Mac plugins are written in Python.
This article is for our v1 agent and will soon be deprecated. See information about custom plugins for custom plugins for the v2 agent
Step 1: Agent setup
Plugin support in the agent is disabled by default. To enable it, you need to do the following:
Create a plugin directory
This is a single directory anywhere on your server which will contain your plugin scripts. Make sure it has the correct permissions so it is accessible by the agent. For example, you can create the directory in /usr/bin/sd-agent/plugins/
sudo mkdir /usr/bin/sd-agent/plugins
Tell the agent where the directory is
Open the agent config.cfg file. This is located at /etc/sd-agent/config.cfg or if you didn't use our installer, where you downloaded the agent to. Edit the following line, adding the full absolute path to your plugin directory. Do not include a trailing slash.
plugin_directory: /usr/bin/sd-agent/plugins
The agent will parse this directory for any new Python scripts each time the agent is started.
Step 2: Writing a plugin script
Requirements
- Plugins must be written in Python (v2.4+).
- Plugins must be within their own self contained file, but can include other files.
- Plugins files must be a .py file - the filename should be unique to identify the plugin in your account.
- Plugins must have a class named the same as the filename. The class must have a constructor that takes three arguments - the agent configuration object, a logging instance and the raw config. The class must have at least a
run()function which must return a dictionary.
Filename
The filename is used to match with the plugin class, so the agent can dynamically detect new plugins. This simply means naming the file the same as the class name you pick. E.g. if you wanted to create a plugin called New Users your plugin file must be called NewUsers.py. This is then placed inside the plugins directory previously created.
Structure
The script must have a run() function which returns a dictionary. This needs to belong to a class named the same as the filename. The agent will import the script and then immediately call the run() function, using the return value as part of the postback payload. You can, of course, create other classes and functions to do anything you like. The agent will only call run() from the class named the same as the plugin internal name.
The plugin is only imported and the object created once when the agent starts. For every other check cycle, the run() method will be called on the existing object.
Privileges
All plugins on Linux execute as the sd-agent user which is a regular, unprivileged user. Some commands in your plugin may need sudo access which is explained separately.
Return value
Each plugin will be displayed in the interface on a single graph. However, the return dictionary may contain any number of key/value pairs and these will appear as separate series on the graphs.
The name of the key will be what is displayed on the chart and can contain any character except a dot. The value is expected to be an integer or float, although it will be stored as a string and displayed to 4DP on the graphs.
Example
For example, the following function for the plugin called Plugin1 and the filename name Plugin1.py - it returns two fixed value key/pairs:
class Plugin1 (object):
def __init__(self, agentConfig, checksLogger, rawConfig):
self.agentConfig = agentConfig
self.checksLogger = checksLogger
self.rawConfig = rawConfig
def run(self):
data = {'hats': 5, 'Dinosaur Rex': 25.4}
return data
agentConfig is the core config that is read and modified by the agent.
rawConfig is a multi-dictionary that is essentially a clone of the entire config.cfg file. This is useful if you want to add custom config values for your plugins.
Finally
Once you have written the script and it exists in the plugin directory, just restart the agent and it will immediately be picked up and executed.
Comments