Skip to content

Troubleshooting: Hyper-V Server

If the appliance is deployed but isn't behaving as expected, work through the issues below. If it boots but never connects, or the tunnel drops right after it establishes, the cause is usually firewall L7/TLS inspection or NAC, not this platform: see Connectivity troubleshooting.

The VM boots to a black screen or shows "unsigned image's hash is not allowed (DB)"

Secure Boot is enabled. Hyper-V Gen2 VMs default to Secure Boot On with the "Microsoft Windows" template, which rejects the appliance's unsigned GRUB:

  1. Shut down the VM.
  2. In Hyper-V Manager: select the VM → Settings → Security.
  3. Uncheck Enable Secure Boot → OK.
  4. Start the VM.
The VM has no network / can't reach the headend

The NIC must be connected to an external virtual switch bound to a physical NIC, not Internal or the Default Switch (Windows Server has no Default Switch; Windows 11 client's Default Switch is NAT). Check:

  1. Settings → Network Adapter → confirm the switch is External and points to a physical NIC with internet access.
  2. If the NIC shows Not connected, attach it to an external switch (see the GUI guide or PowerShell guide).
The appliance boots but never connects

First confirm both VHDX are attached; without the cidata seed disk the appliance has no engagement identity and will not register. In Hyper-V Manager: select the VM → Settings and check that both the root disk and cidata.vhdx are attached. Then open the VM console: because this image is pre-registered, it shows a live status and troubleshooting dashboard (network, VPN tunnel, connectivity); use it to confirm the tunnel is up.

The VM won't boot from the disk / "no bootable device"

The root disk must be first in the boot order and the firmware must be Gen2 (UEFI). In Settings → Firmware, move the root hard drive to the top of the boot order. Make sure you created a Generation 2 VM; Gen1 cannot boot this image.

L2 tools (Responder, bettercap, ARP poisoning) don't work

MAC address spoofing must be On and the NIC must be on an external switch backed by a wired Ethernet adapter. Confirm both in Settings → Network Adapter → Advanced Features → MAC address spoofing: Enabled. If the physical NIC is Wi-Fi, move to a wired NIC for Layer-2 work.