[somethingwithproof]

Description

Rewrites README.md so that every statement matches the code on the default branch (origin/develop at 7fe6d33), and moves the 1.1 and 1.0 release history from the README to CHANGELOG.md, where the other entries are.

Documentation only. INFO is not changed (see "Decision for the maintainers"). Statements about behaviour that other open changes alter (for example the wmic path setting, the wmic credentials and the script-server paths) describe the default branch as it is today and need a one-line update when those land.

Related Issue

None open for this. It touches the same ground as open issue #15 (Windows hosts); the README now states what the code does, without taking a position on that issue.

Motivation and Context

Several README statements were wrong or out of date:

• The settings section said there is one setting and where it lives. There are three, on the Misc tab, and two of them do nothing yet.
• "Credentials are added under WMI Authentication" gave no path; it is a tab on the WMI Queries page.
• The wmic section told the reader to keep a binary path "in Linux_WMI" in step and to install a wmi-client / openwsman package. The path comes from the path_wmi setting, and the package is not in the repositories I could check.
• "Cacti with PHP 8.2 or newer is required" was stated without saying what the code needs (8.0) and what CI tests (8.2 to 8.4).
• The README had no upgrade, uninstall, poller, table, script-server, translation or development sections, and no word on which Cacti versions the plugin was run on.

How Has This Been Tested?

Each README claim was checked against the code or by running a command in a throwaway Cacti (MariaDB 11.8.9, no other plugin installed). The commands in the README were run as written on the final tree.

Cacti versions run (the README says exactly this and nothing more):

Cacti	PHP	Install, enable, disable, uninstall	Pages (GET as admin)
1.2.20 (release tag)	8.1.x	Through the plugin API, because that release has no cli/plugin_manage.php; tables, column, hooks and plugin_config status as expected at each step	Queries, Queries edit, Authentication, Edit Account, Query Tool, Device Template edit and Device edit all load (HTTP 200, no PHP error). Cacti 1.2.20 prints deprecation notices of its own on PHP 8.1
1.2.31 (release tag)	8.4	plugin_manage.php --install, --enable, --disable, --enable, --uninstall, --install --enable, --disable --uninstall	Same seven pages load
1.2.x branch tip (1.2.32)	8.4	Same seven steps	Same seven pages load; the Edit Account page loads with a shortened title (> (Edit)) because its breadcrumb parent does not exist, and the Cacti log gets warnings
develop (1.3.0)	8.4	Same seven steps	Six pages load; the Edit Account page fails with resolve_navigation_variables(): Argument #1 ($text) must be of type string, null given

The pages were requested with a logged-in admin through PHP's built-in server, with one device (id 1) added so the Device page has something to show. Nothing was run on Cacti releases other than these four, and nothing on PHP 8.2 or 8.3 locally.

At each step the database was inspected. After install: seven tables, the host.wmi_account column, a realm "WMI Management" for the three pages, 11 hooks and the two data input methods. After disable: all of them still present. After uninstall: tables, column, hooks and realm gone; the two data input methods remain. Installing again gives the realm a new id (2 became 3). The result was the same on 1.2.31, 1.2.32 and 1.3.0.

Full test suite in the CI order (checkout, composer install as the workflow does it, the pinned Pest harness for 1.2.x, install_cacti, plugin_manage --install --enable on a bare Cacti, then Pest as a non-root user): 54 passed and 1 warning (the existing PruneFilesTest permission test) on the 1.2.x branch and on develop; workflow log grep clean.

Claim	Changed or confirmed	Evidence	Result
PHP 8.0 or newer to load	New	php -l over every production file with php:8.0-cli and php:7.4-cli	No errors on 8.0; parse error on 7.4 at includes/linux_wmi.php:41 (constructor property promotion)
CI runs PHP 8.2, 8.3, 8.4 on Cacti 1.2.x	Confirmed	.github/workflows/plugin-ci-workflow.yml (php: ['8.2', '8.3', '8.4'], CACTI: 1.2.x)	as stated
Cacti's own PHP floor: 1.2.31 8.0, 1.2.x tip 8.2, develop 8.3	New	composer.json require.php at the 1.2.31 tag, the 1.2.x tip and develop	>=8.0, >=8.2, ^8.3
Core functions the plugin calls exist from 1.2.0	New	Token scan of the production files lists 69 core function names; each looked up with ^\s*function\s+name\s*\( in lib/*.php and include/global_languages.php at the release/1.2.0 tag	All present except auth_augment_roles(), which setup.php:286 calls only when it exists
wmi_processes uses the MEMORY engine	New	includes/database.php:122	as stated
Cancel buttons need the cactiReturnTo click handler before 1.2.31	Confirmed, and extended to develop	grep of include/layout.js at the tags 1.2.28 to 1.2.31, the 1.2.x tip and develop	Handler present from 1.2.31 and in the tip; absent in 1.2.30 and earlier and in develop (develop's layout.js defines cactiReturnTo() but binds no click handler). The plugin's buttons carry only the class: wmi_accounts.php:194, wmi_queries.php:211,213
Install steps and the CLI command	Confirmed	php cli/plugin_manage.php --plugin=wmi --install --enable on 1.2.31, 1.2.x and develop	"Plugin wmi installed successfully", "Plugin wmi enabled"; the 1.2.20 release has no such script
Menu path is Configuration > Plugins	Changed (README said Plugin Management)	lib/plugins.php:1566 (1.2.x), :1837 (develop)	The menu entry is called Plugins
Install creates seven tables, the host.wmi_account column, the realm, hooks and two data input methods	New	Database state after --install	7 tables listed in the README; column present; realm with the three files; 11 hooks; data inputs "Get WMI Data" and "Get WMI Data (Indexed)"
Upgrade: Cacti never calls plugin_wmi_upgrade()	New	Searched lib/, plugins.php and include/ of Cacti 1.2.x and develop for _upgrade / check_upgrade callers; setup.php:164, :849	No caller. wmi_prune_files() is reached only from that function
Disable keeps data; uninstall drops the tables and the column, removes hooks and realm; the data input methods remain; reinstall gets a new realm	New	The seven plugin_manage steps above with the database inspected after each	as stated
Uninstall also deletes graphs and data sources of the two WMI data input methods	New	setup.php:87 to :140	Read only; no graphs existed to delete in the test
wmic client not in common package lists	Changed (README named wmi-client / openwsman)	apt-cache for wmi-client, wmic, openwsman, wsmancli, winexe in Debian 12; apt-get install wmi-client in Ubuntu 18.04 (amd64) and 20.04 (arm64)	Not found in any of them. README says "does not appear in the Debian 12 or Ubuntu 18.04 package lists"
path_wmi read by the tool and poller, default /usr/bin/wmic; no settings field	New	wmi_tools.php:610,613; includes/functions.php:456,459; grep path_wmi setup.php	as stated
wmi_script.php uses /usr/bin/wmic; script/wmi-script.php uses plugins/wmi/wmic (not shipped)	New	wmi_script.php:75, script/wmi-script.php:73; find . -iname 'wmic*' outside tests	as stated
wmic gets --user and --password arguments	New	includes/linux_wmi.php build_command()	as stated
DCOM hardening KB5004442, enforced since March 2023	Confirmed	Microsoft's KB5004442 article	Packet-integrity level required; "stays enabled with no option to disable" from the March 2023 phase
NTLMv1 and PowerShell/WinRM statements	Unchanged	Not checked: no Windows host and no pwsh available	Left as the maintainers wrote them
No setting switches a Linux server to PowerShell	Confirmed	includes/linux_wmi.php:318 to :326 (default_transport() looks only at cacti_server_os)	as stated
PowerShell transport runs powershell.exe on a Windows server	Changed (README said pwsh or powershell.exe)	includes/linux_wmi.php:322; pwsh is only the constructor default	as stated
Menu entries and tabs	New	setup.php:283,284; includes/functions.php:38 (display_tabs(): Queries, Authentication)	Console > Data Collection > WMI Queries; Console > Utilities > WMI Query Tool; Authentication is a tab on the queries page
Device Template and Device page additions	New	setup.php wmi_device_template_edit(), wmi_device_edit_pre_bottom(), wmi_config_form(); the Device Template and Device pages load on all four Cacti versions	as stated
A device is polled only with an account	New	poller_wmi.php:202,385 (wmi_account > 0)	as stated
Realm and Template Editor	Confirmed	setup.php:71,286,291	as stated
Passwords stored reversibly	Confirmed, detail added	includes/linux_wmi.php:534 to :542	base64 of a serialized array
Settings on the Misc tab, names and defaults	Changed (README said one setting, under Device Defaults)	setup.php:477 to :531	wmi_enabled on, wmi_processes 10 (choices 1 to 10, then 15 to 50), wmi_autocreate on
wmi_enabled is never read	New	grep -rn wmi_enabled over the production files	Only the definition at setup.php:503
wmi_autocreate does nothing	New	setup.php:819 to :831 (the call is commented out)	as stated
wmi_autopurge read, not registered	New	poller_wmi.php:267; no definition in setup.php	as stated
Master poller behaviour	New	setup.php:204 to :212 (poller_id == 1, exec_background); poller_wmi.php:189 to :202 (device selection); run with no device	"No Devices found this pass to launch", WMI STATS line, stats_wmi setting Time:0.00 Processes:10 Devices:0
Live lock blocks the master, and a row two hours old never expires	New	INSERT INTO wmi_processes ... NOW() - INTERVAL 2 HOUR, then php plugins/wmi/poller_wmi.php -M	"WARNING: Another WMI Collector is still running! Exiting"
Poller options	New	poller_wmi.php:57 to :104; php plugins/wmi/poller_wmi.php --help; run with no arguments	Help lists only -M, --host-id, --seed, -f, -d; no arguments prints "FATAL: You must specify a Cacti host-id run". -f only sets a flag passed on to children; debug() (line 147) is never called
host_wmi_accounts unused	New	grep shows it only in setup.php:97 (drop) and includes/database.php:89 (create)	as stated
Script-server sample	New	templates/resource/script_server/exchange_messages.xml:3,8; wmi_script.php:80 (WHERE name = ?); grep for callers of plugin_wmi_create_dataquery_xml and plugin_wmi_create_resource_xml	script_path is `
Edit WMI Account page fails on develop	New	setup.php:337 to :342 (mapping points at index.php:wmi_accounts.php:, which is not defined); page request on each version	PHP error on develop, shortened title on 1.2.x
Translations	New	sh locales/build_gettext.sh on a copy of the tree in an Ubuntu 24.04 container with gettext	Prints cat: include/cacti_version: No such file or directory, then updates the .po files; on macOS, BSD sed also fails
Development commands	New	php tests/bin/validate-manifest.php, php tests/bin/check-i18n-pot.php origin/develop, the Pest command, php tests/bin/patch-coverage.php coverage/clover.xml origin/develop 100 from the plugin directory	The manifest check passes, and fails with coverage/ present (hence the README note to run it first); the i18n check passes; Pest passes in the CI-order simulation on both refs; the patch coverage check reports "no measured lines changed" for this change
tests/.cacti-version must read 1.2.x or develop	New	tests/bootstrap-unit.php version check	A value other than those or the exact Cacti version throws

Not run: the GitHub workflow itself, PHP 8.2 and 8.3 locally, Cacti releases other than the four above, a real wmic or Windows host, and pwsh.

Decision for the maintainers

INFO still says compat = 1.1.4 and version = 1.0. Both disagree with the rest of the repository:

• The code calls cacti_sizeof() (in poller_wmi.php, wmi_tools.php and includes/functions.php). I could not find it in lib/functions.php, html.php, html_form.php, html_utility.php or plugins.php at the release/1.1.26 tag, so a plugin declared for Cacti 1.1.4 would fail there. The functions the code calls all exist at the release/1.2.0 tag, and nothing was run on 1.1.x or on 1.2.0 to 1.2.19 (a trial install through the plugin API on 1.2.19 created the tables and registered the plugin, but I ran nothing further there).
• The newest release section in the old README change log, now in CHANGELOG.md, is 1.1. INFO says 1.0. No git tags or releases exist (gh api repos/Cacti/plugin_wmi/tags and /releases are empty), so I did not choose a number.

This pull request leaves both fields alone; the README states the versions that were actually run. Declared compatibility and the version are yours to set.

The Warning that the plugin is not fully functional is unchanged. The wmi_enabled, wmi_autocreate and Edit Account findings above support it.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Documentation only.

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation repository accordingly.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud