Sensor / Troubleshooting

Troubleshooting

What to do when the sensor fails to start, can't reach the server, or refuses to attach because LSM BPF isn't enabled — including the one-time GRUB fix.

This page collects the failures customers hit most often after installing or upgrading the sensor, and what to do about each one. Start with Sensor fails to start — almost every problem either is that or surfaces through it.

Sensor fails to start#

Read the logs for the specific error:

journalctl -u imunifyai-sensor --since "5 min ago" --no-pager

Common causes:

Binary not found#

If imunifyai-sensor is not found after installation, check that it was installed to /usr/local/bin/:

ls -la /usr/local/bin/imunifyai-sensor

If missing, the installer may have failed during the download step. Re-run the install command with a fresh install token from your administrator.

LSM BPF not active#

If the installer — or the sensor service itself after upgrade — fails with LSM BPF is not active in the running kernel, or the Panel shows a red LSM BPF pill on your sensor’s row, your kernel supports LSM BPF but it is not enabled in the boot parameters.

Starting with v0.0.19, the sensor exits with status 1 at startup when LSM BPF is missing, instead of falling back to a weaker monitor-only mode. Fix it once (this requires a reboot):

# 1. Confirm the kernel supports LSM BPF:
grep CONFIG_BPF_LSM /boot/config-$(uname -r)
# Expected: CONFIG_BPF_LSM=y

# 2. Add 'bpf' to the lsm= list in /etc/default/grub.
#    Edit the GRUB_CMDLINE_LINUX line so it reads e.g.:
#    GRUB_CMDLINE_LINUX="... lsm=lockdown,yama,apparmor,bpf"
sudo vi /etc/default/grub

# 3. Regenerate GRUB config:
sudo update-grub                                # Debian/Ubuntu
# or:
sudo grub2-mkconfig -o /boot/grub2/grub.cfg     # RHEL/Rocky/Alma

# 4. Reboot:
sudo reboot

# 5. Verify after reboot:
cat /sys/kernel/security/lsm    # must contain 'bpf'

# 6. Restart the sensor (if it was already installed):
sudo systemctl restart imunifyai-sensor

The Panel’s LSM BPF pill should turn green on the next heartbeat.

If instead the installer reports Kernel does not support LSM BPF (CONFIG_BPF_LSM is not set), your kernel is too old or was not built with LSM BPF. Install a newer kernel package and reboot into it:

BTF not available#

If the installer reports that BTF is not available:

# Check if your kernel config has BTF enabled:
grep CONFIG_DEBUG_INFO_BTF /boot/config-$(uname -r)

If BTF is not compiled into your kernel, you may need to upgrade to a newer kernel (5.8+) or install a BTF-enabled kernel package for your distribution. Contact your system administrator for assistance.

Cannot connect to server#

Verify the server address in the sensor configuration:

cat /etc/imunifyai/sensor/config.yaml | grep server

Test connectivity:

curl -s https://panel.imunify.ai/health

If the health endpoint is unreachable, check firewall rules and the configured server.url. Current sensors use one URL for both REST and gRPC; configs containing server.host, server.port, server.rest_port, or server.tls are from the old schema. Current sensors migrate those fields to server.url on first boot; if migration fails, reinstall with a fresh install one-liner from your administrator.

Install token rejected#

If you see HTTP 410 when running the install command, the token has already been used. Each install token is single-use. Request a new token from your administrator.

If you see HTTP 401 or 403, the token may have expired (install tokens are valid for 24 hours). Generate a new one from Add Sensor in the Panel.

Last updated Jun 16, 2026