Category: Virtualization

As you know, Hyper-V is not just a server virtualization software anymore. Today, you can find Hyper-V technology across different operating systems, products, and services, like Windows Defender Application Guard, Windows Sandbox, Hyper-V Containers, or many more. Thanks to Ben Armstrong from the Hyper-V team, I found out that there is a tool in Windows to troubleshoot these Hyper-V containers called hcsdiag.exe or Hyper-V Host Compute Service Diagnostics Tool. The Hyper-V Host Compute Service Diagnostics Tool (HCSDiag.exe) is available in Windows 10 and Windows Server 2019 if you have the Hyper-V roles or virtualization features enabled, and can be helpful to troubleshoot Hyper-V containers, virtual machines (VMs), Windows Sandbox, Windows Defender Application Guard, Windows Subsystem for Linux 2 and more.

HCSDiag.exe – Hyper-V Host Compute Service Diagnostics Tool

Let’s have a look at the HCSDiag.exe, which you can find in C:\Windows\System32. It provides you with a couple of different commands and options. However, keep in mind that not all features work with every type of container. Some features are limited to scenarios where the VM is being used under the same user context as the host, where it is all about protecting the host from the guest and not the guest from the host like in the server version of Hyper-V.

To install Hyper-V, check out the following posts:

• Install Hyper-V on Windows 10 using PowerShell
• Install Hyper-V on Windows Server using PowerShell

HCSDiag.exe

hcsdiag <command> [options…]

• list
  Lists running containers and VMs.
• exec [-uvm] <id> <command line>
  Executes a process inside the container.
• console [-uvm] <id> [command line]
  Launches an interactive console inside the container.
• read [-uvm] <id> <container file> [host file]
  Reads a file from the container and outputs it to standard output or a file.
• write [-uvm] <id> [host file] <container file>
  Writes from standard input or a host file to a file in the container.
• kill <id>
  Terminates a running container.
• share [-uvm] [-readonly] [-asuser] [-port <portnumber>] <id> <host folder> <container folder>
  Shares a host folder into the container.
• vhd [-uvm] <id> <host vhdx file> <container folder>
  Shares a virtual hard disk file into the container.
• crash <id>
  Forces a crash of the virtual machine hosting the container (only works for containers hosted in a virtual machine).

I will give you some examples of how you can use hcsdiag.exe to interact with some of the Hyper-V containers. Now again, this focuses mostly on technologies like Windows Sandbox, Docker Hyper-V Containers, WSL 2, and similar features.

You can find more documentation on Hyper-V on Windows Server or Hyper-V on Windows 10 on Microsoft Docs.

List all containers and Hyper-V VMs

With the hcsdiag list command, you can create a list of containers and Hyper-V virtual machines running on the host. Including Windows Sandbox, Windows Subsystem for Linux 2, and Application Guard.

hcsdiag.exe list

Connect Console to Hyper-V containers and Windows Sandbox

You can also directly connect to the console of containers or the Windows Sandbox. Remember that it only works for Hyper-V containers where the guest is not protected from the host. Not for containers like Hyper-V VMs, where the guest is also protected from the host. If you need to remote into want console access or run commands against a Hyper-V VM from the host, check out PowerShell Direct for Windows VMs and hvc.exe for Linux VMs.

hcsdiag console connect

Here is an example where I am connected to a Windows Sandbox container using hcsdiag.exe.

hcsdiag Windows Sandbox

But that also works with Dockers container (Hyper-V containers) running Windows and Linux.

hcsdiag Linux Container

HCSDiag console provides you with an interactive connection to interact with the container.

Additional HCSDiag.exe features and commands

The HCSDiag.exe also provides you with a couple of additional commands you can use. For example, the read command to read a file from the container and output it to the host or as a file to the host.

hcsdiag read

You can use the “share” command to share a host folder into the container or use “vhd” to mount a virtual disk file (VHD) file to a container. The hcsdiag kill command terminates a running container.

Conclusion

HCSDiag.exe – Hyper-V Host Compute Service Diagnostics Tool is excellent if you need to troubleshoot these Hyper-V containers, virtual machines (VMs), Windows Sandbox, Windows Defender Application Guard, Windows Subsystem for Linux 2 and more. If you have any questions, feel free to leave a comment.