Managing Hyper-V From the Command Line (Part 3)

by [Published on 31 July 2012 / Last Updated on 31 July 2012]

This article continues the discussion of managing Hyper-V from the command line by demonstrating various methods for testing virtual machine health.

If you would like to read the other parts in this article series please go to:


In the previous article, I showed you how to start and stop virtual machines from the command line. In this article, I want to build on that by showing you two different methods for confirming that your virtual machines are running and that they are responsive.

Before I Begin

Before I get started, I want to quickly mention for the benefit of anyone who is just joining this series that the commands that I will be discussing are not native to Hyper-V. They are a part of a Hyper-V management library. Furthermore, this library must be imported into PowerShell each time that you plan on using any Hyper-V related commands. The import command is:

Import-Module “C:\Program Files\Modules\Hyperv\Hyperv.psd1”

The full instructions for downloading and installing the Hyper-V management library are provided in Part 1 of this series.

Troubleshooting Commands

Often times administrators rely on the PING command to test a host’s connectivity. The premise is simple. Ping the machine and see if it responds. Although the PING command works relatively well, there is a PowerShell command called Ping-VM which is specifically designed to ping virtual machines.

At first, the Ping-VM command seems redundant and its syntax is a bit more complicated than the regular PING command, but it does have its advantages. Before I explain what those advantages are, let me show you the basic syntax.

The Ping-VM command requires you to provide the name of the virtual machine that you want to ping and the name of the host server. For example, if I wanted to ping a VM named Lab-DC that was running on a host named Hyper-V then the command would be:

Ping-VM “Lab-DC” –Server Hyper-V

When this command is executed, the Ping-VM command uses the virtual machine’s integration services to discover the Fully Qualified Domain Name and then it performs a regular ICMP ping.

So why would you ever use Ping-VM rather than using PING? There are two reasons. First, Ping-VM is virtualization aware. Second, Ping-VM can be run against multiple virtual machines by using wildcards. To illustrate these concepts, take a look at Figure A. My host server has several virtual machines whose names are prefaced by “Lab-“. That being the case, I ran the command against Lab-*. Notice that I omitted the quotation marks when I did so. Ping-VM returned information on six virtual machines and was even able to determine which VMs were stopped.

Figure A: Ping-VM can be run against multiple virtual machines.

It is also possible to use Ping-VM to check the state of every virtual machine that resides on a host. To do so, just replace the virtual machine name with an asterisks. You could even take things a step further and display a warning message for any virtual machines that are running, but that cannot be pinged. The command for doing so is:

Get-VM –r | foreach-object {if ((Ping-VM $_).StatusCode –ne 0) {“$($_.elementname) is inaccessible”} }

This command does not produce any output if your virtual machines can be successfully pinged.

One last trick that I want to show you before I move on is that the Ping-VM command can be used to ping VMs on multiple Hyper-V hosts. To do so, simply provide the names of each host that you want to ping. The names should be separated by commas. For example, if I wanted to ping all of the virtual machines on Hyper-V1, Hyper-V2, and Hyper-V3 then the command that I would use is:

Ping-VM * -Server Hyper-V1,Hyper-V2,Hyper-V3

Testing Virtual Machine Heartbeats

Just as you can use the Ping-VM command to tell whether or not a virtual machine is responsive, you can also use the Test-VmHeartBeat command. Like Ping-VM, the Test-VmHeartBeat command depends on the Integration services being run on the virtual machine that you are testing.

The command’s syntax is relatively simple. You must specify the name of a virtual machine and a timeout period. The timeout period is expressed in seconds. The Test-VmHeartBeat command will look for a heartbeat once every five seconds until the timeout period expires. For example, if you wanted to test for a heartbeat for five minutes then you would set the timeout period to 300. To show you what I mean, take a look at Figure B. In this figure, I am looking for a heartbeat on a virtual machine named Lab-DC.

Figure B: The Test-VmHeartBeat command can be used to verify that a virtual machine is alive and responsive.

Like the Ping-VM command, you can use wildcards in place of virtual machine names and you can specify multiple host servers.

Since Ping-VM and Test-VmHeartBeat can both be used to verify a virtual machine’s responsiveness, you might be wondering which you should use.

If you want a quick status report from all your virtual machines (including those that are not running) then you are better off using Ping-VM. The reason is because Test-VmHeartBeat will stop and wait for the timeout period to expire for each virtual machine that is currently stopped. For example, suppose that your host server has ten virtual machines, but only five of them are running at the moment. Now imagine that you ran the following command:

Test-VmHeartBeat * -Timeout 300

The command would take a full twenty five minutes to complete because the Test-VM command would wait for a full five minutes while testing each of the stopped virtual machines. You can see an example of this in Figure C. In contrast, the Ping-VM command would provide the same basic status information, but would complete almost instantly.

Figure C: The Test-VMHeartBeat command can take a long time to complete if some virtual machines are not running.

Even so, the Test-VmHeartBeat command does have its place. This command is especially useful when virtual machines need to be started in sequence. For example, on my lab server my domain controller (Lab-DC) needs to be started before my Exchange Server (Lab-E2K10). It is actually possible to use the Test-VmHeartBeat command to verify that the domain controller is running prior to starting the Exchange Server. To start these two servers in sequence, I could use a command like this one:

Start-vm “Lab-DC” ; Test-VmHeartBeat “Lab-DC” –Timeout 300; Start-vm “Lab-E2K10”

If you look at Figure D you can see that PowerShell starts the domain controller and then stops and waits for the heartbeat to be confirmed (or for the timeout period to expire). Once the domain controller is up and running, the Exchange Server is started, as shown in Figure E. It would even be possible to append the Test-VmHeartBeat command to the end of this command string as a way of verifying that the Exchange Server is functional.

Figure D: PowerShell starts the domain controller and waits for a heartbeat.

Figure E: Once a heartbeat is detected, PowerShell launches the Exchange Server.


Now that I have shown you how to determine a virtual machine’s status from the command line, I want to continue the series by showing you some tricks for adjusting virtual machine memory allocations.

If you would like to read the other parts in this article series please go to:

See Also

The Author — Brien M. Posey

Brien M. Posey avatar

Brien Posey is an MCSE and has won the Microsoft MVP award for the last few years. Brien has written well over 4,000 technical articles and written or contributed material to 27 books.


Featured Links