diff --git a/CHANGELOG.md b/CHANGELOG.md index 4b88f648..b23c0de0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,8 @@ ## ChangeLog +Documentation update (unreleased): Refresh README release/source compatibility, +installation guidance and source-checked behavior. + --- develop --- * dev: Run the CI poller with the shared runner group so RRD files and structured directories pass permission verification * issue: Shorten the VRULE graph drilldown button title so it reads cleanly as a label in Cacti's graph action menu, using two complete 'Toggle Threshold VRULES On'/'Off' strings (keeping the Threshold reference) so the label stays grammatical across translations diff --git a/README.md b/README.md index 38267a8b..f996b1ed 100644 --- a/README.md +++ b/README.md @@ -7,8 +7,26 @@ operations personnel. It provides Email, Syslog, and SNMP Trap or Inform escalations. In addition, it also can notify personnel of Cacti Device status changes through Email, Syslog, and either SNMP Trap or Inform. -NOTE: The Thold plugin that is in GitHub is ONLY compatible with Cacti 1.0.0 and -above! +This source branch requires Cacti 1.2.29 or later. Published packages have +their own compatibility requirements, shown below. + +## Versions and compatibility + +This README describes the `develop` source branch. + +| Code | Plugin version | Minimum Cacti declared in `INFO` | +| --- | --- | --- | +| [Source branch](https://github.com/Cacti/plugin_thold/blob/develop/INFO) | 1.8.3 | 1.2.29 | +| [Published v1.8.2](https://github.com/Cacti/plugin_thold/releases/tag/v1.8.2) | 1.8.2 | 1.2.25 | + +Use the published release’s assets and tagged documentation when installing that +package. Branch code can include later changes, even when its version number +matches the release. Cacti’s own PHP and database requirements also apply. + +Install this plugin in **`/plugins/thold`**, using the directory +name `thold` rather than `plugin_thold`. + +See [CHANGELOG.md](https://github.com/Cacti/plugin_thold/blob/develop/CHANGELOG.md) for the version history. ## Cacti compatibility @@ -29,7 +47,9 @@ $(document).off('click.cactiReturnTo', '.cactiReturnTo') To install the plugin, simply copy the plugin_thold directory to Cacti's plugins directory and rename it to simply 'thold'. Once this is complete, go to Cacti's Plugin Management section, and Install and Enable the plugin. Once this is -complete, you can grant users permission to view and create Thresholds. +complete, you can grant users permission to view and create Thresholds. The +plugin registers four realms: **Configure Thresholds**, **Configure Threshold +Templates**, **Manage Notification** and **View Thresholds**. Once you have installed thold, you should verify that Email support is functioning in Cacti by going to Cacti's Console and under Configuration select @@ -143,6 +163,13 @@ thresholds, note that you must modify and install the thold_daemon.service file into your systemd configuration, and then start and test the service. If you fail to perform these steps, thold will appear to not work as expected. +Two command line scripts are included in the plugin directory. Run +`cli_thresholds.php --auto-create=N` (or select Devices, Graph Templates, +Threshold Templates or Graphs with `--host-ids`, `--graph-template`, +`--thold-template` and `--graph-ids`) to create Thresholds from Threshold +Templates, and `cli_import.php --filename=N` to import a Threshold Template +exported from the plugin. + When upgrading the plugin while the Threshold Daemon is running, restart the `thold_daemon` service (for example `systemctl restart thold_daemon`) after the upgrade so the long-lived process picks up the new code. On upgrade the diff --git a/service/README.md b/service/README.md index 0b807773..005ae7bc 100644 --- a/service/README.md +++ b/service/README.md @@ -5,20 +5,20 @@ The thold daemon was designed to improve Cacti's scalability by allowing the thold check process to take place out of band. By doing so, the time Cacti spends checking thresholds can be reduced significantly. This service folder -includes initialization scripts for both systemd and initd based systems. To -install the thold daemon as a service, follow the instructions below. +includes a systemd unit file. To install the thold daemon as a service, follow +the instructions below. ## SystemD Based Systems Follow the steps below to install the thold daemon on a SystemD system. -* Verify the location of the thold_daemon.php in the systemd subfolder of the - location of this README.md file. +* Verify the location of `thold_daemon.php`, which is in the root of the thold + plugin directory ([cacti]/plugins/thold). * You may have to change mariadb.service to mysql.service depending on your installed version of MariaDB or MySQL. -* Update the to point to you Cacti base path. +* Update the placeholder to point to your Cacti base path. * Copy the `thold_daemon.service` file to systemd directory and then reload the systemd daemon so that it knows the new service is available. @@ -28,18 +28,10 @@ Follow the steps below to install the thold daemon on a SystemD system. systemctl daemon-reload ``` -* Edit the `thold_daemon.service` file and update the ExecStart/ExecStop paths - with the location of the `thold_daemon` shell script. By default, this script - is found in the [cacti]/plugin/thold/service/systemd folder, but the service - file is currently hardcoded to expect [cacti] is located at: - - /var/www/html/cacti - -* Ensure that the `thold_daemon` script is marked executable - - ```shell - chmod +x thold_daemon.php - ``` +* Edit the `thold_daemon.service` file and replace the placeholder in + the ExecStart path with the location of your Cacti base path. The unit runs + `thold_daemon.php` with `/usr/bin/php`, and has no ExecStop entry. The unit + file is found in the [cacti]/plugins/thold/service/systemd folder. * Enable and start the service using either the -now parameter: