Skip to content

Latest commit

 

History

History
206 lines (148 loc) · 7.61 KB

Plugin-Development.md

File metadata and controls

206 lines (148 loc) · 7.61 KB
Raw

Plugin Development

Overview

Cacti Plugins allow users of Cacti to extend it's functionality into areas that the core Cacti developers have not. They were written based off of the work of Jimmy Conner from the Squirrel Mail project years ago. They allow developers to augment the Cacti Website, and it's polling processes to extend Cacti's reach.

There are a number of popular plugins including:

  • Thold - A graph based service checking framework that leverages the data on Cacti graphs for performing service checks
  • Syslog - A plugin that allows you to view log data from hundreds or thousands of hosts and generate faults based upon pattern matching of that log data.
  • Monitor - A plugin that provides a Device Dashboard highlighting Cacti Devices that are experiencing faults.
  • Intropage - A plugin that provides a replacement to the Cacti console showing key performance metrics across all of Cacti from a single page.
  • Weathermap - A plugin that allows you to create architectural diagrams of your network and to animate them with status data.

In theory, these plugins can be integrated into Cacti very simply, and removed without breaking Cacti. However, it must be noted to always review the plugins documentation before you start to use it.

Legacy Plugins Notice

Plugins written for Cacti 0.8.x require modifications in order to be compatible with Cacti 1.x. There are several changes that all plugin developers need to be aware of. Any of the Cacti Group maintained plugin can be used as reference plugins for driving your plugin migration to the 1.x framework and are available on Github.

Plugin Migration

In order to migrate your legacy Cacti plugins, there are several steps that need to be taken. This guide will provide a brief synopsis of changes that are required to make your plugins compatible with Cacti 1.0.

Migration Steps

Each of the following steps should be followed to migrate your plugins. Some of these changes are optional, and some are mandatory. We will start with the list of steps that must be required. Then, in future sections, we will provide details on performing each step.

Required Steps

  • Creation of Information (INFO) file (mandatory)

  • Applying correct classes to Anchor tags to trigger callbacks (mandatory)

  • Remove instances of including top_header.php, top_graph_header.php, top_general_header.php and replacing with function calls top_header(), bottom_footer(), top_graph_header(), and top_general_header(). (mandatory)

  • Adding '&header=false' to most header() function calls to drive Ajax rendering. (mandatory)

  • Movement of form elements to be W3C compliant as HTML5 requires it (mandatory)

  • Moving the $nav variable within the page to ensure tables are formatted correctly. This includes the $nav before the table and the $nav afterwards. (mandatory)

  • Remove all instances of $_GET, $_REQUEST, and $_POST and replacing the wrappers get_request_var(), get_filter_request_var(), set_request_var(), isset_request_var(), isempty_request_var() (mandatory)

  • Utilize the 'validate_store_request_vars()' function to greatly simplify request validation on your pages. (mandatory)

  • Migration of the Plugin to the PIA 2.x+ install and setup process. Cacti PIA 1.x plugins are not supported in Cacti 1.0 and beyond. (mandatory)

  • Removal of hooks that inject jQuery, jQueryUI into Cacti's header (mandatory)

Optional Steps

  • Remove inline styles, and use Cacti's classes instead (highly recommended)

  • Migration of filters to Ajax callbacks (highly recommended)

  • Removing references to the $colors array (optional)

  • Using new functions for alternate colored rows, sorted, checkbox and other headers (optional)

  • Using new options for headers to support tool tips, alignment etc (optional)

  • Migration to new pagination functions, which simplify page navigation

INFO File structure

The INFO file follows the INI file specification. An example INFO file includes the following sections:

  • name - The name of the plugin directory

  • version - The version number of the plugin

  • longname - A description for the plugin

  • author - The plugins author

  • email - An email contact in order to reach the author

  • homepage - A link to the plugin authors homepage

  • compat - Prior to Cacti 1.3, the minimum version of Cacti to support the plugin. After Cacti 1.3, it will represent the range of Cacti versions supported.

  • requires - The list of plugins and versions that the current plugin needs in order to operate. This is a comma delimited list of Plugins with version attributes similar to the compat section.

  • capabilities - a comma delimited string of capabilities defining how the plugin works with remote data collectors

  • nosync - a comma delimited string of directories or file extensions to skip during the remote data collector synchronization. File extensions must be formatted as *.extension and only are relevant in the base directory of the plugin. The following extensions are automatically excluded regardless of directory: 'tar', 'gz', 'zip', 'tgz', 'ttf', 'z', 'exe', 'pack', 'swp', 'swo'.

Example INFO Files

From the Monitor plugin, we can see the following format:

[info]
name = monitor
version = 2.8
longname = Device Monitoring
author = The Cacti Group
email =
homepage = http://www.cacti.net
compat = 1.2.15
requires = thold:1.2.1
capabilities = online_view:1, online_mgmt:1, offline_view:0, offline_mgmt:0, remote_collect:0

From the Syslog plugin, we can see a slightly different format.

[info]
name = syslog
version = 4.2
longname = Syslog Monitoring
author = The Cacti Group
email =
homepage = http://www.cacti.net
compat = 1.2.23
nosync = config.php
capabilities = online_view:1, online_mgmt:1, offline_view:1, offline_mgmt:1, remote_collect:0, remote_poller:1

Here we can see that the config.php file in the plugin directory will not be copied over to remove pollers, and we can see that syslog allow for remote data collection. using the remote_poller:1 capabilities attribute.

Changes in Cacti 1.3+

Starting with Cacti 1.3 and beyond, the compat and requires lines can include ranges of support. For example, the following will be supported:

compat = >=1.2.15 <1.3.0
requires = thold:>1.2.1 <=2.0, monitor:>2.0

Before Cacti 1.3, the compat and requires attributes assumed always >= there were never provisions for < or <= to for any plugin. Due to changes in the Plugin Architecture, this will change starting with Cacti 1.3.

As mentioned, there are some very good examples of how to create or migrate plugins in the various Cacti plugins included on The Cacti Groups GitHub site. Also, for a very simple Cacti page, you can look at vdef.php as an example. You can use this as a template to manage a table using the Cacti framework. For a simple plugin example, please review the gexport plugin.

Charting Functionality

Several JavaScript based HTML5 Charting packages have been included in Cacti in an effort to assist plugin developers who wish to use graphing API's in their plugins other than RRDtool.

Logging

For developers using the Cacti framework, it is important to note that additional controls on logging have been added. Debug logging can now be controlled at not only a global level, but now per plugin, per device and even per file.

Copyright (c) 2004-2024 The Cacti Group