Skip to content

Harmonize the ss_mikrotik scripts with Cacti 1.2.x and develop - #140

Merged
TheWitness merged 4 commits into
developfrom
fix/harmonize-ss-scripts
Nov 20, 2026
Merged

TheWitness merged 4 commits into
developfrom
fix/harmonize-ss-scripts

Conversation

@TheWitness

Copy link
Copy Markdown
Member

Summary

The MikroTik script server data collection scripts (scripts/ss_mikrotik_*.php) had drifted three ways between Cacti 1.2.x, Cacti develop and plugin_mikrotik. This makes all 17 scripts byte-identical in Cacti 1.2.x, Cacti develop and plugin_mikrotik. One PR goes to each of those three branches.

The differences trace back to plugin_mikrotik #135 (RouterOS 7 support). It moved health collection to the mtxrGaugeTable and wireless collection to the RouterOS API, and it copied the develop scripts into the plugin. Along the way:

  • Health: the plugin's ss_mikrotik_health.php was changed to accept friendly names (voltage, ...). The shipped health data templates pass the legacy column names (HlTwelveVoltage, HlCpuTemperature, HlPower, ...), so every health data source returned U.
  • Interfaces: develop and the plugin switched the interfaces query to a name-based index with an allow-list of columns that don't exist (curInOctets, ...). The shipped templates index interfaces by the numeric index, and the table stores curRxBytes, curTxBytes, and so on, so every interface get returned U.
  • Unknown values: develop and the plugin dropped the table-existence checks and returned 0, false or a fallback column instead of U in several places.

Changes

  • All scripts: each checks that its plugin table exists, returns U when there is no data (so health graphs aren't created with fabricated zeros), and validates requested columns against an allow-list, with values bound as parameters.
  • Health: accepts the Hl* column names the templates pass, plus the friendly aliases from Support RouterOS 7.x (WifiWave2 wireless + mtxrGaugeTable health) alongside 6.x, and add a Health tab #135. If plugin_mikrotik_health_sensors exists (plugin schema 3.4 and later), it prefers the RouterOS 7 gauge sensor, using the same sensor→column map as the poller's mikrotik_gauge_health_column(). Otherwise, and for pre RouterOS 7 devices, it reads the legacy column.
  • Interfaces: numeric interface index, as in the shipped templates, with an allow-list taken from the data query's output fields.
  • num_indexes: returned rather than printed, so script server reindex checks see it.
  • Wireless registrations: the collection change in Support RouterOS 7.x (WifiWave2 wireless + mtxrGaugeTable health) alongside 6.x, and add a Health tab #135 was API-only; the schema is unchanged. The script maps RxStrengthCh1 → RxStrengthChl (a historical column-name typo) and converts the stored d:h:m:s uptime to seconds, so the SNMP and RouterOS API collectors both graph it.
  • SNMP get: validates the OID, polls with SNMP_POLLER, and returns U when the get fails.
  • Compatibility: PHP 5.4 compatible for Cacti 1.2.x (no native types). PHPDoc types satisfy develop's PHPStan, and the formatting follows develop's php-cs-fixer.

The device template packages (templates/*.xml.gz) are not regenerated here. That stays the final step once these scripts are merged everywhere.

Testing

  • plugin_mikrotik: full Pest suite passes (135 tests). ScriptServerBackendsTest covers health on pre-3.4 and 3.4+ schemas, U when there's no data, the column allow-lists, the wireless uptime/column mapping, the interfaces index and num_indexes, and a drift guard against the poller's gauge map. The new tests fail against the previous scripts.
  • Cacti 1.2.x: ScriptServerHardeningProbeTest (both modes) and InstallerKeepsShippedScriptsTest pass.
  • Cacti develop: ScriptsHardeningTest, InstallerKeepsShippedScriptsTest and MikrotikSqlParameterizationTest pass. PHPStan reports no errors on the scripts, php-cs-fixer is clean, and the hardening-pattern, sink-inventory and hotspot guards report nothing new for these files.

The unit-test db_table_exists() stub now uses the existing db fixture mechanism (still defaults to false), so the schema detection can be tested.

The ss_mikrotik_*.php scripts had drifted three ways between Cacti 1.2.x,
Cacti develop and plugin_mikrotik. They are now byte-identical in all
three, PHP 5.4 compatible for 1.2.x, and pass the develop PHPStan and
php-cs-fixer rules.

- Every script checks that its plugin table exists, returns U when there
  is no data, and validates requested columns against an allow-list.
- ss_mikrotik_health.php takes the Hl* column names the shipped health
  graph templates pass. It prefers the RouterOS 7 gauge sensor in
  plugin_mikrotik_health_sensors when that table exists (plugin schema
  3.4) and falls back to the legacy column for pre RouterOS 7 devices
  and older plugin versions.
- ss_mikrotik_interfaces.php keeps the numeric interface index used by
  the shipped templates and reads the real cur* counter columns.
- num_indexes is returned, not printed, so script server reindex checks
  see it, and the queue tree and user queries support it too.
- ss_mikrotik_wireless_reg.php maps RxStrengthCh1 to the RxStrengthChl
  column and graphs registration uptime in seconds for both the SNMP and
  RouterOS API collectors.
- ss_mikrotik_snmpget.php validates the OID, polls with SNMP_POLLER and
  returns U when the get fails.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@TheWitness

Copy link
Copy Markdown
Member Author

Cacti companions: Cacti/cacti#8859 (1.2.x) and Cacti/cacti#8860 (develop). The 17 scripts are byte-identical across all three.

Pest runs from the Cacti root, so mikrotik_test_load_functions() resolved
scripts/ss_mikrotik_*.php to Cacti's own copies, which sit outside the
plugin root, and the suite aborted with "Unable to resolve required plugin
source". Try the plugin root first.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved collector regressions can overstate wireless uptime, select stale interface rows, and break existing interface, queue-tree, and health data sources.

5 open issues
What changed in this PR

Aligns the MikroTik script-server backends with coordinated Cacti 1.2.x and develop changes, restoring template-compatible data collection while preserving PHP 5.4 compatibility.

Changes:

  • Standardizes table checks, column allow-lists, parameter binding, and unknown-value handling across 17 scripts.
  • Updates health metric mapping, numeric interface indexes, wireless uptime conversion, and index-count returns.
  • Adds backend regression tests and configurable table-existence mocks.
File Description
tests/​Unit/​ScriptServerBackendsTest.php Adds health, wireless, and interface regression tests.
tests/​bootstrap-unit.php Makes table-existence checks configurable through fixtures.
scripts/​ss_mikrotik_wrcount.php Guards wireless registration counts.
scripts/​ss_mikrotik_wireless_reg.php Updates field mapping, uptime conversion, and missing-data handling.
scripts/​ss_mikrotik_wapcount.php Guards wireless access-point counts.
scripts/​ss_mikrotik_users.php Normalizes user-count results.
scripts/​ss_mikrotik_uptime.php Handles unavailable device uptime.
scripts/​ss_mikrotik_trees.php Guards queue-tree counts.
scripts/​ss_mikrotik_snmpget.php Validates numeric OIDs and handles failed reads.
scripts/​ss_mikrotik_qusers.php Standardizes user queries and index-count returns.
scripts/​ss_mikrotik_queues.php Standardizes queue queries and column validation.
scripts/​ss_mikrotik_qtrees.php Parameterizes tree lookups and changes index handling.
scripts/​ss_mikrotik_qcount.php Guards recent simple-queue counts.
scripts/​ss_mikrotik_procs.php Normalizes process-count results.
scripts/​ss_mikrotik_mem.php Handles unavailable memory measurements.
scripts/​ss_mikrotik_interfaces.php Uses numeric indexes and actual counter columns.
scripts/​ss_mikrotik_health.php Supports legacy health columns, aliases, and gauge sensors.
scripts/​ss_mikrotik_disk.php Handles unavailable storage measurements.
scripts/​ss_mikrotik_cpu.php Handles missing processor-load aggregates.
CHANGELOG.md Documents script compatibility and collection changes.

Review effort: Balanced

Comment thread scripts/ss_mikrotik_health.php Resolved
Comment thread scripts/ss_mikrotik_interfaces.php Resolved
Comment thread scripts/ss_mikrotik_interfaces.php Resolved
Comment thread scripts/ss_mikrotik_qtrees.php Resolved
Comment thread scripts/ss_mikrotik_wireless_reg.php Resolved
ladams and others added 2 commits November 20, 2026 15:39
- The friendly health aliases keep their own RouterOS 7 sensor lists
  (processorTemperature reads cpu-temperature, temperature falls back to
  board-temperature) and their legacy fallback columns.
- Interface data sources created by name still resolve, and a renamed
  interface's absent row no longer shadows the present one sharing its
  index; discovery only lists present interfaces.
- Queue trees are indexed with spaces replaced by underscores, as the
  queues are, and the value lookup tries every stored name form, so
  existing customer_tree data sources keep collecting.
- Numeric wireless registration uptimes are SNMP TimeTicks and are now
  divided by 100.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…dexes to trees and users

- num_indexes runs a COUNT with the same filters as the index list rather
  than fetching every row on each recheck.
- The queue tree and user data queries declare arg_num_indexes so index
  count changes trigger a reindex.
- Wireless registration values come only from present registrations, so a
  disconnected client graphs U instead of zeroed or stale values.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@sonarqubecloud

Copy link
Copy Markdown

@TheWitness
TheWitness merged commit 1f23565 into develop Nov 20, 2026
7 checks passed
@TheWitness
TheWitness deleted the fix/harmonize-ss-scripts branch November 20, 2026 21:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants