Plugins for Excubitor

Installing a plugin

To install a plugin, you need to create the plugins folder within Excubitor's working directory. When using the .deb package, this is /opt/excubitor.

In there you want to create a folder with the name of the plugin. In this folder, you drop the .plugin-file. When restarting Excubitor either manually or through systemd, the plugin will be loaded.

Note: Make sure that the .plugin file is executable! If not, try chmod +x *.plugin.

Sample plugin

You can find a sample plugin in Filesystem-Plugin. It can be built using make build. For more information consult the README file in the repository.

Developing a plugin for Excubitor

ModuleProvider

Every plugin for Excubitor needs to implement the ModuleProvider interface in github.com/Excubitor-Monitoring/Excubitor-Backend/pkg/shared.

type ModuleProvider interface {
	GetName() string
	GetVersion() modules.Version
	TickFunction() []PluginMessage
	GetComponents() []modules.Component
	GetComponentFile(path string) []byte
}

All required types are contained in the same package. This also means that every plugin needs to import this package from the main application.

What do the interface methods do?

GetName

GetName returns the name of the provided module. This can be any string - but by convention it should be human readable and not contain any symbols other than alphanumerical symbols.

GetVersion

GetVersion returns the version of the plugin. The modules.Version type is an int array of length 3. It is recommended that plugins adhere to semantic versioning.

TickFunction

This function is called whenever the application wants new data from the plugin. It should return an array of all messages the plugin can provide.

GetComponents

GetComponents is used to retrieve metadata about the components delivered by the plugin.

GetComponentFile

GetComponentFile is used to get the byte value of the files associated with components from GetComponents.

Serving the ModuleProvider implementation

When started the plugin needs to specify the implementation in a pluginMap and serve it through the plugin.Serve function of go-plugin:

var handshakeConfig = plugin.HandshakeConfig{
	ProtocolVersion:  1,
	MagicCookieKey:   "MODULE_PLUGIN",
	MagicCookieValue: "EXCUBITOR",
}

var pluginMap = map[string]plugin.Plugin{
	"module": &shared.ModulePlugin{Impl: impl},
}

plugin.Serve(&plugin.ServeConfig{
	HandshakeConfig: handshakeConfig,
	Plugins:         pluginMap,
})

The handshakeConfig signals which plugin protocol version the plugin is developed for. The MagicCookieKey and MagicCookieValue show the main application which type of plugin it loads. Currently, only the values shown above are supported.

Example

For an example on how to implement a plugin for Excubitor see Filesystem-Plugin.