FreeBSD Console Keymap and Localization Operations: Test Before Rebooting

FreeBSD console localization includes several layers that are easy to conflate: the keyboard layout maps physical key events to characters, the terminal type describes control and character behavior, fonts determine which glyphs can be displayed, and the user process locale affects text encoding and language conventions. Changing one layer does not automatically configure the others.

This runbook focuses on the system virtual console. The kbdmap utility operates on a virtual console, not X11 or a desktop session. Desktop environments have their own keyboard and input-method configuration. Before changing the console, identify whether the machine uses vt(4) or syscons(4), preserve a known-working administrative path, and test from a spare virtual terminal when possible.

Identify the console driver and current settings

Capture the system version, active virtual-terminal state, and relevant rc.conf values:

freebsd-version -kru
sysctl kern.vty
sysrc -n keymap
sysrc -n keyrate
sysrc -n keychange
sysrc -n font8x16
sysrc -n scrnmap
tty

An unset sysrc value is not the same as an explicit configured value. Save the output and inspect the active console driver. When both syscons and vt are available, kern.vty selects the one used as the system console; the GENERIC kernel uses vt when the setting is absent. The two drivers differ in supported font and screen-map controls.

Do not assume that a shell opened in a terminal emulator is using the host’s physical or virtual console. A terminal emulator has its own key translation and font rendering. Confirm you are on the console before running kbdmap or vidfont.

Test candidate keymaps interactively

List the keymaps available on the installed system:

kbdmap -p

Run kbdmap from a virtual console to select and test a candidate. The Handbook notes that keymaps can be tested without rebooting. Before accepting one, test alphabetic keys, digits, punctuation, modifier keys, function keys, symbols used in passwords, and the key sequence required to switch virtual terminals. A visually plausible layout may place punctuation in unexpected positions.

Do not close your only administrative session while testing. Keep a second console, serial path, or out-of-band management session available. Record the exact selected keymap base name and test date. On a remote system whose only access depends on a console keyboard, coordinate an operator who can observe or recover the physical console.

If a key is mapped correctly in kbdmap but not in a desktop, that is expected: the console and graphical input stacks are separate. Configure the desktop input method through its own platform tools. Conversely, a correct X11 layout does not prove that the loader and virtual console use the same mapping.

Persist the keyboard layout carefully

The Handbook documents the rc.conf keymap setting. The value is the keymap name without the .kbd suffix:

sysrc keymap="selected-keymap"
sysrc keyrate="normal"

Replace selected-keymap with the exact name reported by the installed keymap list. The keyrate setting is optional; use one of the documented values such as slow, normal, or fast only when repeat behavior is part of the requirement. Do not add unrelated changes to rc.conf during the test.

For function-key escape sequences, the keychange setting may be required so the programmed keys match the selected terminal type. The sequence is separate from the keymap file. Validate the terminal application’s behavior for function keys after changing it rather than assuming that keyboard characters and terminal escape sequences are controlled by the same option.

To roll back an explicit keymap override, restore the previous value or remove it if the variable was originally unset:

sysrc -x keymap

Use this only when removing the intended override; preserve configuration-management ownership and confirm the current rc.conf contains no separately managed value. A reboot is not required to test the keymap interactively, but a controlled restart is necessary to prove that the persistent boot configuration applies as expected.

Match terminal type to the character repertoire

The console terminal type in /etc/ttys affects how applications encode and interpret terminal behavior. FreeBSD’s Handbook lists terminal types such as cons25, cons25l1, cons25l2, cons25l7, cons25r, and cons25u for specified character sets. Use the mapping documented for the installed release and the actual repertoire required; do not set a terminal type by guessing from a locale string.

The vt console supports UTF-8 text and double-width characters according to vt(4), but complex writing systems may need a dedicated console solution from ports. A locale setting such as LANG influences applications, not the console keyboard map. Check locale output inside the target user’s login session separately from what the physical console displays.

Do not change every /etc/ttys entry in one edit without understanding which terminals are active. Preserve the original file and modify only the intended virtual-terminal entries. Test a new login after any terminal-type change because services such as getty and login may need a new session to use the updated definition.

If typed characters appear as question marks, replacement glyphs, or mojibake, isolate input, terminal type, locale, and font separately. A glyph missing from the selected font can appear wrong even though the stored character is correct. A terminal type mismatch can corrupt display behavior even if the input is correct. Capture bytes or use an application known to report code points if the distinction matters.

Configure fonts with the active driver in mind

The rc.conf font variables can choose font files for the console driver’s supported screen sizes. The relevant paths differ between syscons and vt. For vt, the kern.vty and screen.font loader setting refer to font files under /boot/fonts and the installed font index. Verify the named font is present and listed before making it persistent.

For example, vt supports a boot loader setting such as:

screen.font="8x16"

This is only an example; confirm that the font exists in /boot/fonts and is listed in its INDEX.fonts file. The syscons driver uses its own font paths and vidcontrol behavior. Do not assume that a screen-map option documented for syscons also applies to vt; rc.conf(5) specifically notes that scrnmap is ignored when vt is the console driver.

Use kbdmap or vidfont only from a virtual console. The manual documents that these utilities do not configure X11. If a console font change makes output unreadable, revert using a second console or known-good boot loader access rather than repeatedly trying random font names.

Diagnose keyboard and display symptoms separately

If a key produces the wrong character, check the physical layout, active keymap, modifier behavior, terminal application, and input method. If a key produces no character, test whether it is a function key, special control key, or unsupported hardware event rather than changing the character set. If the issue appears only after boot, compare the runtime kbdmap selection with the persistent rc.conf value and startup logs.

If a correct character is stored but rendered incorrectly, check the terminal type, console driver, font coverage, and locale. Test both ASCII and representative non-ASCII characters in a simple console program before changing system-wide settings. Preserve output from a separate UTF-8 capable client when working over SSH so remote terminal rendering is not mistaken for the FreeBSD console.

If function keys send unexpected sequences, verify keychange, terminfo, and the application. Changing the keymap alone may not update function-key string definitions. Test with a simple terminal application and compare the actual sequence to the terminal description.

Operational acceptance and rollback

Acceptance means the intended user can type all required characters at the physical or virtual console, see them rendered correctly, use expected terminal keys, and log in after a controlled reboot. Test the recovery console and a fresh login, not only the interactive menu. Keep the test account and administrator credentials usable under the selected layout.

Record the active driver, FreeBSD release, keymap file, rc.conf values, terminal type, font, locale, test characters, and rollback procedure. If the change fails, restore only the values changed, remove an accidental override if needed, and verify the previous console behavior before closing the change.

Related:

Sources: