Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,7 @@
* feature#435: Leave MACs on ports matching a regular expression out of a scan, so uplink and trunk ports stay out of the database: a new Ports to Ignore While Scanning setting for all devices plus a regular expression on each site and device, matched without regard to case against the port name and alias. The filter runs where every scanner stores its results, an invalid expression is logged and skipped, and the device run message reports how many MACs were skipped; the regular expression fields are text areas like the device Ports to Ignore, and each line is its own expression
* feature#451: Partition the IP address table (mac_track_ips) by scan date like the port table, and replace mactrack_convert.php with cli/upgrade_partitioning.php. It checks both tables against the Port Partition Size setting (or --partition=daily|weekly|disabled, which it saves as the setting; Disabled is now a setting value), reports when there is no drift, and rebuilds each drifted table in turn: rename it to <table>_rebuild, create it again with the retention and partitioning scheme, copy each scan date, then drop the original. The run is registered in the process registry, pauses scanning and database maintenance (a maintenance window that passes meanwhile is run by the poller as soon as the rebuild ends), shows a maintenance message on the MAC and IP address views, refuses changes to the history and defers the background database upgrade until it has finished, prints progress, and resumes after an interruption; new installs partition the IP table (following the saved Port Partition Size) and its retention drops whole partitions; --keep-old is removed; the README describes setting up and maintaining partitioning
* feature#455: Add the vendor Virtual/KVM Host for the unregistered MAC prefix 52:54:00 (QEMU/KVM virtual network cards) to the OUI database when the plugin is upgraded and after every IEEE OUI import, which removes the vendors the IEEE list does not hold; a prefix the database already holds is kept
* feature: Show the vendor Locally Admined MAC for any MAC address that begins with 52 and that the OUI database does not name (52:54:00 stays Virtual/KVM Host) in the MAC Addresses and IP Addresses views, and match it in their search; it is worked out when the view runs, so existing scan data is covered without a rescan or an upgrade
* feature: Add a Dashboard tab (the first MacTrack tab) presenting admin status cards in a draggable, add/remove
* feature: Add a root manifest.json and upgrade-time file pruning (mactrack_prune_files()) that removes tombstoned and dev-only paths
* feature: Add a status pill column to the 802.1x view after the username; clicking the pill drills down by setting the Status filter to that session status
Expand Down
39 changes: 35 additions & 4 deletions lib/mactrack_functions.php
Original file line number Diff line number Diff line change
Expand Up @@ -3863,6 +3863,34 @@ function mactrack_ports_load(string $table = 'mac_track_ports', int $batch = 100
'525400' => 'Virtual/KVM Host',
];

/**
* Returns the vendor name for a MAC address that no OUI row names: any
* address whose first octet is 52 is locally administered, and the IEEE
* registers no vendor for it. 52:54:00 is named by the OUI table.
*
* @param string $mac MAC address, with or without separators.
*
* @return string The label, or an empty string when the address is not 52.
*/
function mactrack_locally_administered_label(string $mac): string {
return strncmp($mac, '52', 2) === 0 ? __('Locally Admined MAC', 'mactrack') : '';
}

/**
* Returns a SQL expression for the vendor name of a MAC address column:
* the OUI table's name, or the locally administered label for a 52 address
* the OUI table does not name. The views select it and filter on it, so the
* label shows and is searchable without storing it on each scan row.
*
* @param string $mac_column Column holding the MAC address without separators.
*
* @return string SQL expression; the query must join mac_track_oui_database AS mtod.
*/
function mactrack_vendor_name_sql(string $mac_column): string {
return 'COALESCE(mtod.vendor_name, IF(SUBSTRING(' . $mac_column . ", 1, 2) = '52', "
. db_qstr(mactrack_locally_administered_label('52')) . ', NULL))';
}

/**
* Adds the well known unregistered MAC prefixes to the OUI table. A prefix
* the table already holds, such as one the IEEE registers later, is kept. The
Expand Down Expand Up @@ -5441,18 +5469,21 @@ function mactrack_tabs(): void {
* @param string $mac The MAC address (or at least its first 3 octets)
* to look up.
*
* @return string The vendor name, or 'Unknown' if no match is found.
* @return string The vendor name, the locally administered label for a 52
* address the OUI database does not name, or 'Unknown'.
*/
function mactrack_get_vendor_name($mac): string {
$vendor_mac = substr($mac,0,8);
// The OUI table keys vendors by the first six hex digits, without separators.
$mac = str_replace([':', '-', '.'], '', (string) $mac);
$vendor_mac = substr($mac, 0, 6);

$vendor_name = db_fetch_cell_prepared('SELECT vendor_name FROM mac_track_oui_database WHERE vendor_mac = ?', [$vendor_mac]);

if ($vendor_name != '') {
return $vendor_name;
} else {
return __('Unknown', 'mactrack');
}

return mactrack_locally_administered_label($mac) ?: __('Unknown', 'mactrack');
}

/**
Expand Down
6 changes: 5 additions & 1 deletion locales/po/cacti.pot
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ msgid ""
msgstr ""
"Project-Id-Version: Cacti\n"
"Report-Msgid-Bugs-To: developers@cacti.net\n"
"POT-Creation-Date: 2026-11-17 09:32-0500\n"
"POT-Creation-Date: 2026-11-17 13:16-0500\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: Cacti Developers <developers@cacti.net>\n"
"Language-Team: Cacti Developers <developers@cacti.net>\n"
Expand Down Expand Up @@ -130,6 +130,10 @@ msgstr ""
msgid "Not observed in latest scan"
msgstr ""

#: lib/mactrack_functions.php
msgid "Locally Admined MAC"
msgstr ""

#: lib/mactrack_functions.php
msgid "Mactrack Device Tracking OUI Database Import Results"
msgstr ""
Expand Down
9 changes: 5 additions & 4 deletions mactrack_view_arp.php
Original file line number Diff line number Diff line change
Expand Up @@ -255,10 +255,10 @@ function mactrack_view_get_ip_records(&$sql_where, $rows, $apply_limits = true):
if (read_config_option('mt_reverse_dns') != '') {
$sql_where .= ($sql_where != '' ? ' AND' : 'WHERE') .
' (mti.dns_hostname LIKE ' . db_qstr('%' . get_request_var('filter') . '%') . ' OR ' .
'mtod.vendor_name LIKE ' . db_qstr('%' . get_request_var('filter') . '%') . ')';
mactrack_vendor_name_sql('mti.mac_address') . ' LIKE ' . db_qstr('%' . get_request_var('filter') . '%') . ')';
} else {
$sql_where .= ($sql_where != '' ? ' AND' : 'WHERE') .
' (mtod.vendor_name LIKE ' . db_qstr('%' . get_request_var('filter') . '%') . ')';
' (' . mactrack_vendor_name_sql('mti.mac_address') . ' LIKE ' . db_qstr('%' . get_request_var('filter') . '%') . ')';
}
}

Expand Down Expand Up @@ -289,7 +289,8 @@ function mactrack_view_get_ip_records(&$sql_where, $rows, $apply_limits = true):
$sql_where .= ($sql_where != '' ? ' AND' : 'WHERE') . ' mti.scan_date = ' . db_qstr(get_request_var('scan_date'));
}

$sql_order = get_order_string();
$sql_order = get_order_string();
$vendor_sql = mactrack_vendor_name_sql('mti.mac_address');

if ($apply_limits && $rows != 999999) {
$sql_limit = ' LIMIT ' . ($rows * (get_request_var('page') - 1)) . ', ' . $rows;
Expand All @@ -301,7 +302,7 @@ function mactrack_view_get_ip_records(&$sql_where, $rows, $apply_limits = true):
// compared as a number is 0 and matched nothing. The interface table
// has no device_id index (its primary key leads with site_id), so the
// join must include site_id or every row scans the whole table.
$query_string = "SELECT mti.*, mts.site_name, mtod.*, mtin.ifName
$query_string = "SELECT mti.*, mts.site_name, $vendor_sql AS vendor_name, mtin.ifName
FROM mac_track_ips AS mti
LEFT JOIN mac_track_sites AS mts
ON mti.site_id = mts.site_id
Expand Down
13 changes: 7 additions & 6 deletions mactrack_view_macs.php
Original file line number Diff line number Diff line change
Expand Up @@ -676,13 +676,13 @@ function mactrack_view_get_mac_records(&$sql_where, &$sql_params, $rows, $apply_
' (mtp.dns_hostname LIKE ' . db_qstr('%' . get_request_var('filter') . '%') . ' OR ' .
'mtp.device_name LIKE ' . db_qstr('%' . get_request_var('filter') . '%') . ' OR ' .
'mtp.hostname LIKE ' . db_qstr('%' . get_request_var('filter') . '%') . ' OR ' .
'mtod.vendor_name LIKE ' . db_qstr('%' . get_request_var('filter') . '%') . ' OR ' .
mactrack_vendor_name_sql('mtp.mac_address') . ' LIKE ' . db_qstr('%' . get_request_var('filter') . '%') . ' OR ' .
'mtp.vlan_name LIKE ' . db_qstr('%' . get_request_var('filter') . '%') . ')';
} else {
$sql_where .= ($sql_where != '' ? ' AND' : 'WHERE') .
' (mtp.device_name LIKE ' . db_qstr('%' . get_request_var('filter') . '%') . ' OR ' .
'mtp.hostname LIKE ' . db_qstr('%' . get_request_var('filter') . '%') . ' OR ' .
'mtod.vendor_name LIKE ' . db_qstr('%' . get_request_var('filter') . '%') . ' OR ' .
mactrack_vendor_name_sql('mtp.mac_address') . ' LIKE ' . db_qstr('%' . get_request_var('filter') . '%') . ' OR ' .
'mtp.vlan_name LIKE ' . db_qstr('%' . get_request_var('filter') . '%') . ')';
}
}
Expand Down Expand Up @@ -714,7 +714,8 @@ function mactrack_view_get_mac_records(&$sql_where, &$sql_params, $rows, $apply_
}
}

$sql_order = get_order_string();
$sql_order = get_order_string();
$vendor_sql = mactrack_vendor_name_sql('mtp.mac_address');

if ($apply_limits && $rows != 999999) {
$sql_limit = ' LIMIT ' . ($rows * (get_request_var('page') - 1)) . ',' . $rows;
Expand All @@ -727,7 +728,7 @@ function mactrack_view_get_mac_records(&$sql_where, &$sql_params, $rows, $apply_
if (get_request_var('scan_date') == 3) {
$query_string = "SELECT
row_id, site_name, device_id, device_name, hostname, mtp.mac_address,
vendor_name, ip_address, dns_hostname, port_number,
$vendor_sql AS vendor_name, ip_address, dns_hostname, port_number,
port_name, vlan_id, vlan_name, MAX(date_last) AS scan_date, count_rec, MAX(active_last) AS active_last, mtm.mac_id
FROM mac_track_aggregated_ports AS mtp
LEFT JOIN mac_track_sites AS mts
Expand All @@ -743,7 +744,7 @@ function mactrack_view_get_mac_records(&$sql_where, &$sql_params, $rows, $apply_
} elseif ((get_request_var('scan_date') != 2)) {
$query_string = "SELECT
site_name, device_id, device_name, hostname, mtp.mac_address,
vendor_name, ip_address, dns_hostname, port_number,
$vendor_sql AS vendor_name, ip_address, dns_hostname, port_number,
port_name, vlan_id, vlan_name, scan_date, mtm.mac_id
FROM $ports_table AS mtp
LEFT JOIN mac_track_sites AS mts
Expand All @@ -758,7 +759,7 @@ function mactrack_view_get_mac_records(&$sql_where, &$sql_params, $rows, $apply_
} else {
$query_string = "SELECT
site_name, device_id, device_name, hostname, mtp.mac_address,
vendor_name, ip_address, dns_hostname, port_number,
$vendor_sql AS vendor_name, ip_address, dns_hostname, port_number,
port_name, vlan_id, vlan_name, MAX(scan_date) AS scan_date, mtm.mac_id
FROM $ports_table AS mtp
LEFT JOIN mac_track_sites AS mts
Expand Down
35 changes: 35 additions & 0 deletions tests/Integration/AggregatedPortsFreshnessDatabaseTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -224,4 +224,39 @@ public function testOldStagingRowsCannotBecomeCurrentSightings(): void {
$this->assertSame(1, (int) $this->db->query('SELECT COUNT(*) FROM mac_track_aggregated_ports')->fetchColumn());
$this->assertSame(self::PREVIOUS, $this->db->query('SELECT date_last FROM mac_track_aggregated_ports')->fetchColumn());
}

/**
* @param string $filter Text the vendor name must contain, or empty for all rows.
*
* @return array<string, string> MAC address => vendor name, with no vendor as an empty string.
*/
private function vendorNames(string $filter = ''): array {
$vendor = mactrack_vendor_name_sql('mti.mac_address');
$where = $filter === '' ? '' : ' WHERE ' . $vendor . ' LIKE ' . $this->db->quote('%' . $filter . '%');
$rows = $this->db->query("SELECT mti.mac_address, $vendor AS vendor_name
FROM (SELECT '525400AABBCC' AS mac_address UNION ALL SELECT '520000000001'
UNION ALL SELECT '001122334455' UNION ALL SELECT 'AABBCCDDEEFF') AS mti
LEFT JOIN mac_track_oui_database AS mtod ON mtod.vendor_mac = SUBSTRING(mti.mac_address, 1, 6)
$where")->fetchAll(PDO::FETCH_KEY_PAIR);
ksort($rows);

return array_map('strval', $rows);
}

/**
* @return void
*/
public function testEveryFiftyTwoAddressIsNamedExceptTheRegisteredKvmPrefix(): void {
$this->db->exec('CREATE TEMPORARY TABLE mac_track_oui_database (vendor_mac VARCHAR(8) NOT NULL, vendor_name VARCHAR(100) NOT NULL DEFAULT "", PRIMARY KEY (vendor_mac)) ENGINE=InnoDB');
$this->db->exec("INSERT INTO mac_track_oui_database VALUES ('525400', 'Virtual/KVM Host'), ('001122', 'Acme')");

$this->assertSame([
'001122334455' => 'Acme',
'520000000001' => 'Locally Admined MAC',
'525400AABBCC' => 'Virtual/KVM Host',
'AABBCCDDEEFF' => '',
], $this->vendorNames());
$this->assertSame(['520000000001' => 'Locally Admined MAC'], $this->vendorNames('Locally Admin'));
$this->assertSame(['525400AABBCC' => 'Virtual/KVM Host'], $this->vendorNames('KVM'));
}
}
70 changes: 70 additions & 0 deletions tests/Unit/LocallyAdministeredMacTest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
<?php
/*
+-------------------------------------------------------------------------+
| Copyright (C) 2004-2026 The Cacti Group |
| |
| This program is free software; you can redistribute it and/or |
| modify it under the terms of the GNU General Public License |
| as published by the Free Software Foundation; either version 2 |
| of the License, or (at your option) any later version. |
+-------------------------------------------------------------------------+
| Cacti: The Complete RRDtool-based Graphing Solution |
+-------------------------------------------------------------------------+
| http://www.cacti.net/ |
+-------------------------------------------------------------------------+
*/

/*
* A MAC address whose first octet is 52 is locally administered, so no
* vendor registers it. The views name it from the vendor name expression,
* which the filters use too, so the label is shown and searchable.
*/

require_once dirname(__DIR__, 2) . '/lib/mactrack_functions.php';

it('labels an address that begins with 52', function (string $mac) {
expect(mactrack_locally_administered_label($mac))->toBe('Locally Admined MAC');
})->with(['520000000001', '52:AA:BB:CC:DD:EE', '52-54-01-00-00-01']);

it('leaves other addresses unlabeled', function (string $mac) {
expect(mactrack_locally_administered_label($mac))->toBe('');
})->with(['', '5', '001122334455', '152233445566', 'A25254000001']);

it('builds the vendor name from the OUI row and then the label', function () {
$sql = mactrack_vendor_name_sql('mti.mac_address');

expect($sql)->toBe("COALESCE(mtod.vendor_name, IF(SUBSTRING(mti.mac_address, 1, 2) = '52', 'Locally Admined MAC', NULL))");
});

it('names an unknown 52 address in the lookup helper only when the OUI table has no name', function () {
$GLOBALS['__test_db_calls'] = [];
$GLOBALS['__test_matched_returns'] = [];
mactrack_test_queue_return_for('db_fetch_cell_prepared', 'mac_track_oui_database', 'Virtual/KVM Host');
expect(mactrack_get_vendor_name('52:54:00:aa:bb:cc'))->toBe('Virtual/KVM Host');

$GLOBALS['__test_matched_returns'] = [];
mactrack_test_queue_return_for('db_fetch_cell_prepared', 'mac_track_oui_database', '');
expect(mactrack_get_vendor_name('52:11:22:aa:bb:cc'))->toBe('Locally Admined MAC');
expect(mactrack_get_vendor_name('5211.22aa.bbcc'))->toBe('Locally Admined MAC');
expect(mactrack_get_vendor_name('00:11:22:aa:bb:cc'))->toBe('Unknown');
});

it('looks a full MAC address up by its six character OUI', function (string $mac) {
$GLOBALS['__test_db_calls'] = [];
mactrack_get_vendor_name($mac);

$call = end($GLOBALS['__test_db_calls']);
expect($call['params'])->toBe(['525400']);
})->with(['52:54:00:aa:bb:cc', '525400aabbcc', '52-54-00-aa-bb-cc', '5254.00aa.bbcc']);

it('uses the expression for the MAC and IP address views and their search', function (string $file, string $column) {
$src = file_get_contents(dirname(__DIR__, 2) . '/' . $file);

expect($src)->toContain("mactrack_vendor_name_sql('$column')");
expect($src)->not->toContain("'mtod.vendor_name LIKE");
expect($src)->not->toContain('(mtod.vendor_name LIKE');
expect($src)->toContain('$vendor_sql AS vendor_name');
})->with([
'MAC addresses' => ['mactrack_view_macs.php', 'mtp.mac_address'],
'IP addresses' => ['mactrack_view_arp.php', 'mti.mac_address'],
]);