How to forcefully disconnect a vSphere VM Console session?

The vSphere Virtual Machine Console UI is an extremely useful interface for interacting with a VM, especially for initial configurations and/or debugging and troubleshooting purposes, such as an issue with networking. The VM console is analogous to connecting a physical keyboard and monitor to a computer, you remember the good ol' days right? 😀

Unlike the physical world, where you can only have a single person interacting with the computer, the vSphere VM Console can allow multiple users to view and interact with the VM. It is also not uncommon for customers to limit the number of simultaneous VM Console sessions, especially for security and/or for privacy purposes.

One potential down side with limiting the VM Console session to one is that another user may not be able to connect until the other session has concluded and/or has expired due to lack of activity. This recently came up as a question from a customer asking if there was a way to forcefully disconnect an existing VM Console connection?

I was not aware of any practical methods but pinging one of our Engineers, I came to learn that we actually had introduced a new vSphere API that would assist in this very use case and was introduced back in vSphere 7.0 Update 1. The new vSphere API is called DropConnections(), which is very straight forward to use and can disconnect one or more existing VM Console connections. To list all active VM Console sessions, another new vSphere API was introduced called QueryConnections().

To demonstrate these two new vSphere APIs, I will be using PowerCLI to invoke the vSphere API using a VM in my environment called ph-clone.

(Get-VM -Name ph-clone).ExtensionData.QueryConnections()

As you can see from the command above, the QueryConnections() API is performed on a specific VM and the results is a set of connection(s) with three fields: Label, Client and UserName.

Note: The UserName for vSphere H5 Client VM Console will always show up as root and for any Standalone VMRC VM Console, the UserName will simply show up as VNC User, which can help distinguish the type of method used to connect to VM Console.

To disconnect a specific VM Console connection, we will need the three fields from above as they are all required to identify a specific VM Console session to perform the disconnect

The DropConnections() API can disconnect a list of active VM Console session and in the example below, we are simply disconnecting a single session.

$connection = New-Object VMware.Vim.VirtualMachineConnection
$connection.Label = "4"
$connection.Client = "192.168.30.3"
$connection.UserName = "root"

(Get-VM -Name ph-clone).ExtensionData.DropConnections(@($connection))

If the VM Console session disconnect was successful, you will get a result of True as shown in the screenshot below.

If you navigate to the existing VM Console session that you had been opened prior, you will see the following when it is remotely disconnected using this API.

If you are ever in a crunch and needing to disconnect an active VM Console, this is definitely a handy vSphere API to be aware of! If you are not running vSphere 7.0 Update 1, one other method that can be used to quickly disconnect VM Console session(s) is by performing a vMotion of the VM, this has been used by few customers in the past.

Note: Although Standalone VMRC VM Console connections are listed in QueryConnections() API and can be disconnected using DropConnections() API, the VMCR client has built-in session re-establishment, so you will see that a new session is spawn even when you attempt to disconnect an active session.