# Install uxmax 2.0.3 (free)

This ZIP is the manual/offline distribution. Prefer the signed DEB or RPM
package when possible: both use the single package name
`zabbix-module-uxmax`, contain both manifest trees and automatically select
the compatible tree after a Zabbix frontend upgrade or rollback.

Extract the archive and run every command below from the directory that contains
`modern/`, `legacy/` and this `INSTALL.md` (normally `cd uxmax`).

## Choose exactly one payload

| Zabbix frontend | Copy from | Loader |
| --- | --- | --- |
| Zabbix 6.0 / 6.2 | `legacy/` | manifest v1 |
| Zabbix 6.4 / 7.0 / 7.2 / 7.4 | `modern/` | manifest v2 |

Never place both payloads in the frontend scan directory and never create a
second `uxmax-legacy` module. The active destination is always
`<frontend>/modules/uxmax`.

## Native host manual install

Find the active frontend root (7.2+ packages commonly use
`/usr/share/zabbix/ui`; older packages commonly use `/usr/share/zabbix`):

```sh
for root in /usr/share/zabbix/ui /usr/share/zabbix /usr/share/zabbix/php /srv/www/htdocs/zabbix; do
  [ -f "$root/include/defines.inc.php" ] && ZABBIX_FRONTEND="$root" && break
done
test -n "$ZABBIX_FRONTEND" || { echo "Zabbix frontend not found" >&2; exit 1; }
```

Set `PAYLOAD=legacy` for Zabbix 6.0/6.2 or `PAYLOAD=modern` for 6.4+,
then replace only this module's directory:

```sh
PAYLOAD=modern
sudo rm -rf "$ZABBIX_FRONTEND/modules/uxmax.new"
sudo mkdir -p "$ZABBIX_FRONTEND/modules/uxmax.new"
sudo cp -a "$PAYLOAD/." "$ZABBIX_FRONTEND/modules/uxmax.new/"
sudo rm -rf "$ZABBIX_FRONTEND/modules/uxmax"
sudo mv "$ZABBIX_FRONTEND/modules/uxmax.new" "$ZABBIX_FRONTEND/modules/uxmax"
```

In Zabbix open **Administration -> General -> Modules**, choose **Scan
directory**, and enable the single `uxmax` entry. On 6.0/6.2 the legacy loader
allows only one active implementation of a widget type; do not enable an old or
duplicate copy with the same id.

## Docker manual install

Set the web container and payload, detect its frontend root, then copy:

```sh
ZABBIX_WEB_CONTAINER=zabbix-web
PAYLOAD=modern
ZABBIX_FRONTEND=$(docker exec "$ZABBIX_WEB_CONTAINER" sh -c '
  for root in /usr/share/zabbix/ui /usr/share/zabbix /usr/share/zabbix/php; do
    [ -f "$root/include/defines.inc.php" ] && echo "$root" && break
  done')
test -n "$ZABBIX_FRONTEND" || { echo "Zabbix frontend not found in container" >&2; exit 1; }
docker exec "$ZABBIX_WEB_CONTAINER" rm -rf "$ZABBIX_FRONTEND/modules/uxmax"
docker exec "$ZABBIX_WEB_CONTAINER" mkdir -p "$ZABBIX_FRONTEND/modules/uxmax"
docker cp "$PAYLOAD/." "$ZABBIX_WEB_CONTAINER:$ZABBIX_FRONTEND/modules/uxmax/"
docker restart "$ZABBIX_WEB_CONTAINER"
```

Then scan/enable the one module in the Zabbix UI as above.

## Upgrading Zabbix

A ZIP cannot register a package-manager trigger. After any frontend upgrade or
rollback that crosses 6.2 <-> 6.4, repeat the copy with the newly compatible
payload before using the dashboard. DEB uses a pathname trigger and RPM uses a
systemd path watcher, so native package installations switch automatically and
do not require reinstalling the widget.

## DEB/RPM recovery

Normal package install/update is simply `apt install zabbix-module-uxmax` or
`dnf install zabbix-module-uxmax` after configuring the appropriate FREE/PRO
initMAX repository. FREE and PRO deliberately have the same package name: enable
the intended repository/edition, refresh package metadata, and upgrade or
reinstall `zabbix-module-uxmax`. Do not install a second `-pro` or `-legacy`
package. The native package versions are ordered FREE < PRO, so when both
channels are enabled apt/dnf selects PRO without a second package name or a
repository-priority tie-break. To return to FREE, disable the PRO channel and
perform an explicit package downgrade; an ordinary upgrade must never silently
replace PRO with FREE.

If automatic selection was administratively disabled, run
`/usr/libexec/initmax-widget-deploy-uxmax` once as root, then verify only
`modules/uxmax` is active.
