[PATCH docs] sysadmin: add comment about update-initramfs needing to be run when changing the keyboard layout after installation due to KEYMAP=y in config for zfs-initramfs

[PATCH docs] sysadmin: add comment about update-initramfs needing to be run when changing the keyboard layout after installation due to KEYMAP=y in config for zfs-initramfs

[Michael Robert Jimenez]

Signed-off-by: Michael Robert Jimenez <m.jimenez@proxmox.com>
---
 keyboard-layout.adoc | 20 ++++++++++++++++++++
 sysadmin.adoc        |  4 ++++
 2 files changed, 24 insertions(+)
 create mode 100644 keyboard-layout.adoc

diff --git a/keyboard-layout.adoc b/keyboard-layout.adoc
new file mode 100644
index 0000000..4693753
--- /dev/null
+++ b/keyboard-layout.adoc
@@ -0,0 +1,20 @@
+[[chapter_keyboard_layout]]
+Keyboard Layout
+---------------
+ifdef::wiki[]
+:pve-toplevel:
+endif::wiki[]
+
+
+While the {pve} Installer initially configures the keyboard layout, it is possible to change it later by running:
+
+----
+# dpkg-reconfigure keyboard-configuration
+----
+
+
+You need to update the initramfs to persist the change after rebooting:
+
+----
+# update-initramfs -k all -u
+----
diff --git a/sysadmin.adoc b/sysadmin.adoc
index dd43f73..4d55835 100644
--- a/sysadmin.adoc
+++ b/sysadmin.adoc
@@ -52,6 +52,8 @@ See Also
 
 * link:/wiki/Kernel_Samepage_Merging_(KSM)[Kernel Samepage Merging (KSM)]
 
+* link:/wiki/Keyboard_Layout[Keyboard Layout]
+
 endif::wiki[]
 
 
@@ -85,6 +87,8 @@ include::system-booting.adoc[]
 
 include::kernel-samepage-merging.adoc[]
 
+include::keyboard-layout.adoc[]
+
 endif::wiki[]
 
 
-- 
2.47.3

Re: [PATCH docs] sysadmin: add comment about update-initramfs needing to be run when changing the keyboard layout after installation due to KEYMAP=y in config for zfs-initramfs

[Shannon Sterz]

hey, note that your commit message should not exceed 72 characters as
outlined in our developer documentation [1].

[1]: https://pve.proxmox.com/wiki/Developer_Documentation#Commits_and_Commit_Messages

in this case may i suggest something like this as the main commit
message:

> sysadmin: document running update-initramfs on keyboard layout change

and then a more elaborate explanation in the body (form stoiko's message
in chate):

> zfs-initramfs adds KEYMAP = y to the initramfs.conf
> (/usr/share/initramfs-tools/conf-hooks.d/zfs). this in turn causes
> /etc/console-setup to be included in the initramfs and this is not
> updated automatically when reconfiguring the keyboard-configuration.
> so initramfs needs to be update when changing the keyboard layout in
> these cases.

that should make it easier to glimpse what this commit is about while
preserving more information. thanks :)

On Tue Feb 17, 2026 at 4:20 PM CET, Michael Robert Jimenez wrote:
> Signed-off-by: Michael Robert Jimenez <m.jimenez@proxmox.com>
> ---
>  keyboard-layout.adoc | 20 ++++++++++++++++++++
>  sysadmin.adoc        |  4 ++++
>  2 files changed, 24 insertions(+)
>  create mode 100644 keyboard-layout.adoc
>
> diff --git a/keyboard-layout.adoc b/keyboard-layout.adoc
> new file mode 100644
> index 0000000..4693753
> --- /dev/null
> +++ b/keyboard-layout.adoc
> @@ -0,0 +1,20 @@
> +[[chapter_keyboard_layout]]
> +Keyboard Layout
> +---------------
> +ifdef::wiki[]
> +:pve-toplevel:
> +endif::wiki[]
> +
> +
> +While the {pve} Installer initially configures the keyboard layout, it is possible to change it later by running:

nit: the above line exceeds 80 characters which is the limit we try to
enforce for documentation here

> +
> +----
> +# dpkg-reconfigure keyboard-configuration
> +----
> +

nit: unnecessary empty line above.

> +
> +You need to update the initramfs to persist the change after rebooting:
> +
> +----
> +# update-initramfs -k all -u
> +----
> diff --git a/sysadmin.adoc b/sysadmin.adoc
> index dd43f73..4d55835 100644
> --- a/sysadmin.adoc
> +++ b/sysadmin.adoc
> @@ -52,6 +52,8 @@ See Also
>
>  * link:/wiki/Kernel_Samepage_Merging_(KSM)[Kernel Samepage Merging (KSM)]
>
> +* link:/wiki/Keyboard_Layout[Keyboard Layout]
> +
>  endif::wiki[]
>
>
> @@ -85,6 +87,8 @@ include::system-booting.adoc[]
>
>  include::kernel-samepage-merging.adoc[]
>
> +include::keyboard-layout.adoc[]
> +
>  endif::wiki[]
>
>