Upgrades

What happens when your sensor upgrades, how to watch one live, and how to confirm the new version is healthy afterwards.

When your sensor needs to upgrade, it stops itself, replaces its binary, restarts, and reports back. There is a short enforcement gap during the swap, and no action is required from you — your administrator pushes the new release from the Panel and the sensor takes it from there.

This page covers what an upgrade looks like from your side: what changes on the host, how to watch one happen, and the post-upgrade checks you can run to confirm the new version is healthy.

Why upgrades pause enforcement#

The sensor sits in the kernel and intercepts system calls. Replacing the running binary while it is actively attached to the kernel — with fanotify watches, eBPF programs, and (optionally) HTTP redirect rules in place — would be risky. So the sensor takes itself out of the way first:

1. Stop the sensor’s interception components.
2. Replace the binary while the sensor is down.
3. Restart and verify.

This creates a short window — usually a handful of seconds — during which no syscall monitoring is happening on that host. The trade-off is intentional: a clean, predictable swap is safer than trying to mutate a running interception stack in place.

Watch the upgrade live#

If you want to see an upgrade as it runs (during the brief swap window), tail the upgrade-related journal entries on the host:

journalctl -u imunifyai-sensor-upgrade.service -f

You will see the upgrade machinery progress through fetching the new binary, verifying its checksum, swapping it in, and restarting the sensor. The whole thing typically takes well under a minute.

You can also inspect the durable on-host state file while an upgrade is in flight:

cat /var/lib/imunifyai/sensor/upgrade-state.json

This file records which phase the upgrade is currently in and what version it is moving from and to. It is kept on disk for about an hour after the upgrade finishes so you can read it after the fact, then garbage-collected.

Confirm the upgrade succeeded#

After an upgrade completes, you can verify the host ended up healthy and on the new version with this short checklist:

1. The sensor service is active.

   systemctl is-active imunifyai-sensor.service
   

   Expected: active.

2. The running binary matches the target version.

   /usr/local/bin/imunifyai-sensor --print-version
   

   Expected: the new version your administrator pushed.

3. The upgrade state file shows completed.

   cat /var/lib/imunifyai/sensor/upgrade-state.json
   

   Expected: a phase of completed and matching from_version / to_version fields.

4. If HTTP interception was enabled on this host, the mitmproxy sidecar is back.

   systemctl is-active imunifyai-sensor-mitmproxy.service
   iptables -t nat -L OUTPUT -n | grep imunifyai-sensor-http-intercept || true
   

   Expected: the service is active and the redirect rules are present again.

5. The Panel agrees. Open the Panel’s Sensors page; the row for this host should show the new sensor version and a recent heartbeat. If the panel still shows the old version, give it 30 seconds and refresh — sensor heartbeats are not instant.

If any of those checks fails, see Troubleshooting. The most common post-upgrade issue is the sensor refusing to start because LSM BPF is not active in the running kernel; the troubleshooting page has the one-time GRUB fix.

Resume a stalled upgrade#

In the rare case that an upgrade does not converge on its own — for example, the host lost power partway through — the upgrade machinery is designed to reconcile itself on the next boot or within five minutes via a recover timer. If you want to nudge it without waiting, you can restart the upgrade service explicitly:

sudo systemctl start imunifyai-sensor-upgrade.service

If the upgrade is unrecoverable and you want to roll the sensor back to the previous version manually, run the rollback command:

sudo /etc/imunifyai/sensor/upgrade-controller.sh rollback

This restores the previous binary from /usr/local/bin/imunifyai-sensor.prev and restarts the sensor. The Panel will show the older version on the next heartbeat. If you reached this command after a failed upgrade, also let your administrator know — they may want to investigate the new release before re-pushing it.