Skip to content
Merged
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
7 changes: 7 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,12 @@
## ChangeLog

Documentation update (unreleased): Refresh README release/source compatibility,
installation guidance and source-checked behavior.

[All published release notes](https://github.com/Cacti/plugin_mactrack/blob/develop/docs/RELEASE_HISTORY.md)

[Version 5.0 release notes and upgrade guidance](https://github.com/Cacti/plugin_mactrack/blob/develop/docs/RELEASE_NOTES_5.0.md) · [Contributors and change history](https://github.com/Cacti/plugin_mactrack/blob/develop/docs/COMMITS_5.0.md)

--- 5.0 ---

* security: Add a version-safe CSP nonce (`plugin_mactrack_csp_nonce()`) to every inline `<script>` tag
Expand Down
30 changes: 30 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,28 @@ be helpful in recovering lost equipment. Through MacTrack's interface
monitoring feature, a Network Administrator can get a very good idea of where
utilization is, where there are errors, etc within their network.

## 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_mactrack/blob/develop/INFO) | 5.0 | 1.2.29 |
| [Published v5.0](https://github.com/Cacti/plugin_mactrack/releases/tag/v5.0) | 5.0 | 1.2.29 |

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 **`<cacti-root>/plugins/mactrack`**, using the directory
name `mactrack` rather than `plugin_mactrack`.

See [CHANGELOG.md](https://github.com/Cacti/plugin_mactrack/blob/develop/CHANGELOG.md) for the version history.

[All published release notes](https://github.com/Cacti/plugin_mactrack/blob/develop/docs/RELEASE_HISTORY.md)

[Version 5.0 release notes and upgrade guidance](https://github.com/Cacti/plugin_mactrack/blob/develop/docs/RELEASE_NOTES_5.0.md) · [Contributors and change history](https://github.com/Cacti/plugin_mactrack/blob/develop/docs/COMMITS_5.0.md)

## Features

* Scans Devices
Expand Down Expand Up @@ -53,6 +75,14 @@ Add Mactrack Site - Console -> Mactrack -> Sites
Add/import devices - Console -> Mactrack -> Devices -> Add device or Management -> Choose host -> Import into Mactrack Database
Create new or enable prepared Device Types - Console -> Mactrack -> Device Types

## Command-line scripts

| Script | Purpose |
| --- | --- |
| `cli/upgrade_database.php` | Runs the pending MacTrack database upgrade in the background. Console pages normally launch it when they detect an upgrade, but it can be run by hand. Options: `-d`, `--debug` for verbose progress; `-f`, `--force` to run even if another upgrade appears to be registered; `-v`, `--version` and `-h`, `--help` |
| `mactrack_import_ouidb.php` | Imports the IEEE OUI database into the vendor MAC table. Use `-f=ouifile` to import a manually downloaded file when the system cannot reach the IEEE over http; `-v`, `--version` and `-h`, `--help` are also accepted |
| `cli/upgrade_partitioning.php` | Checks and changes the history partitioning scheme; see below |

## Port, IP and 802.1x history partitioning

MacTrack keeps the MAC address history in `mac_track_ports` and the IP address
Expand Down
25 changes: 25 additions & 0 deletions docs/COMMITS_5.0.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# MacTrack 5.0 contributors and change history

[Release notes](RELEASE_NOTES_5.0.md) · [Compare changes](https://github.com/Cacti/plugin_mactrack/compare/v4.8...v5.0)

The released range is `v4.8..v5.0`.

## Contributors

Thank you to the contributors whose work is recorded in this range:

[@aqr199](https://github.com/aqr199), [@bmfmancini](https://github.com/bmfmancini), [@EkaterinePapava](https://github.com/EkaterinePapava), [@ka1lie](https://github.com/ka1lie), [@Linegod](https://github.com/Linegod), [@mixneko](https://github.com/mixneko), [@MukundaKatta](https://github.com/MukundaKatta), [@nakayama1869](https://github.com/nakayama1869), [@netniV](https://github.com/netniV), [@oz-agent](https://github.com/oz-agent), [@somethingwithproof](https://github.com/somethingwithproof), [@TheWitness](https://github.com/TheWitness), [@Thumb23](https://github.com/Thumb23), [@weblate](https://github.com/weblate), [@xmacan](https://github.com/xmacan), [@xxconn](https://github.com/xxconn), [@yeager](https://github.com/yeager).

Additional recorded author names are retained in the complete comparison when GitHub does not associate them with an account.

[Browse the paginated commit history](https://github.com/Cacti/plugin_mactrack/commits/v5.0).
Commit pages retain the original author and co-author records, including merge,
translation and automation history.

## Selected changes

- [8b300a21a7](https://github.com/Cacti/plugin_mactrack/commit/8b300a21a788271e217ede56df80b17419def5a3) Partition MAC history by scan date; by [@somethingwithproof](https://github.com/somethingwithproof).
- [85b58bedfb](https://github.com/Cacti/plugin_mactrack/commit/85b58bedfb0f3c594737a8f4503cec54808d5379) Extend partitioning and rebuilds to IP history; by [@TheWitness](https://github.com/TheWitness).
- [4a99a2f711](https://github.com/Cacti/plugin_mactrack/commit/4a99a2f711cd65f10f81d7c8afeda8e30c34f156) Exclude ports by regular expression; by [@TheWitness](https://github.com/TheWitness).

Use the comparison and paginated history to inspect other changes and original attribution.
10 changes: 10 additions & 0 deletions docs/RELEASE_HISTORY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# MacTrack release history

Release notes for every published GitHub release, with version-specific highlights, compatibility requirements, upgrade checks and linked contributor credits. Historical notes preserve the original detailed announcements.

- [v5.0](RELEASE_NOTES_5.0.md)
- [v4.8](releases/v4.8.md)
- [v4.7](releases/v4.7.md)
- [v4.2](releases/v4.2.md)
- [v4.1](releases/v4.1.md)
- [v4.0](releases/v4.0.md)
86 changes: 86 additions & 0 deletions docs/RELEASE_NOTES_5.0.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
# MacTrack 5.0: clearer scan visibility and more manageable address history

Released November 17, 2026. [Download MacTrack 5.0](https://github.com/Cacti/plugin_mactrack/releases/tag/v5.0).

MacTrack 5.0 helps administrators see scan progress, exclude uplink sightings
and manage MAC and IP history with partition-based retention. Its dashboard and
Process Status page show current activity and skipped runs.

## Highlights

- **See what collection is doing.** The new Dashboard tab brings status cards
together. Process Status reports scan phases, skipped runs, maintenance timings
and table sizes, so an administrator has somewhere to start investigating a delay.
- **Manage MAC and IP history together.** Both history tables support partitioning
by scan date. Retention drops whole expired partitions; existing installations
can rebuild their tables to use daily, weekly or unpartitioned layouts.
- **Keep uplink and trunk sightings out of scans.** Set regular expressions for
port names and aliases globally, per site or per device. The scanner reports
how many MAC sightings it skipped.
- **Keep useful observations through interruptions.** Recovery fixes preserve
completed scans during interrupted partition exchanges and retain staging data
when recovery cannot finish. Address reports also retain Layer 2 sightings
without current ARP data and identify older observations.
- **Read device and address results more clearly.** Collection fixes cover Cisco,
Aruba and other scanners. Interface and authorization status pills, theme
styles, and corrected MAC, IPv6 and vendor handling improve the reports used
during day-to-day troubleshooting.

The release also includes security hardening across administrative actions,
imports, exports and device collection. See the [full changelog](../CHANGELOG.md)
for individual changes.

## Upgrade decision guide

| Check | What to plan |
| --- | --- |
| Runtime | Cacti 1.2.29+ and PHP 8.2+; check Cacti's own PHP requirements too. |
| Storage | MySQL 8.0+ or MariaDB with partition support for partitioned history; unpartitioned tables remain supported. |
| Existing tables | Updating files does not rebuild history. Choose a layout and run the partitioning utility when ready. |
| Rebuild impact | Scheduled scans and maintenance pause; MAC/IP results are incomplete. Allow space for another copy of each table and its indexes. Large histories can take hours. |
| Recovery | If a rebuild stops, rerun the same command to resume. Keep the original rebuild tables until recovery completes. |

![MacTrack backup, layout selection, rebuild and verification workflow](images/release-workflow-5.0.svg)

### Upgrade and verify

1. Back up the database and plugin configuration/files together. Confirm the
runtime requirements before replacing the plugin files in `plugins/mactrack`.
2. Complete the plugin upgrade in Cacti's Plugin Management. Check the Cacti log
for upgrade errors before starting a history rebuild.
3. For an existing installation, review **Console > Settings > Mactrack > Port
and IP Address Partition Size** and both retention settings. Prefer daily or
weekly when planning a CLI rebuild; legacy hourly/per-scan layouts have
different maintenance behavior described in the partitioning guide.
4. During a maintenance window, use **MacTrack Utilities > Configure Port and IP
Address Partitioning**, or run this from the Cacti directory as the poller user:

```sh
php plugins/mactrack/cli/upgrade_partitioning.php
```

5. Check **View Partition Status** for both history tables and **Process Status**
for completion. Confirm the next scheduled scan finishes and fresh MAC/IP
sightings appear before closing the maintenance window.

The utility changes only tables that do not match the selected scheme.
[Read the partitioning and interruption-recovery guide](../README.md#port-and-ip-history-partitioning)
for the exact layout options and progress messages.

### Behavior changes to review

- **MacAuth email:** configured report frequencies now take effect. Review
recipients and frequency if reports previously never arrived.
- **Stored MAC values:** corrected binary SNMP decoding can change previously
malformed values. Review historical matches and affected authorizations.
- **Device exports:** SNMP credentials are omitted. Imports preserve existing
credentials; newly imported devices need credentials entered separately.

If rollback is needed, restore plugin files and the database from the same
pre-upgrade backup; do not assume an older plugin can use an upgraded schema.

## Contributors and change history

Thank you to the developers, translators, testers and reviewers who kept this
plugin moving forward. See the [linked contributor credits and selected commits](COMMITS_5.0.md).
Those links include the comparison, paginated history and original author records.
25 changes: 25 additions & 0 deletions docs/images/release-workflow-5.0.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
47 changes: 47 additions & 0 deletions docs/releases/v4.0.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# MacTrack 4.0: Cacti 1.x integration and interface updates

Historical release, published 2018-03-31. [Current releases](https://github.com/Cacti/plugin_mactrack/releases).

MacTrack 4.0 updates the plugin for the Cacti 1.x generation, adds internationalization and refreshes interface behavior and packet counters.

## Highlights

- Add internationalization and updated Spanish translations.
- Move interface backgrounds into CSS and use jQuery for DOM handling.
- Restore device Save and MAC port-name filtering controls, and fix site-query and interface-status display problems.
- Replace deprecated non-unicast packet counters with multicast and broadcast counters.

## Compatibility and upgrade checks

The [metadata shipped in v4.0](https://github.com/Cacti/plugin_mactrack/blob/v4.0/INFO) declares a minimum Cacti version of **1.1.1**. Follow the [documentation for this tag](https://github.com/Cacti/plugin_mactrack/blob/v4.0/README.md) for the matching installation and configuration steps.

Before replacing plugin files, back up the plugin/local configuration and its database together. Apply migration instructions only when they match the version you are upgrading from.

1. Review any external reports that depend on the old non-unicast counter names.
2. After upgrading, verify device editing, site/interface views and the configured language.

## Contributors and change history

Thank you to the developers, translators, testers and reviewers who contributed. For this earliest published release, linked authors are drawn from the repository history through its tag.

[@cigamit](https://github.com/cigamit), [@Dh0mp5eur](https://github.com/Dh0mp5eur), [@gan-dalf](https://github.com/gan-dalf), [@jpobeda](https://github.com/jpobeda), [@Linegod](https://github.com/Linegod), [@ronytomen](https://github.com/ronytomen), [@smiles1969](https://github.com/smiles1969), [@TheWitness](https://github.com/TheWitness).

[Browse commits and original author/co-author records](https://github.com/Cacti/plugin_mactrack/commits/v4.0).

<details>
<summary>Original detailed announcement and change list</summary>

--- 4.0 ---
- feature: Cacti 1.0 compatibility
- feature: i18n MacTrack
- feature: interface backgrounds in CSS
- feature: use jQuery exclusively for dom manipulation
- issue#22: Mactrack devices, 'Save' option missing.
- issue#17: MacTrack Show Site SQL Syntax
- issue#16: MacTrack Undefined indexes and offsets
- issue: MacTrack view Interfaces showed wrong color for interfaces UP.
- issue: MacTrack view MACs 'portname' filter option missing.
- feature: Removed deprecated ifInNUcastPkts and IfOutNUcastPkts and replaced by Ifin/OutMulticastPkt and Ifin/OutBroadcastPkt.
- feature: Updated spanish translations

</details>
36 changes: 36 additions & 0 deletions docs/releases/v4.1.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# MacTrack 4.1: translation support and clearer poller messages

Historical release, published 2018-03-31. [Current releases](https://github.com/Cacti/plugin_mactrack/releases).

This maintenance release improves translation support and resolves site-removal and poller-message problems.

## Highlights

- Make it easier for contributors to provide translated interface text.
- Fix site removal and clarify ambiguous MacTrack poller messages.

## Compatibility and upgrade checks

The [metadata shipped in v4.1](https://github.com/Cacti/plugin_mactrack/blob/v4.1/INFO) declares a minimum Cacti version of **1.1.10**. Follow the [documentation for this tag](https://github.com/Cacti/plugin_mactrack/blob/v4.1/README.md) for the matching installation and configuration steps.

Before replacing plugin files, back up the plugin/local configuration and its database together. Apply migration instructions only when they match the version you are upgrading from.

1. After upgrading, inspect the interface in the configured language and check a poller run for understandable status messages.

## Contributors and change history

Thank you to the developers, translators, testers and reviewers who contributed. Linked authors below are associated by GitHub with the comparison range.

[@cigamit](https://github.com/cigamit), [@ggomezsena](https://github.com/ggomezsena), [@jpobeda](https://github.com/jpobeda), [@netniV](https://github.com/netniV), [@ronytomen](https://github.com/ronytomen).

[Compare v4.0 to v4.1](https://github.com/Cacti/plugin_mactrack/compare/v4.0...v4.1) · [Browse commits and original author/co-author records](https://github.com/Cacti/plugin_mactrack/commits/v4.1).

<details>
<summary>Original detailed announcement and change list</summary>

--- 4.1 ---
- feature: Updates to facilitate i18n by contributors
- issue#25: Unable to remove Site
- issue#34: Ambiguous messages when running the MacTrack poller

</details>
Loading
Loading