Key remapping with keymapper

The keymapper daemon is a very neat utility that allows you to re-map any keys in your keyboard in all sorts of configurations.

It is similar to keyd (which I also recommend you check out if you use only Linux), but keymapper has the added benefit of working cross-platform in Linux, Windows and macOS, allowing you to share one configuration file across many systems. It also comes packed with several more features.

As keymapper isn't available in the official void repositories, it has to be built from source. I provide a package template in my void-templates repository to simplify the process; follow the usage instructions to install it, replacing <package-name> with keymapper.

Installation

1. To begin, build and install the keymapper package via void-templates.

2. Enable the system-wide service with:

   sudo ln -s /etc/sv/keymapperd /var/service

3. Write the following to ~/.config/keymapper.conf:

   # Holding [CapsLk], [W] [A] [S] [D] keys become [↑] [←] [↓] [→].
   [modifier="CapsLock"]
   W >> ArrowUp
   A >> ArrowLeft
   S >> ArrowDown
   D >> ArrowRight
   
   # Tapping [CapsLk] just generates [Esc].
   [default]
   CapsLock >> Escape

   The above is just example content. You can replace it with your own later.

4. You need to start the user-owned keymapper service yourself. If you followed Running user scripts after login, you can just append the following to your ~/.loginrc:

   # Start keymapper.
   (keymapper -u &>~/keymapper.log) &

Further configuration

You'll want to take a look at the keymapper repo, which is where all the documentation for keymapper resides.

Troubleshooting

Keymapper and PCI passthrough

If you followed my GPU passthrough in Void Linux, you may have run into an issue with keymapper intercepting input devices.

It is possible to keep keymapper running on the host and use its output as keyboard in the guest, but it requires a little bit of hacking.

1. Firstly, for this hack keymapper should only intercept one device (presumably your keyboard). You can ensure this is the case by adding the following directives to the top of your keymapper.conf:

   @skip-device-id /.*/
   @grab-device-id /<YOUR_DEVICE_NAME>/

   Replace <YOUR_DEVICE_NAME> as appropiate; you can figure it out by looking at /dev/input/by-id contents and cat'ing devices with keymapper disabled as explained in Creating the virtual machine. You don't need to write out the full name, just the identifying part is good enough.

2. You should be able to use sudo dmesg | grep "keymapper" to figure out what ID the keymapper output got assigned. Look for a message like:

   elogind-daemon[1028]: Watching system buttons on /dev/input/event20 (keymapper)

   In my case, /dev/input/event20 contains my keymapper output. If I set that as the dev of the keyboard in the VM config, I can use my keymapper-remapped keyboard in the VM without issue.

3. Because the virtual keymapper device may be assigned a different number in a future boot, it is best to determine it automatically on startup.

   Write the following to some file somewhere, for example keymapper-tmp-link.sh:

   #!/bin/bash
   
   while true; do
       device=$(dmesg | grep -m1 -o -E '/dev/input/event[0-9]+ \(keymapper\)')
   
       if [[ -z $device ]]; then
           sleep 1
           continue
       fi
   
       device=${device::-12}
       mkdir -p /tmp/dev/input && ln -s "$device" /tmp/dev/input/keymapper
       break
   done

   This creates /tmp/dev/input/keymapper as a symlink to the actual device, so your VM can point to that instead of to /dev/input/event<N>.

   Then to have it execute on boot, append the following to /etc/rc.local, adjusting the given path as necessary:

   (bash /path/to/keymapper-tmp-link.sh >/dev/null 2>&1) &

   If everything went well, /tmp/dev/input/keymapper should be created automatically everytime you start your computer.