The
Plugin Architecture (PIA) is a set of code changes to core cacti. It is provided by Jimmy Conner (cigamit), one of the Cacti core developers. The Plugin Architecture for Cacti was designed to be both simple in nature and robust enough to allow freedom to do almost anything in Cacti. Cacti itself is designed nicely enough that integrating into it is fairly easy with very little modifications necessary. Eventually Cacti will come with a standard plugin architecture that will allow you to create addons without the need to modify your installation, but until that time comes (we are working on it) you will need to follow the directions below.
The following has been taken from the above link and updated to PIA 2.8+
The first step is to
download the Plugin Architecture. You can get it in either zip or gzip compressed archives.
You will need to extract this archive. On Windows there are several ways to extract zips/gzips, just use the program of your choice (ex: Winzip). Using Unix you can extract it using a command similar to this one, but your milage may vary depending on the Distribution you are running.
tar -zvxf cacti-plugin-arch.tar.gz
If all goes well, you should have a folder called cacti-plugin-arch with a few patch files and a folders in it. It does not matter in particular to where you download and extract these files to, as we will be moving just the files we need.
There are two ways of install the Plugin Architecture. The first way is by using the patch files. A patch file contains the difference between the original files and the “new” files, which makes them very small as they only contain exactly what we need to make the changes. The other way is by using the pre-patched full files. These files are the full install of the necessary files with the patch already applied to them. With these you can directly override the files already in your Cacti directory. I only include the files that are necessary to change, so you don't have to override every file in your Cacti install.
Using the pre-patched files is easiest and most straight forward way to install the Plugin Architecture. You will of course want to backup your Cacti install first before attempting any add-on modifications. Once you have backed up your install. Goto the directory that you extracted the Plugin Architecture to. In this directory you will find several other directories. One of them will look like this “files-0.8.7g”. This is to show you that these are the pre-patched files for Cacti v0.8.7g, there may be other versions available if that is not your version.
Now you will need to determine where your original Cacti install is. For instance on Fedora Core 3, my original Cacti files are located at ”/var/www/html/”. This will vary between Distributions and of course between Linux and Windows, and it is outside the scope of this document to discover where your installation is placed. Once you have the location, remember where it is as you will need it shortly.
You will now copy the files from the
“files-0.8.7g” directory to your Cacti install directory, overriding any files if you are prompted. There are several ways to copy the files over (Explorer in Windows,
FTP, command line, etc…) so I will not go into that here.
From here you are done installing the Plugin Architecture, but it is necessary to configure it first before you continue using Cacti (or Cacti will probably not function properly!)
Using the patch files is slightly harder that using the pre-patched files, but it is recommended for anyone that has already modified their Cacti install using other mods, or their own custom tweaks. This is mostly used on Linux/Unix etc… but can also be done on Windows if you have the appropriate tools installed. You will ofcourse want to backup your Cacti install first before attempting any add-on modifications.
Now you will need to determine where your original Cacti install is. For instance on Fedora Core 3, my original Cacti files are located at ”/var/www/html/”. This will vary between Distributions and ofcourse between Linux and Windows, and it is outside the scope of this document to discover where your installation is placed. Once you have the location, remember where it is as you will need it shortly.
Now goto the directory that you extracted the Plugin Architecture to. In this directory you will find several files with names similar to this “cacti-plugin-0.8.6f.diff”. This is a patch file that contains everything you need to install the Plugin Architecture. You will copy the file that corresponds with your Cacti version to the location of your Cacti install using a command prompt (if you weren't already using one!)
We will first run this command from the Cacti Install directory
patch -p1 -N --dry-run < cacti-plugin-arch.diff
This will not make any changes, it will only attempt to do the install and report back any errors. If you receive and FAILED errors, then you know that you will run into a few problems. These problems can usually be addressed by posting in the forums. If you have not modified your Cacti install by using any other mods, then it is usually fairly safe to override the file that “FAILED” with a pre-patched file that is also provided in the archive (See the directions above). Your config.php file will almost always fail to be patched if you have either already configured your database settings for Cacti, or you are using an RPM/DEB install (and possibly even the Windows MSI install). If so, then just override the file, and reconfigure it for your database.
To continue with the patching process, just run this command
patch -p1 -N < cacti-plugin-arch.diff
This will modify the files and report back and errors. Assuming that all went well, then you can now proceed to configuring your Cacti install.
WARNING: I just discovered a new “problem” when using patches. I received permission errors on all files, that are created from scratch by using the patch. Don't misunderstand me: the files exist and look fine, but still “permission denied”. No SELinux alerts. But I suppose it's been an issue with SELinux nevertheless. The soltion was to delete the newly created files and to copy them from the files-0.8.7g directory. This removed all permission errors.
Edit “include/config.php” and specify the database type, name, host, user and password for your Cacti configuration.
$database_type = "mysql";
$database_default = "cacti";
$database_hostname = "localhost";
$database_username = "cactiuser";
$database_password = "cactiuser";
/* load up old style plugins here */
$plugins = array();
//$plugins[] = 'thold';
/*
Edit this to point to the default URL of your Cacti install
ex: if your cacti install as at http://serverip/cacti/ this
would be set to /cacti/
*/
$url_path = "/cacti/";
/* Default session name - Session name must contain alpha characters */
#$cacti_session_name = "Cacti";
The $plugins array is required for using the Plugin Architecture (PIA) only. For legacy plugins, those that must be installed in global.php, we have moved the plugins array out of global.php and into config.php. This was done to insure that global.php remains pristine. It is a file that is not intended to be modified, so with the PIA installed, you should not have to.
The variable “$url_path” has also been moved from global.php to config.php for the same reason as the plugins array. For those of you upgrading from very old Plugin Architectures you should know that in the past, we attempted to “detect” this path. However, the process was not reliable. Therefore, you have to specify that path in config.php.
$url_path = "/projects/cacti/testing/";
It is important to note that you must include the '/' at the front and end of the location. This is to prevent other issues later down the road.
The plugin architecture includes a pa.sql file. You will need to import this into your cacti
SQL database.
Once this is done, you will have successfully completed installing the Plugin Architecture. You will now want to proceed with downloading and install Plugins. You can refer to
Installing Plugins to help with it.
The
Plugins Repository and the
Forums provide a huge list of plugins. Many of them are maintained by Cacti core developers; others are provided by different users.
There are two types of plugins today, the
legacy plugins and those conforming to the
2.x architecture. Their installation process differs. All plugin authors are asked to upgrade to the PIA 2.x type of plugins.
The first step to is to
download the plugin of your choice. You can choose either the zip or gzip compressed archive. You will then need to extract this archive to a temporary location. When you extract the archive it should, depending on your archive software, create a directory with several files inside of it. We will use the
Monitor Plugin as an example.
Begin by downloading the Monitor plugin. After the download is complete, the filename should look something like this. monitor-0.82.zip or monitor-0.82.tar.gz
You will need to extract this archive. On Windows there are several ways to extract zips/gzips, just use the program of your choice (ex: Winzip). Using Unix you can extract it using a command similar to this one, but your milage may vary depending on the Distribution you are running.
tar -zvcf monitor-0.82.tar.gz
If all goes well, you should have a folder called monitor with a few files and possibly a few folders in it. To be sure that you are looking at the correct directory, check and make sure that you have a file called “setup.php” directly inside of your monitor folder. On Windows if you happen to end up with a parent folder called monitor-0.82 with a subfolder called monitor then you will need to ignore the parent folder and just use the subfolder.
It is extremely important that you do not alter the case or the name of this folder or the plugin will not function at all. And please make sure, that there is no second directory like e.g.monitor.old
Once you are satisfied that you are working with the correct directory, then you will need to upload this file into your Cacti install's Plugin directory. This will vary greatly depending on where you actually installed Cacti. For example, on Linux, if your Cacti files are in a directory like this.
/var/www/html/cacti/ then your Plugin Directory would be here
/var/www/html/cacti/plugins/ On Windows using
IIS, it could be located here
C:\inetpub\wwwroot\cacti\plugins\
You will need to upload/copy the complete “monitor” folder into this “plugins” folder on your web server. So that you have a structure kinda like this /var/www/html/cacti/plugins/monitor/ orC:\inetpub\wwwroot\cacti\plugins\monitor\
That takes care of the difficult part of the installation (download, uncompress, upload). Now we will just turn the newly installed plugin on.
You will now need to modify Cacti's configuration file to activate the plugin. This the same file that you had to use to configure Cacti to connect to the correct database. Using the above example, Cacti's config file would be located here /var/www/html/cacti/include/config.php or here C:\inetpub\wwwroot\cacti\include\config.php
Inside this configuration file, as you proceed down a few lines, you will find a line that looks like this
$plugins = array();
Directly after this, you may see an example line like this
//$plugins[] = 'thold';
This is in place to basically show you how to activate a plugin. The ”//” is a comment line in
PHP Code which effectively disables the text directly proceeding it from being executed. What we will need to do, is to change that line to look like this
$plugins[] = 'monitor';
If the example line does not exist, then just put this directly below the
$plugins = array();
line. You may also have a few other plugins already installed, and if so your configuration file may look like this.
$plugins = array();
$plugins[] = 'thold';
$plugins[] = 'monitor';
$plugins[] = 'discovery';
It is extremely important that the name in the quotation marks is the folder name of the plugin you installed. This folder name also can not be changed from the original or the plugin will not work correctly!
For example, if you had a plugin with a folder name of “logpurge” then you would have to a configuration like this
$plugins[] = 'logpurge';
You are now completely done installing the plugin, and at this point it should have been a fairly painless process.
A few plugins will require their own little tweaks or configuration changes to complete the installation of the Plugin. These are outside the scope of this document, as you will need to consult the individual documentation of the Plugin. But if you are stuck and can not locate the specific configuration options for a Plugin, you might try looking at the Settings link in the Console to see if any new options were added.
Removing a plugin is very simple. If you want to just disable the plugin, just remove the line from Cacti's config.php or comment it out like so
//$plugins[] = 'thold';
The ”//” is a comment line in
PHP Code which effectively disables the text directly proceeding it from being executed. To completely remove the plugin, just delete the directory for the plugin from your
plugins directory.
This works very much like the above. The main difference is, that there's no need to change ./include/config.php. PIA will autodetect the existance of such a new plugin as soon as it is found in the ./plugins directory.
PIA 2.8+ introduces a new menu item to manage the plugins. But this menue item is not available for all users by default. It is govern by a realm permission for each user. To provide access to
Plugin Management, please visit
User Management and select the user in question. The
Realm Permission tab will show up like
You may not have all the plugins listed in this image. But please make sure to have
Plugin Management checked. After saving, you will find
Plugin Management underneath
Configuration:
Selecting this new console menu item may look like:
Hitting the icons to the left will allow you to install (blue icon), enable (green icon), disable (red square) or uninstall (red circle) a plugin. You may change the load order by first selectiong the column heading Load Order and then moving plugins around using the blue arrows. You can't move around System plugins.
