Using FreeRDP to connect to the Hyper-V console

Accessing Microsoft’s Hyper-V console is typically performed by running Hyper-V Manager / vmconnect on a Windows Server host or Windows 7 / 8 equipped with RSAT.

There are unfortunately quite a few limitations in this approach, including the fact that is not available on the Hyper-V host itself or on other operating systems.

Hyper-V console access is based on an extension of the RDP protocol, which is implemented in the Remote Desktop Services ActiveX Client control (mstscax.dll) used by vmconnect and by the RDP client itself (mstsc.exe).

Enter FreeRDP

Microsoft opened up their RDP protocol, including the extensions required by Hyper-V, which led to having FreeRDP implementing it. FreeRDP is without any doubt one of the most promising open source projects in terms of interoperability with the Microsoft world with a great developers team behind it.

The great news is that it’s now possible to access a Hyper-V console from Windows, Linux and Mac OS X. Here’s how. I’m going to present a “hard”, way using directly FreeRDP and a easier way using a Powershell script to get the required details from HyperV.

Support for Hyper-V is not yet available in the latest FreeRDP release, so all you need to do is to download the latest sources and compile them. To spare you some work here are the precompiled binaries for Windows. As a prerequisite you need to install the Visual C++ 2012 x86 runtime.

Connecting with FreeRDP

First you need to get the Id of the VM to which you want to connect. This can be done in Powershell on Windows Server / Hyper-V Server 2012 or Windows 8 with:

Get-VM <vmname> | Select-Object Id

On Windows Server / Hyper-V Server 2008 and 2008 R2 you can use PSHyperV as the Cmdlets introduced with the new Hyper-V version are not available.

To connect from Linux or Mac OS X:

xfreerdp –ignore-certificate –no-nego -u <username> –pcb <vmid> -t 2179  <hypervhost>

On Windows you can use the same command line but authentication is handled by the OS. In particular, in order to connect to a different host not in the same domain or without passthrough authentication you can use cmdkey.

wfreerdp –ignore-certificate –no-nego  –pcb <vmid> -t 2179  <hypervhost>

If you need to authenticate on the server, before wfreerdp run:

cmdkey /add:<hypervhost> /user:<username> /pass

A Powershell Cmdlet to ease up things.

The process described above, involving getting the VM Id before running FreeRDP might become a bit annoying if you need to do it frequently. Here’s also a Powershell Cmdlet that I wrote to simplify your work.

Some examples.

First you need to enable the execution of Powershell scripts on the host if you didn’t do it before:

Set-ExecutionPolicy RemoteSigned

Now you can import the module:

Import-Module .\PSFreeRDP.ps1

Now, to access the console on the “instance-00000001” virtual machine on the local Hyper-V host:

Get-VMConsole instance-00000001

To access the console of a VM on a remote server:

Get-VMConsole instance-00000001 -HyperVHost RemoteServer

To access the console on all the running instances (be careful! 🙂 ):

Get-VM | where {$_.State -eq “Running”} | Get-VMConsole

As you can see some Powershell magic can ease up a lot of work!

Update: Now with Windows Server / Hyper-V Server 2012 R2 support.

Download FreeRDP for Windows and Powershell Cmdlet

We love FreeRDP to the point that we bundled it with our OpenStack installer. This way the entire Hyper-V compute management can be done in a completely autonomous way.