Troubleshooting

Troubleshooting

Common issues and quick resolutions.

• Module will not load

  • Check kernel headers match the running kernel (/lib/modules/$(uname -r)/build).
  • Inspect dmesg | grep snakedrv for errors (signing, symbol mismatches).
  • Ensure modprobe or insmod is executed as root.

• /dev/snakedrv missing

  • Reload udev: udevadm control --reload-rules && udevadm trigger.
  • Verify the snakeengine group exists; re-run deploy.sh install to recreate rules.

• Permission denied opening the device

  • Add your user to snakeengine: sudo usermod -aG snakeengine $USER then re-login.
  • Check AppArmor/SELinux audit logs for denials.

• DKMS build failures

  • Remove stale versions: dkms remove -m snakedrv -v 1.0.0 --all.
  • Re-run sudo ./deploy.sh install (or --no-dkms to bypass).
  • Confirm linux-headers-$(uname -r) are installed.

• Secure Boot blocks loading

  • Sign the module with ./sign-module.sh and enroll the MOK.
  • Reboot and try sudo ./deploy.sh load again.

• No debug events or breakpoints not firing

  • Ensure the watched address is mapped and matches the access size/type.
  • DR slots are limited (4); clear existing breakpoints.
  • Confirm the process is still attached and running.

• Kernel panic or instability

  • Develop in a VM or dedicated test host.
  • Keep debug_level at 1; revert local modifications.
  • Validate against the shipping source and rebuild clean.