Update (21/03/2025)
German, UK (PC) and Italian layouts are supported in 8.0.4.
8.0.5 will have better support for CAPS lock and ctrl c and ctrl z
Update (19/02/2025)
We have implemented functionality in 8.0.3 to directly map Keysyms from Guacamole to VMware scancodes. The first keyboard layout to work with this functionality is Dutch Belgium. Testing is going well and we are planning to expand this to German, UK (PC) and Italian layouts soon.
Update (17/01/2025)
Morpheus is investigating a strategy to utilise scancodes directly to resolve keyboard map issues in VMware. If this proves successful Morpheus will maintain its own keyboard keymaps for mapping key symbols to scancodes in VMware when using the hypervisor console. These updates will begin to be tested in 8.0.2 and I will keep this post updated as this progresses.
Hello,
I am posting here to provide an explanation for why you may be experiencing keyboard mapping problems when attempting to use the Morpheus Hypervisor console on a VMware virtual machine.
Before reading further it is worth visiting this post for a background on keyboard layouts in Morpheus: Understanding Morpheus Console Keyboard Layouts + Why unexpected behaviour can occur
Summary:
Morpheus has received several reports of incorrect key mapping when using a non-US keyboard on the Morpheus Hypervisor console on Vmware.
When using the Hypervisor console, Morpheus will instruct Guacamole to open up a VNC connection to the virtual machine through VMware.
The problem stems in how VMware is configured to map keysyms (corresponds to the symbol on the key top) to scancodes (corresponds roughly to a physical key location)
If the VNC settings in VMware are configured with an incorrect keymap, or a slightly different keymap to what a user is expecting, the consequence can be an incorrect key mapping and unexpected behaviour.
Details:
Morpheus uses Guacamole (Requirements — Morpheus Docs documentation) for cloud agnostic Remote console SSH, RDP and VNC services
When using the Hypervisor console, Morpheus will instruct Guacamole to open up a VNC connection to the virtual machine through VMware.
Guacamole VNC is keyboard layout independent (VNC does not depend on keyboard layout and the Guacamole client is independent of keyboard layout) and will always send a keysym for keyboard input on a console. This is not the case for RDP sessions, as we will discuss later (Configuring Guacamole — Apache Guacamole Manual v1.5.5)
As Guacamole must use a VNC connection for the VMware hypervisor console, VMware must translate key events into scancodes based on its own internal keymaps. If that keymap does not actually match the layout selected within the guest OS, or you change the layout after the fact, the VMware keymap translation may fail, and strange behaviour may be experienced.
Example 1:
You press “A” on your local azerty keyboard. Guacamole reads this as an “A” keypress and sends it as such.
The Guacamole server receives your “A” keypress and sends it to the VNC server (VMware) as an “A” keypress.
Vmware receives the “A” keypress from Guacamole and needs to translate it into a scancode. It looks at the settings for the virtual machine, which is set either explicitly or by default to assume that the keyboard layout is English US. It sends the scancode for an “A” on a qwerty keyboard.
The guest OS is configured for azerty. When it receives the scancode from VMware, that scancode actually represents “Q”
The best way to alleviate this issue is to provide VMware with the correct keymap to use for a VNC connection. VMware ships with the following default keymaps: TechDocs. By ensuring that VMware is using the closest correct keymap, you can fix most, if not all, key mapping issues. VMware has a support article that describes how to configure the keymap in use for a virtual machine VNC connection: Specifying the keyboard layout when connecting with VNC client. You will notice that this list of supported languages is the same as what Morpheus uses for Hypervisor keyboard layouts: Screen Shot on 2023-04-04 at 14-20-31.png - Droplr. Morpheus allows you to configure the VMware hypervisor keymap by selecting the keyboard layout either on the cloud, virtual image or virtual machine host settings. If you have recently changed the selected keymap in Morpheus on the host settings, make sure to then open up a Hypervisor console connection to the virtual machine, next power-off and reboot the machine, and then reattempt the hypervisor console to test the changes.
Unfortunately this procedure does not correct all non-US keyboard problems. VMware has a very limited set of keymaps that can be used therefore there is a chance their provided layout does not exactly match the keyboard you are attempting to use. Here is another example:
Example 2:
You press ‘"’ on your local English UK (PC) keyboard. Guacamole reads this as an ‘"’ keypress and sends it as such.
The Guacamole server receives your ‘"’ keypress and sends it to the VNC server (Vmware) as an ‘"’ keypress.
Vmware receives the ‘"’ keypress from Guacamole and needs to translate it into a scancode. VMware is configured to use a English UK (MAC) keymap. It sends the scancode for an ‘"’ on a English UK MAC keyboard.
The guest OS is configured for English UK (PC). When it receives the scancode from VMware, that scancode actually represents “@”
How to workaround this issue:
Option 1) Choose the correct keymap to use for the VNC connection through Morpheus
Option 2) Choose to use an RDP/SSH (guest) connection instead. Guacamole has greater scancode support for the RDP protocol and can even do failsafe with Unicode keysym support. This enables Morpheus to enforce your local keyboard (Screen Shot on 2023-04-04 at 14-43-55.png - Droplr)
Option 3) Choose to use an RDP/SSH (guest) connection with a VDI gateway. If you have networking requirements that prevents use of RDP or SSH, you could instead deploy a Morpheus VDI (Morpheus Virtual Desktops — Morpheus Docs documentation) within the subnet where the VM resides, and configure Morpheus to use the VDI gateway for the console session. This will require 443 connectivity between your Morpheus appliance and the VDI gateway, however only the VDI gateway will require RDP/SSH access to the virtual machine.
Option 4) Change the keyboard layout of the guest virtual machine you are connecting to. If we take “Example 2” above, and change the guest console keyboard layout to English US, the scancode will correctly represent a ‘"’ key.
Option 5) Change the keymap file in VMware. VMware gives (fairly vague) instructions within their documentation on how to change how keysyms are mapped for VNC connections: Using VMware VMware Workstation Pro. It is possible that you can overwrite a supported language keymap (TechDocs) with the correct mapping you need for use-case, however please be aware that this is outside of Morpheus support including any future keymapping issues that arise from this.
Possible future option 6) Morpheus is exploring the option of allowing Option 3) to be extended without the 443 direct connect requirement. This will allow RDP and SSH console sessions to be handled by a VDI gateway within a subnet with the only requirement that the gateway can connect back to the Morpheus appliance over 443. This will give you the benefits of the better keyboard mapping support that the RDP and SSH protocols offer.
Why does the VMware web console or VMRC not exhibit this issue?
Whilst VMware is able to utilize their own proprietary extensions within their clients to alleviate this issue, Morpheus is not able to, and must be bound by the constraints of the VNC connection.
Additional documentation:
VMware VNC keyboard layout issue community thread 1: Home - Broadcom Community - VMTN - Discussion Forums, Technical Docs, Ideas and Blogs
VMware VNC keyboard layout issue community thread 2: Home - Broadcom Community - VMTN - Discussion Forums, Technical Docs, Ideas and Blogs
NDG notice on VNC keyboard layout issues: NDG NETLAB+ - Foreign Keyboard Mapping Issues with Virtual Machines
VMware knowledge article on VNC keyboard layout issue: Specifying the keyboard layout when connecting with VNC client
Configuring VNC keymap documentation: TechDocs