Skip to main content

Module doctor

hexz_cli::cmd::sys

Module doctor 

Source
Expand description

Implementation of the hexz doctor command.

Performs comprehensive system health checks to verify that all required dependencies, kernel modules, and system resources are available for Hexz operations. This command helps troubleshoot installation issues and validates the environment before running VMs or mounting snapshots.

§Diagnostic Checks Performed

§Binary Dependencies

fusermount:

  • Required for: FUSE mounting (hexz mount)
  • Checks: Command exists and returns version
  • Failure mode: Command not found or non-zero exit code

qemu-system-x86_64:

  • Required for: VM booting (hexz boot)
  • Checks: Command exists and returns version
  • Failure mode: Command not found or non-zero exit code

§Kernel Support

FUSE Kernel Module (/dev/fuse):

  • Required for: FUSE mounting
  • Checks: Device node exists
  • Failure mode: Device not found (module not loaded)
  • Fix: sudo modprobe fuse

§Network Connectivity

DNS Resolution:

  • Required for: Remote backends (HTTP, S3), package updates
  • Checks: Can resolve google.com to socket address
  • Failure mode: DNS lookup fails (network down, DNS misconfigured)

§Interpretation of Results

OK:

  • Component is installed and working correctly
  • No action required

NOT FOUND:

  • Binary is not in $PATH
  • Action: Install the required package
    • fusermount: Install fuse or fuse3 package
    • qemu-system-x86_64: Install qemu-system-x86 package

FAIL:

  • Binary exists but returned error or unexpected behavior
  • Action: Check binary is correct version or reinstall

FAIL (Device node not found):

  • Kernel module not loaded
  • Action: Load module with sudo modprobe fuse

FAIL (DNS error):

  • Network connectivity issue
  • Action: Check network configuration, DNS settings

§Use Cases

  • Pre-Installation Verification: Confirm all dependencies before first use
  • Troubleshooting: Diagnose why commands are failing
  • CI/CD Validation: Verify build environments have required tools
  • Bug Reports: Include doctor output in issue reports

§Common Usage Patterns

# Run comprehensive health check
hexz doctor

# Include in bug reports
hexz doctor > hexz-diagnostics.txt

# Verify installation
sudo apt install qemu-system-x86 fuse3
hexz doctor  # Should show all OK

Functions§

run
Executes the doctor command to perform system health checks.