INSTALL-KEYMAP(8)

📦 version 0.7.92, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 INSTALL-KEYMAP 💖

okay so bestie, welcome to install-keymap — it's a little system manager's manual situation from section 8, and it's literally the glow-up your boot-time keyboard needs. let's get into it ✨

🌸 NAME 🌸

install-keymap — expand a given keymap and install it as boot-time keymap

like. it takes your keymap, un-nests it, and makes it The One your kernel wakes up with. periodt. 💅

🎀 SYNOPSIS 🎀

install-keymap [keymap-name | NONE | KERNEL]

three moods, pick one 🫶

🦋 DESCRIPTION 🦋

so normally install-keymap takes a keymap-name as its argument. that file gets passed to loadkeys for loading, which means the valid values for this argument are the exact same ones you'd hand to loadkeys. no cap.

then install-keymap expands all the include-like statements inside that file, and drops the result into /etc/console/boottime.kmap.gz, which gets loaded into the kernel at boot-time. iconic behaviour honestly. 🌈

you can also hand it KERNEL instead of a keymap name. that causes /etc/console/boottime.kmap.gz to be removed, making sure that no custom keymap will replace the kernel's builtin keymap at next reboot. bye bestie 👋

and then there's NONE, which tells the command to do absolutely nothing. sounds useless but it's actually so smart — caller scripts use it to avoid handling this special case and needlessly duplicating code. not me writing the same if-block in six places 😭 no thank u.

💜 the whole reason this exists (the lore) 💜

the purpose of all this processing is to solve one annoying problem made of 2 apparently conflicting issues. yes, two. both real. let's go.

issue one: an important goal of keymap management in Debian is making sure that whenever the user or admin is expected to use the keyboard, the keymap selected as boot-time keymap is actually in use. which means the keymap has to be loaded before a shell is ever proposed — so, very early in the booting process, and especially before all local filesystems are mounted (/etc/rcS.d/S10checkroot.sh can spawn sulogin, iykyk). early early. like, first-thing early. ⏰

issue two: for flexibility we allow that /usr or /usr/share may live on their own partition(s), and thus /usr/share/keymaps, where keymap files live, may not be available for reading at the time we need a keymap file. and no, we won't put 1Mb of keymaps in the root partition just for this. we are not doing that. absolutely not. 💀

so here's the problem: most keymap files are not self-contained, so it does not help to just copy the selected file into the root partition. it would be a broken little orphan. 🙈

the best known solution so far is to expand the keymap file so that it becomes self-contained, and put it in the root partition. that's what this tool does. main character energy only. 👑

✨ FILES ✨

  • /etc/console/boottime.kmap.gz — Where the boot-time keymap is stored

that's the sacred little file. protect it. 🥺

🌟 SEE ALSO 🌟

  • loadkeys (8).

go say hi, they're literally the ones doing the loading. 💖

👑 AUTHOR 👑

This program and manual page were written by Yann Dirson dirson@debian.org for the Debian GNU/Linux system, but as it should not include any Debian-specific code, it may be used by others.

shoutout Yann, ate and left no crumbs 🍓

and that's the whole page bestie!! this was INSTALL-KEYMAP(8) from the System Manager's Manual — mwah, slay, go install a keymap 💅✨

📦 where this page comes from