Skip to content

Hyper-V VM Console

Open the console of a virtual machine on a Microsoft Hyper-V host from the portal, without connecting to the host with Hyper-V Manager or RDP.

The console attaches to the VM's video device, so it works for any guest operating system and before one is installed. Use it to watch a Hyper-V VM PXE boot, reach a bootenv shell, or look at a guest whose network is down.

Overview

DRP opens an RDP connection to the Hyper-V host on port 2179 and names the VM by its GUID, the same way Hyper-V Manager's "Connect" does. Two things follow:

  • The credentials are for the Hyper-V host, not the guest operating system.
  • The host keeps a per-VM access list that must name the connecting account.

Prerequisites

Endpoint

The guacd-service resource broker must exist. The bootstrap-guacd task creates it. Without it the portal hides the Remote button.

Bash
drpcli resource_brokers exists Name:guacd-service && echo "broker present"

Machine parameters

Set these on the DRP machine that represents the VM:

Parameter Required Description
hyper-v/uuid yes The VM's Hyper-V VM Id (a GUID). Identifies the VM to the host.
hyper-v/console-host yes Address of the Hyper-V host. Not the VM's own address.
hyper-v/console-username yes An account on the Hyper-V host.
hyper-v/console-password yes Password for that account. Defined as a secure parameter, so DRP stores it encrypted.
hyper-v/console-domain no Windows domain, if the host is domain-joined.

Keep the credentials in a profile so one place serves every VM on that host.

Hyper-V host

  • TCP port 2179 must be reachable from the DRP endpoint. The built-in Hyper-V (REMOTE_DESKTOP_TCP_IN) firewall rule allows it.
  • The account in hyper-v/console-username must be granted console access to each VM (see step 4 below).

Architecture

Text Only
1. User's browser
2. RackN Portal UX
3. API call on 8092, upgraded to a websocket
4. DRP endpoint
5. localhost:4822/tcp
6. guacd service container
7. RDP to hyper-v/console-host:2179, VM GUID sent as an RDP preconnection blob
8. Hyper-V host attaches the session to the VM's video device

The browser sends only the console type, the machine id and its auth token. The endpoint resolves the host address, username and password and injects them into guacd, so they never reach the browser. See Guacamole Tunnel for the tunnel.

Procedure

1. Get the VM's GUID

On the Hyper-V host:

PowerShell
Get-VM -Name <vm-name> | Select-Object Name, Id

The Id column is the value for hyper-v/uuid.

2. Create a profile with the host credentials

Bash
drpcli profiles create '{
  "Name": "hyperv-console",
  "Description": "Console credentials for the Hyper-V host",
  "Params": {
    "hyper-v/console-host": "<hyper-v-host-address>",
    "hyper-v/console-username": "<host-account>"
  }
}'

Set the password separately so it is stored encrypted and stays out of shell history:

Bash
drpcli profiles set hyperv-console param hyper-v/console-password to -

It should read back as an encrypted Key/Nonce/Payload object:

Bash
drpcli profiles show hyperv-console | jq '.Params."hyper-v/console-password"'

3. Apply the profile and the VM GUID to the machine

Bash
drpcli machines addprofile <machine-uuid> hyperv-console
drpcli machines set <machine-uuid> param hyper-v/uuid to "<vm-guid>"

4. Grant the account console access to the VM

Hyper-V keeps its own access list for VM consoles. Run this on the host once per VM:

PowerShell
Grant-VMConnectAccess -VMName <vm-name> -UserName "<HOSTNAME>\<host-account>"

Verify:

PowerShell
Get-VMConnectAccess -VMName <vm-name>

An empty result means no account may open that VM's console. Connections then fail in a way that looks like a credential problem. See Troubleshooting.

5. Open the console

In the portal, open the machine and choose Remote → Hyper-V Console.

Validation

Ask the endpoint what consoles it can offer for the machine:

Bash
drpcli machines runaction <machine-uuid> console-info --plugin hyper-v

A correctly configured VM returns:

JSON
{
  "consoles": [
    {
      "type": "hyperv",
      "available": true,
      "transport": "rdp",
      "host": "<hyper-v-host-address>",
      "port": 2179,
      "params": {
        "preconnection-blob": "<vm-guid>",
        "security": "vmconnect",
        "ignore-cert": "true"
      }
    }
  ]
}

If available is false, reason says what is missing. The portal disables the item and shows the same reason as a tooltip.

Troubleshooting

Console closes immediately with Connection Closed

The usual cause is that the account has not been granted access to that VM. The host accepts the login and then drops the session, so there is no failed-logon event to find.

Confirm on the Hyper-V host:

PowerShell
Get-VMConnectAccess -VMName <vm-name>

If the result is empty, or does not list the account in hyper-v/console-username, grant it as shown in step 4 and reconnect.

In the guacd container log a rejected session shows the correct connection mode followed by a forcible disconnect:

Text Only
Security mode: Hyper-V / VMConnect
RDP server closed/refused connection: Forcibly disconnected.

The first line confirms hyper-v/uuid and the connection parameters were right, which leaves host-side authorization.

The Hyper-V Console item is missing from the dropdown

hyper-v/uuid is not set on the machine. The portal offers the Hyper-V console only when that parameter is present.

Bash
drpcli machines get <machine-uuid> param hyper-v/uuid --aggregate

Parameters read back as null even though a profile sets them

drpcli machines get <uuid> param <name> reads only parameters set directly on the machine. Add --aggregate to see values inherited from profiles:

Bash
drpcli machines get <machine-uuid> param hyper-v/console-host --aggregate

Authentication is rejected

The username and password must authenticate to the Hyper-V host, not the guest operating system. A guest credential always fails.

The Remote button is not shown at all

The endpoint has no guacd-service resource broker. Run the bootstrap-guacd task.

References