Upgrade to a New Version
To upgrade to 1.2.0 from an earlier release, you must run dspm-installer upgrade on the server, whatever your install type. The Settings page, automatic updates, and dspmctl can't make this upgrade. See Upgrade to 1.2.0.
How you upgrade Access Analyzer depends on how you installed it.
| Install | How it upgrades |
|---|---|
| Connected (the default) | The upgrade downloads the new release's offline media from Netwrix, verifies it, and loads it into the cluster. Start it from the Settings page, let the version poller start it, or run dspm-installer upgrade --download on the host. |
| Air-gapped | You download the new media on a connected machine, copy it to the server, and run dspm-installer upgrade --bundle-dir. |
Registry (a connected install made before media installs, or with DSPM_MEDIA_INSTALL=false) | ArgoCD pulls new releases from the Netwrix registry. You tell it which version to run with dspmctl. Convert a registry install to downloaded media to upgrade the same way as any connected install. |
Pick the tab that matches your install. You upgrade only the server: deployed agents run the new release's connectors from their next scan. See Agents and upgrades.
The installer installs dspmctl at /usr/local/bin/dspmctl. It's a small shell wrapper that runs kubectl exec into the dspmctl pod in the argocd namespace. The dspmctl program in that pod changes the ArgoCD applications through the Kubernetes API, with its own service account. It doesn't sign in to ArgoCD, and you don't need the argocd command-line interface (CLI) on the host.
Run dspmctl and dspm-installer with sudo. Only root can read the default kubeconfig at /etc/rancher/k3s/k3s.yaml, so without sudo, kubectl falls back to localhost:8080 and fails with "connection refused."
On Red Hat Enterprise Linux (RHEL) and similar distributions, /usr/local/bin usually isn't on the PATH, so dspm-installer and dspmctl can fail with command not found. Run them by their full paths instead, for example sudo /usr/local/bin/dspm-installer or sudo /usr/local/bin/dspmctl.
Download the Latest Installer
Before every upgrade, whatever your install type, download the latest dspm-installer and run the upgrade with it. The upgrade command exists only in newer installers, and an installer from an older release can reject newer media.
-
Read your license key into an environment variable.
read -rs LICENSE_KEY && export LICENSE_KEY -
Download the installer and replace the copy in
/usr/local/bin.ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')TMP_FILE=$(mktemp)curl -Lf -o "$TMP_FILE" \"https://raw.pkg.keygen.sh/v1/accounts/netwrix/artifacts/dspm-installer-linux-$ARCH?auth=license:${LICENSE_KEY}&channel=stable"sudo install -m 0755 "$TMP_FILE" "/usr/local/bin/dspm-installer"rm -f "$TMP_FILE"Keep the
channel=stableparameter. Without it, the registry can return a pre-release build. -
Confirm the version.
dspm-installer --versionThe output should show
dspm-installer version 1.0.21or later. Release and installer versions lists the installer for each release.
If the server has no network access, run these commands on a connected machine with the same architecture, then copy /usr/local/bin/dspm-installer to the same path on the server with scp or removable media.
Check Which Version Is Running
Check which version is running:
sudo dspmctl version
Compare the output with the latest release, 1.2.0. If they match, Access Analyzer is already up to date. Release and installer versions lists every release.
Upgrade to 1.2.0
An install on a release earlier than 1.2.0 can upgrade to 1.2.0, or to any later release, only with dspm-installer upgrade on the server. This applies to every install type. The Settings page, automatic updates, and dspmctl can't make this upgrade.
Download the latest installer first, then run the command for your install type:
| Install | Run |
|---|---|
| Connected | sudo dspm-installer upgrade --download |
| Air-gapped | sudo dspm-installer upgrade --bundle-dir <path-to-archive>, after you download the new release |
| Registry | sudo dspm-installer upgrade --download, which also converts the install to downloaded media |
These commands upgrade to the newest stable release. To upgrade to a specific release, add --target-revision <version> to the connected or registry command.
After the install runs 1.2.0 or later, every upgrade method on this page works.
Choose an Upgrade Command
Find your situation in the table and run its command on the server. Every command in the table runs dspm-installer upgrade.
| You want to | Run |
|---|---|
| Upgrade a connected install to the newest stable release | sudo dspm-installer upgrade --download |
| Upgrade a connected install to a specific release | sudo dspm-installer upgrade --download --target-revision <version> |
| Upgrade a connected install from media you copied to the server | sudo dspm-installer upgrade --bundle-dir <path-to-archive> |
| Upgrade an air-gapped install | sudo dspm-installer upgrade --bundle-dir <path-to-archive> |
| Convert a registry install to downloaded media and upgrade it | sudo dspm-installer upgrade --download --target-revision <version> |
| Convert a registry install to downloaded media on the same release | sudo dspm-installer upgrade --download --target-revision <installed-version> |
| Connect an air-gapped install | sudo --preserve-env=LICENSE_KEY dspm-installer upgrade --connect |
| Connect an air-gapped install and upgrade it | Run upgrade --connect, then upgrade --download --target-revision <version> as a second command |
| Redeploy the installed release, or downgrade | Add --allow-downgrade to the upgrade command |
| Preview any of these without changing anything | Add --dry-run |
Without --target-revision, upgrade --download upgrades to the newest stable release. For converting and connecting, see Convert or connect an install.
These changes have no command:
- Connected to air-gapped.
--connectworks in one direction only, so returning to air-gapped takes a reinstall.upgrade --bundle-dirworks on a connected install, but the install stays connected: the version poller stays on and the license key stays saved. - Connect and upgrade in one run.
--connectdoesn't redeploy or change the release, so the upgrade is a second command. - Registry install straight to air-gapped media. Converting needs
--download, so convert the registry install while it's online first. upgrade --downloadon an air-gapped install. The command refuses and exits with code16. Runupgrade --connectfirst.
Upgrade
- Connected upgrade
- Air-gapped upgrade
- Registry upgrade
All three ways to upgrade a connected install run the same upgrade. Only one upgrade can run at a time.
Upgrade from the Settings page
You need the Administrator role.
An install on a release earlier than 1.2.0 can't upgrade to 1.2.0 from this page. Upgrade it with the installer instead.
- Go to Settings > System.
- Select the version and click Update. The confirmation says the app downloads the release media and is briefly unavailable.
- Watch the progress through these phases: Checking prerequisites, Downloading media, Deploying, and Waiting for services.
- When the upgrade finishes, reload the page.
If the upgrade fails, the page shows the reason and what to do next.
| What you see | What it means |
|---|---|
| Check the license | Netwrix rejected the license. Nothing changed. |
| The upgrade couldn't start, No release available, or Download failed | Nothing changed. For a download failure, free some disk space and click Retry. |
| Retry or contact support | The installer couldn't load the media. Nothing changed. |
| The upgrade failed while applying, The new version didn't become healthy, or The new version failed to start | The cluster may have changed. Click Roll back to return to the previous version. |
| Contact support | The installer couldn't apply the new version. |
If another upgrade is already running, the page says so.
Upgrade automatically
The version poller checks for new releases every 12 hours. When a newer release matches the install's version constraint and Netwrix has published its media, the poller starts the same upgrade the Settings page starts.
Automatic updates can't upgrade an install on a release earlier than 1.2.0 to 1.2.0. Upgrade it with the installer instead.
If an upgrade fails partway through deploying, the poller doesn't retry it. Fix the cause, then run sudo dspm-installer upgrade --download on the host.
Upgrade from the host
Upgrade to the newest stable release:
sudo dspm-installer upgrade --download
Upgrade to a specific release:
sudo dspm-installer upgrade --download --target-revision 1.2.0
--download reads the license key from /etc/dspm/installer.yaml. On a host without a saved key, pass the key through the environment, as the install does:
read -rs LICENSE_KEY && export LICENSE_KEY
sudo --preserve-env=LICENSE_KEY dspm-installer upgrade --download
To upgrade a connected install from media you already copied to the server, pass the archive instead of --download:
sudo dspm-installer upgrade --bundle-dir /etc/dspm/media/dspm-airgap-media-v<version>-<arch>.tar.gz
The install stays connected afterwards. See Download the new release for how to get the archive.
If the cluster already runs the newest release, the command prints The cluster is already on the newest release (v<version>); nothing was changed. and exits 0. A scheduled run can use this to distinguish "nothing to do" from a failure.
Add --dry-run to check the preconditions and free space and print the upgrade plan without downloading anything.
What an upgrade does
- Checks the preconditions: the cluster runs from offline media, the root application's automated sync is on, the release is newer than the installed one, and the server has enough disk space. If any check fails, the upgrade exits with code
16and changes nothing. - Downloads and checks the media, or reuses media already on disk.
- Pauses automated sync, so ArgoCD doesn't act on a half-loaded release.
- Removes images older than the previous release from the in-cluster registry. The registry keeps the current release and the one before it.
- Loads the new charts and images into the cluster and points the root application at the new version.
- Turns automated sync back on and waits for every application to become healthy.
- Deletes the downloaded media.
If something interrupts the upgrade (Ctrl-C, a dropped SSH session, or a stopped pod), the upgrade turns automated sync back on before it exits. Run the same command again to finish the upgrade.
An air-gapped upgrade loads the new release into the cluster from the newer offline media archive. The upgrade reads only the cluster and the media, so it needs no network access. It upgrades the Access Analyzer services and ArgoCD. It doesn't upgrade the underlying k3s platform or the offline package manager. If the media targets a different version of either, the command prints a warning that names both versions and continues with the installed ones.
Before it changes anything, the command checks that the server runs from offline media, that the media carries a newer version than the one installed, and that automated sync is on for the netwrix app. If any check fails, it exits with code 16 and nothing in the cluster changes.
Download the new release
Download the latest installer first. Then download the new media the same way you did for the install, with the new release's version number.
-
Read your license key into an environment variable, if it isn't already set.
read -rs LICENSE_KEY && export LICENSE_KEY -
Download the offline media archive for the new release.
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')VERSION='1.2.0' # the latest release; change it to upgrade to another onesudo mkdir -p /etc/dspm/mediasudo curl -Lf -o "/etc/dspm/media/dspm-airgap-media-v${VERSION}-${ARCH}.tar.gz" \"https://raw.pkg.keygen.sh/v1/accounts/netwrix/artifacts/dspm-airgap-media-v${VERSION}-${ARCH}.tar.gz?auth=license:${LICENSE_KEY}&channel=stable"Don't extract the archive, and keep its name as downloaded. If the server has no network access, run these commands on a connected machine with the same architecture, then copy the archive to the server with
scpor removable media, along with the installer. Keep thechannel=stableparameter. Without it, the registry can return a pre-release build. -
Confirm the archive downloaded completely.
ls -lh "/etc/dspm/media/dspm-airgap-media-v${VERSION}-${ARCH}.tar.gz"The file should be about 3.5 GB. If it's much smaller, the download didn't finish. Repeat step 2.
Run the upgrade
-
Preview the upgrade.
--dry-runvalidates the media and the preconditions and prints the planned changes without touching the cluster.sudo dspm-installer upgrade --bundle-dir /etc/dspm/media/dspm-airgap-media-v<version>-<arch>.tar.gz --dry-runThe summary shows the installed version, the version in the media, and the k3s, offline package manager, and ArgoCD versions on each side. Fix anything it reports before you continue.
-
Run the upgrade.
sudo dspm-installer upgrade --bundle-dir /etc/dspm/media/dspm-airgap-media-v<version>-<arch>.tar.gzThe command loads the chart snapshot and container images into the cluster, applies the bundled ArgoCD manifest, and re-seeds the registry pull secret into every application namespace. It then re-pins the
netwrixapp to the new version and records the previous version in thedspm.netwrix.com/previous-target-revisionannotation. Finally, it waits for every application to become Synced and Healthy. The wait defaults to 30 minutes. Pass--timeoutwith a duration such as45mto change it.Exit code
0means the cluster runs the new release and every application is healthy. For any other code, see Upgrade exit codes.
--bundle-dir takes the archive directly. An extracted media directory also works. --allow-downgrade lifts the "newer version" check for an intentional redeploy of the same version or a downgrade. --kubeconfig and --argocd-namespace override the defaults if you installed with non-default values. See The upgrade command for every flag.
A host that later gains internet access can connect the air-gapped install to upgrade like a connected install.
A registry install pulls releases from the Netwrix registry. Upgrading it to a newer release converts it to downloaded media first, so later upgrades work like any connected install. The conversion downloads about 3.5 GB of media, takes about 15 to 20 minutes, and makes the app briefly unavailable. You can't undo it. See Convert a registry install for what the conversion does.
Any of these starts the upgrade and its conversion:
- The Settings page: select the new version, then select Update.
- The automatic updater: when a newer release that matches the install's version constraint appears, it starts the upgrade on its next run. It checks every 12 hours.
dspmctlon the host, with the following steps.dspm-installer upgrade --download, as Convert a registry install shows.
To upgrade with dspmctl:
-
Check that automated sync is on for the
netwrixapplication. The upgrade refuses to start while it's off.sudo dspmctl auto-statusIf it's off, turn it on:
sudo dspmctl enable-auto netwrix -
Start the upgrade and follow it until it finishes:
sudo dspmctl set-revision netwrix <version> --waitThe command explains the conversion, starts the upgrade job, and prints its progress. It exits with the job's exit code. The job pauses automated sync while it deploys and turns it back on when it finishes, so you don't run
syncorenable-autoyourself.If your session drops while the upgrade runs, the job keeps going. Check on it again with:
sudo dspmctl upgrade-status --wait
If you're upgrading from a version earlier than 1.1.7, the Apache Tika resources from the older release can remain in the cluster after the upgrade and keep the app showing as not healthy. Preview what a pruning sync removes, confirm that the output lists only the Tika resources, and then run the sync with --prune:
sudo dspmctl sync netwrix --prune --dry-run
sudo dspmctl sync netwrix --prune
To roll a registry install back to an older release, see Rolling back to a previous version. A rollback re-pins the install in the registry, and its next upgrade converts it.
Roll Back an Upgrade
On a connected install, when an upgrade fails after it starts applying the new version, the Settings page offers Roll back. The button points the install back at the version the upgrade started from.
From the host, a rollback is a re-pin. The previous chart tag and images stay in the cluster, so you don't need the old media. The in-cluster registry keeps only the previous release's images, so a rollback works one release back. To roll back further, you need that release's media again.
For the precautions to take first and the full procedure, see Rolling back to a previous version. Read the previous version from the annotation, then run all three dspmctl commands. set-revision turns off automated sync so self-heal doesn't immediately re-sync the new version, sync applies it, and enable-auto turns automated sync back on. If you skip enable-auto, the netwrix app never syncs again, and the next dspm-installer upgrade refuses to run.
sudo kubectl -n argocd get application netwrix \
-o jsonpath='{.metadata.annotations.dspm\.netwrix\.com/previous-target-revision}'
sudo dspmctl set-revision netwrix v<previous>
sudo dspmctl sync netwrix
sudo dspmctl enable-auto netwrix
sudo dspm-installer wait-for-apps
A re-pin doesn't roll back database schema changes the new release made.
Upgrade Exit Codes
| Code | Meaning | What to do |
|---|---|---|
0 | The cluster runs the new release and every application is Synced and Healthy, or the cluster already runs the newest release. | Nothing. |
10 | Netwrix rejected the license key. | Check the key, then run the command again. |
15 | The command couldn't load or deploy the media, and the cluster is still on the previous release. When it converts a registry install, the command also exits with this code when an agent node runs on a different CPU architecture from the server. | Fix the cause and run the command again. The deploy is idempotent. |
16 | A precondition failed, such as no cluster or root application, the install type doesn't match the command, the release isn't newer, automated sync is off, or the media volume lacks free space. Nothing changed. | Read the message. For automated sync, run sudo dspmctl enable-auto netwrix first. For a same-version redeploy, add --allow-downgrade. For free space, free space on the media volume or use --tmp-dir. |
17 | The command couldn't download, verify, or unpack the media. Nothing changed. | Run the command again. It resumes the download. |
20 | No release matches --target-revision, or the release has no media for this architecture. | Check the release number. |
60 | The command couldn't apply the new version, couldn't switch to the in-cluster source, or couldn't turn automated sync back on. | Check /var/log/dspm-installer.log, run sudo dspmctl enable-auto netwrix, and run the command again. |
70 | The new version applied, but ArgoCD didn't acknowledge it or the release didn't become healthy within --timeout. The new pin stays in place and ArgoCD keeps reconciling. | Run sudo dspm-installer wait-for-apps to keep waiting, or roll back. |
71 | A pod failed to start. | Check the failing pod with sudo kubectl get pods -A, then roll back or fix the cause and run the command again. |
Troubleshooting an Upgrade
Automated sync is still off after a failed upgrade. Run the same upgrade command to finish it, or turn sync back on with sudo dspmctl enable-auto netwrix. On the netwrix app, enable-auto also clears the pause an unfinished upgrade leaves.
An upgrade exits with code 70, and running it again says the cluster is already on that version. The new version is in place but wasn't healthy in time. Run sudo dspm-installer wait-for-apps.
The upgrade stops with exit code 16 about free space. Free space on the media volume, or point the media elsewhere with --tmp-dir. The check counts media from other releases as free, because the upgrade deletes them, but it deletes nothing unless the check passes.
The progress bar shows garbled characters. Run with --progress ascii, or set DSPM_PROGRESS=ascii.
Checking the Result
Wait one to five minutes for the pods to restart, then check the version again:
sudo dspmctl version
The output should show the version you set. Pod restarts take longer on a busy server, so if the version hasn't changed after five minutes, wait another two or three minutes and run the command again.
For a detailed view of the sync, read the netwrix application's status:
sudo kubectl get application netwrix -n argocd \
-o custom-columns='REVISION:.spec.source.targetRevision,SYNC:.status.sync.status,HEALTH:.status.health.status'
Check that REVISION shows the version you set and SYNC shows Synced. The netwrix app manages only the child Application resources; each child still has to sync on its own to roll new pods. A child with auto-sync enabled syncs shortly after the parent. Otherwise, sync it directly, for example:
sudo dspmctl sync netwrix.webapp
Troubleshooting: dspmctl says an operation is already in progress
If a dspmctl command fails with an operation on <app> is already in progress, ArgoCD is still running an earlier sync of that application. A sync keeps running in ArgoCD even if you press Ctrl-C while dspmctl sync waits for it. Wait for the sync to finish, then run the command again.
If the operation makes no progress after the ArgoCD application controller restarted, the request is stale. Clear it, then run the command again:
sudo kubectl -n argocd patch application <app> --type=json -p '[{"op":"remove","path":"/operation"}]'