Bernhard's Homepage

GNS3 - Using VNC with international keyboards

GNS3 - Using VNC with international keyboards

As a user of keyboards with German layout I noticed, that using VNC with international layouts can lead to weird key bindings. This can make it almost impossible to use some VMs.

In the following I will look at three different cases and see how to achieve the best results.

JollysFastVNC (macOS) connecting to QEMU VMs

At first the keyboard bindings are looking quite good, z is on the right place and most special characters are working as well. But some special characters like /, =, + are giving wrong results and creating special characters by using the Option (Alt) key doesn't work at all. This is clearly not acceptable.

But how does this happen?

VNC sends the keystroke as character and/or keycode to the VM. JollysFastVNC seems to prefer sending the (ASCII) character code over sending the keycode. QEMU needs to convert this character code to a keycode, then forwards it to the VM's OS, which converts it back to a character.

Here an example, how this is giving wrong results:

When I want to send a / I'm typing Shift-5 on my German keyboard. JollysFastVNC will send a "Shift" keycode plus a / to QEMU, which translates the / according to an US keymap to the key just left to the right shift key. So the OS in a VM gets the keycode for "Shift" then the key next to the right shift key. It translates this key sequence according it's US keymap to ?.

For all characters, where the shift state on your keyboard is the same as on an US keyboard, this procedure works. But for all other keys this results in wrong characters. Furthermore all special sequences using AltGR or Option will only work, if the VM's OS can interpret it. With the default US keyboard setting this is not the case.

How to fix it?

First we need to help QEMU to generate the correct keycodes. For that we need to tell QEMU which layout our keyboard has. That is done by adding "-k <language>" to the advanced options of the QEMU VM. The language codes are documented in the QEMU documentation, for me "-k de" is the right setting.

QEMU settings language

Now QEMU will send the correct keycodes to the VM, but the VM's OS will interpret them by default according to the US layout. That's actually worse than before. But when we use the keyboard settings within the VM and configure the correct layout, we will get a perfect setup. In my case I choose a "German (Macintosh, no dead keys)" layout. Now I can use my keyboard (almost) the same way as on the mac, only I have to use the right option key for creating special characters.

remote-viewer (Linux) connecting to QEMU VMs

remote-viewer is part of the virt-viewer package, it supports both the VNC and SPICE protocol. In both cases it sends the keycodes to the VM, not the characters. This results in an US keyboard layout. After configuring the right layout in the keyboard settings within the VM, the keyboard is behaving correctly.

VNC to Docker VM

Interestingly both JollysFastVNC on macOS and remote-viewer on Linux work just fine with Docker VMs, at least with the web_java appliance. I don't have to change any language settings, the keyboard layout is correct right from the beginning. Only on JollysFastVNC I had to initially change to local interpretation to enable special character with the Option (Alt) key. The local/remote interpretation can be toggled by using the right Command (Apple) key.