Configure locale, keyboard, and time zone

Synopsis #

Locale, keyboard layout, time zone, and clock synchronization are independent settings. A locale controls how applications interpret and present language-sensitive data. A console keymap controls keys on FreeBSD virtual consoles. Xorg and Wayland sessions have their own input configuration. A time zone changes civil-time display, while a time-synchronization service corrects the system clock.

Test each layer temporarily, record the original value, and make only the confirmed setting persistent. This avoids a login environment that cannot start, an unusable console keymap, or a clock that appears wrong for two different reasons.

Inventory the current state #

Collect the current application locale, console keymap setting, time-zone record, and clock state:

$ locale
$ sysrc keymap
$ test -r /var/db/zoneinfo && cat /var/db/zoneinfo
$ date
# service ntpd status

An unset keymap rc variable means that the base default can still be active. A stopped ntpd service does not prove the clock is wrong, because another synchronization mechanism may exist. Record the installed desktop or compositor before changing graphical input.

Select and test a locale #

List locale names supplied by the installed base system and choose an exact entry:

$ locale -a

Test that entry in a child process before changing login files. Replace locale-name with the exact reported value:

$ env LANG=locale-name locale

LANG supplies defaults for locale categories. A specific LC_CTYPE, LC_TIME, or another LC_* variable overrides its category. LC_ALL overrides every category and is best reserved for a deliberate temporary test; setting it globally makes category-specific configuration difficult to understand.

Check application behavior that matters, including character input, filename display, sorting, decimal formatting, and date formatting. Changing a locale does not translate an application that lacks message catalogs or add missing fonts and input methods.

Make a per-account locale persistent #

FreeBSD login classes provide a shell-independent per-account mechanism. A minimal UTF-8 example in ~/.login_conf is:

me:\
    :charset=UTF-8:\
    :lang=en_US.UTF-8:

Replace both values when a different entry from locale -a and its documented character set are required. Compile the per-account capability database:

$ cap_mkdb "$HOME/.login_conf"

Log out completely and start a new login session before evaluating the result. Existing shells and applications retain their previous environment.

For a system-wide policy, define a named class in /etc/login.conf, run cap_mkdb /etc/login.conf, and assign that class to accounts with the documented account-management tools. Do not alter the default class for every account merely to fix one desktop application. Keep a root or administrative session open while validating a new login class.

To roll back a per-account change when ~/.login_conf existed previously, restore the recorded file, run cap_mkdb again, and begin a fresh login. If the file was newly created, remove both ~/.login_conf and ~/.login_conf.db, then begin a fresh login. A stale compiled database can otherwise keep the removed settings active. Shell startup files can also set locale variables, but their syntax and coverage differ; avoid configuring the same variable in both mechanisms.

Test and retain a console keymap #

kbdmap(1) applies to a FreeBSD virtual console, not to Xorg or native Wayland applications. Run it from a local virtual console with another administrative session available:

# kbdmap

Select a candidate interactively and test letters, digits, punctuation, modifiers, function keys, and any key needed for the root password. The change is temporary and can be replaced by another selection or reset during the test.

After recording the selected keymap name, make that exact name persistent with sysrc:

# sysrc keymap="selected-keymap"

Do not include a filename suffix unless the installed rc.conf(5) and keymap data require it. Verify at a new virtual console and again after reboot. To roll back, restore the recorded value; if the variable was originally absent, remove the override:

# sysrc -x keymap

Console fonts and screen maps are separate from the keymap. Change them only when the selected character repertoire needs them and the active console driver supports the documented setting.

Configure Xorg input separately #

An Xorg session uses XKB configuration. Inspect the active session rather than inferring its layout from the console:

$ setxkbmap -query

If setxkbmap is installed, a temporary layout change can validate an XKB layout and variant for that Xorg session. Persistence belongs in the desktop environment, display manager, or a narrow Xorg input configuration, not in the console keymap variable.

Keep Xorg input snippets limited to the keyboard match and the verified XkbLayout, XkbVariant, and XkbOptions values. A catch-all input rule can alter keyboards, accessibility devices, remote sessions, or hot-plugged hardware unexpectedly. The Xorg or Wayland guide establishes which session stack is active.

Configure Wayland input through the compositor #

Native Wayland clients receive keyboard configuration from the compositor. setxkbmap changes Xorg and can affect Xwayland, but it is not a general native-Wayland configuration tool.

Use the installed compositor’s current FreeBSD package documentation and configuration syntax for layout, variant, and compose options. Test the compositor’s reload or a separate session before replacing a working login configuration. Desktop-environment settings can override or regenerate compositor configuration, so keep one owner for the persistent layout.

Input methods for languages that need composition or candidate selection are another layer. Select a packaged input method that supports the session protocol and application toolkit, then test it in both native and compatibility applications. A locale alone does not start an input-method daemon.

Set the system time zone #

tzsetup(8) installs the selected zone as the system default and records it for later base-system updates. Use a name found under /usr/share/zoneinfo. A no-write check validates the proposed zone without changing files:

# tzsetup -n Region/City

After verifying the region and city, apply the same explicit zone:

# tzsetup Region/City
$ date

Record the prior /var/db/zoneinfo value so the same command can restore it. Do not replace /etc/localtime by hand when tzsetup can maintain both the zone file and update record.

Changing the system time zone affects the default display of civil time; it does not change the underlying instant. Individual processes can use a TZ environment variable and some applications maintain an independent preferred zone. Verify cron jobs, databases, logs, and calendaring applications separately when their interpretation of local time matters.

Separate time zone from clock correction #

If the displayed hour is offset by a whole number of hours but minutes and seconds are correct, inspect the zone first. If the clock drifts or the underlying instant is wrong, inspect the configured synchronization service and upstream reachability.

FreeBSD’s base ntpd can be enabled through rc.conf when Network Time Protocol is the selected design:

# sysrc ntpd_enable=YES
# service ntpd start
# service ntpd status

Do not run multiple time-synchronization daemons against the same clock. Stepping a badly wrong production clock can affect logs, certificates, databases, and scheduled work, so follow ntpd(8) policy and application requirements before forcing a correction.

The hardware clock’s UTC-versus-local-time policy is separate again. tzsetup can account for systems whose hardware clock is not UTC, but changing that policy can break dual-boot expectations. Record whether /etc/wall_cmos_clock exists and consult adjkerntz(8) before changing it.

Verify a complete session #

After the next login and controlled reboot, verify:

locale reports only intended category overrides;
console input works before any graphical session starts;
the Xorg or Wayland layout works in native applications and compatibility applications;
date reports the intended zone and civil time;
one time-synchronization service owns clock correction;
scheduled tasks and logs retain the intended time semantics.

The maintainable desktop baseline provides the wider package, display, and service boundary for a graphical installation.