Hook API Reference
Submitted by thewitness on Wed, 2007-03-07 13:16.
Cacti Plugin Developers,
Below you will find documentation on the current Plug-in Architecture (1.1). If you are looking to start a plugin, some good reference material would be the following plugins:
- MacTrack,
- THold,
- Syslog,
- Boost
Regards,
Larry Adams (aka TheWitness)
| Hook Name | File Appearing | Explanation |
| api_device_save | lib/api_device.php | This hook allows you to alter the contents to the device table with custom fields. When used properly, it allows you to extend the host table with your plugins custom fields. |
| cacti_image | auth_login.php | This allows you to change the image displayed on the Login screen |
| config_arrays | include/config_arrays.php | Allows your plug-in to define custom array elements to be used throughout cacti. Things like dropdown arrays and the like. |
| config_form | include/config_form.php | Allows you to define form object to represent data to be stored in your tables. In the case of MacTrack, there is a table called mac_track_sites and in order to drive the UI and allow for the user to provide input and save a site, you must provide the Cacti form engine a form array to allow for the form to be presented and contents to be saved. |
| config_settings | include/config_settings.php | Allows you to extend the Cacti settings page to allow for custom tabs and global settings within them. |
| console_after | index.php | Allows you to add text before the default message on the console page |
| console_before | index.php | Allows you to add text before the default message on the console page. For instance, the Update plug-in will display a message here if there are new versions of plugins. |
| data_sources_table | data_sources.php | Allows you to change the data displayed on the Data Sources table. THold uses this to create a link to that datasources threshold |
| device_action_array | host.php | Allows you to define custom dropdown actions from within the device/host page. |
| device_action_execute | host.php | Allows you to define custom actions to be taken upon you dropdown selection. |
| device_action_prepare | host.php | This is the final component to creating a custom action within the devices. In Cacti's form engine, you must provide the dropdown action and then two follow-up actions to complete the cycle. This is were you actually save the data. |
| draw_navigation_text | lib/functions.php | Just below the Cacti "Console", and "Graphs" tabs, cacti provides a Navigation bar that allows you to move backward in a selection tree. Although it is not foolproof, this hook allows you to populate and navigate that tree. |
| graph_buttons | graph.php | You know about the zoom button right? Well this allows you to add any additional custom button to the right of a graph. |
| graph_buttons | lib/html.php | This hook has the same purpose as the hook above. However, there are several sections of Cacti that allow for the insertion of your Icon image and action. |
| graph_buttons | lib/html.php | This hook has the same purpose as the hook above. However, there are several sections of Cacti that allow for the insertion of your Icon image and action. |
| graph_image | graph_image.php | This hooks allows displaying of alternative graphics in place of a graph image. This hook can no output text, only modify the image, as it is only called when a graph is required to be outputted. |
| graphs_action_array | graphs.php | Similar to the host actions and host, prepare and execute hooks. It allows you to have custom dropdown actions within the graph management interface. |
| graphs_action_execute | graphs.php | See the note above. |
| graphs_action_prepare | graphs.php | See the note above. |
| graphs_new_top_links | graphs_new.php | Add a link at the top of the "Create New Graphs" page. |
| login_after | auth_login.php | This allows you to display text or html before the login form. |
| login_before | auth_login.php | This allows you to display text after the login form. Combined with the above hook, you could draw a box, etc… around the form, change its background color, etc… to slightly customize the login page. |
| poller_bottom | poller.php | This hook allows you to launch other polling activities once Cacti has complete it's polling activities. Things like MacTrack, Boost, THold, and others use this hook to launch their respective poller. |
| poller_on_demand | lib/poller.php | This hook was designed specifically for the boost plug-in. It allows Cacti to evaluate whether or not there are RRDtool update's to perform for a set of data sources that will be used in the upcoming graph operation. It will update them prior to any graphing operations. |
| poller_output | lib/poller.php | This hook was designed specifically for the boost plug-in. However, it has found new life in many plugins making them much faster now. What this hook allows you to do is intercept the contents of the poller_output table before the data is deleted. This allows for things like threshold checking and other interesting actions such as checking for up/down events and the like. Previously, plugins were reliant on using things like RRDtool fetch to perform these actions. Now they can leverage the pollers output directly. |
| poller_top | poller.php | This hook allows you to launch processes concurrently with the Cacti poller for things like THolds fast poller for example. |
| prep_graph_array | lib/rrd.php | |
| rrdtool_function_graph_cache_check | lib/rrd.php | This hook was designed specifically for the boost plug-in. This plug-in will check the image cache for a valid file. If the file is found to be stale, it will utilize RRDtool to generate a fresh one. |
| rrdtool_function_graph_set_file | lib/rrd.php | This hook was designed specifically for the boost plug-in. It will look for the presence of a cached graph image and setup it's presentation rather than regenerating a new graph. |
| substitute_host_data | lib/variables.php | This allows you to add to the substitution variables that cacti can parse. Ex |
| top_graph_header_tabs | include/top_graph_header.php | This hook is used to add tab's to Cacti's user interface. |
| top_graph_refresh | include/top_graph_header.php | This allows you to change the refresh on the graph (and any plug-in page that calls the graph header) |
| top_header_tabs | include/top_header.php | This hook is similar to the one above, except in the Console view and not the Graphs view. |
| update_host_status | lib/functions.php | This is called when cmd.php detects a change in the status of a host. Granted, this is not used when you use Cactid, hence the reason THold will not send host down alerts when using Cactid. |
| user_admin_action | user_admin.php | This hook is part of a series of hooks that allow you to add custom user settings. Consider a plug-in called "abc". In that plug-in, you want to save custom settings on a per user basis. Therefore, following our unpublished ? table naming standards, you would create a table called “abc_settings". When you tab over to the "abc" plug-in, you are provided an "abc settings" on the right similar to "Graphs". The next series of hooks allow you to present those settings to the user, enable or disable the users access to that specific "abc settings" tab and allow an administrator to define customer values for that plug-in on a per user basis. |
| user_admin_run_action | user_admin.php | See the explanation on "user_admin_action" |
| user_admin_setup_sql_save | user_admin.php | See the explanation on "user_admin_action" |
| user_admin_tab | user_admin.php | See the explanation on "user_admin_action" |
| user_admin_user_save | user_admin.php | See the explanation on "user_admin_action" |
| utilities action | utilities.php | This hook set's up the function to be executed from within Cacti's utilities section. |
| utilities list | utilities.php | This hook allows you to add a custom utilities pick under Cacti's "Utilities" page. |
| valid_host_fields | include/config_form.php | Pretty sure that this hook allows you to define custom replacement values in graphs. |