2.12, 2.13: Mention that kernel modules may need to be signed

Change-Id: I7fc20f1afb3e0de2ddaaa75b41753b5aab08ded4
Signed-off-by: Kienan Stewart <kstewart@efficios.com>
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

diff --git a/2.12/lttng-docs-2.12.txt b/2.12/lttng-docs-2.12.txt
index d35756d62ac4d7c64848c49fcc83fdf03dd39d0d..c3a937d05c85ccf62d9a7eaa952dddc0d993f850 100644 (file)
--- a/2.12/lttng-docs-2.12.txt
+++ b/2.12/lttng-docs-2.12.txt
@@ -1,7 +1,7 @@
 The LTTng Documentation
 =======================
 Philippe Proulx <pproulx@efficios.com>
-v2.12, 3 November 2023
+v2.12, 28 November 2023
 
 
 include::../common/copyright.txt[]
@@ -712,6 +712,45 @@ the installed files in a specific directory. This can be useful to test
 LTTng without installing it on your system.
 
 
+[[linux-kernel-sig]]
+=== Linux kernel module signature
+
+Linux kernel modules require trusted signatures in order to be loaded
+when any of the following is true:
+
+* The system boots with
+  https://uefi.org/specs/UEFI/2.10/32_Secure_Boot_and_Driver_Signing.html#secure-boot-and-driver-signing[Secure Boot]
+  enabled.
+
+* The Linux kernel which boots is configured with
+  `CONFIG_MODULE_SIG_FORCE`.
+
+* The Linux kernel boots with a command line containing
+  `module.sig_enforce=1`.
+
+.`root` user running <<lttng-sessiond,`lttng-sessiond`>> which fails to load a required <<lttng-modules,kernel module>> due to the signature enforcement policies.
+====
+[role="term"]
+----
+# lttng-sessiond
+Warning: No tracing group detected
+modprobe: ERROR: could not insert 'lttng_ring_buffer_client_discard': Key was rejected by service
+Error: Unable to load required module lttng-ring-buffer-client-discard
+Warning: No kernel tracer available
+----
+====
+
+There are several methods to enroll trusted keys for signing modules
+that are built from source. The precise details vary from one Linux
+version to another, and distributions may have their own mechanisms. For
+example, https://github.com/dell/dkms[DKMS] may autogenerate a key and
+sign modules, but the key isn't automatically enrolled.
+
+See
+https://www.kernel.org/doc/html/latest/admin-guide/module-signing.html[Kernel
+module signing facility] and the documentation of your distribution
+to learn more about signing Linux kernel modules.
+
 [[getting-started]]
 == Quick start
 
@@ -1923,8 +1962,9 @@ See <<proc-lttng-logger-abi,LTTng logger>>.
 Generally, you don't have to load the LTTng kernel modules manually
 (using man:modprobe(8), for example): a root <<lttng-sessiond,session
 daemon>> loads the necessary modules when starting. If you have extra
-probe modules, you can specify to load them to the session daemon on
-the command line.
+probe modules, you can specify to load them to the session daemon on the
+command line. See also
+<<linux-kernel-sig,Linux kernel module signature>>.
 
 The LTTng kernel modules are installed in
 +/usr/lib/modules/__release__/extra+ by default, where +__release__+ is

diff --git a/2.13/lttng-docs-2.13.txt b/2.13/lttng-docs-2.13.txt
index d69aaabe76957cd5bf36ba3ef3abbdb89c960a59..3349d481df92f99698607130910fb897b60ad348 100644 (file)
--- a/2.13/lttng-docs-2.13.txt
+++ b/2.13/lttng-docs-2.13.txt
@@ -1,7 +1,7 @@
 The LTTng Documentation
 =======================
 Philippe Proulx <pproulx@efficios.com>
-v2.13, 17 October 2023
+v2.13, 28 November 2023
 
 
 include::../common/copyright.txt[]
@@ -827,6 +827,44 @@ previous steps automatically for a given version of LTTng and confine
 the installed files to a specific directory. This can be useful to try
 LTTng without installing it on your system.
 
+[[linux-kernel-sig]]
+=== Linux kernel module signature
+
+Linux kernel modules require trusted signatures in order to be loaded
+when any of the following is true:
+
+* The system boots with
+  https://uefi.org/specs/UEFI/2.10/32_Secure_Boot_and_Driver_Signing.html#secure-boot-and-driver-signing[Secure Boot]
+  enabled.
+
+* The Linux kernel which boots is configured with
+  `CONFIG_MODULE_SIG_FORCE`.
+
+* The Linux kernel boots with a command line containing
+  `module.sig_enforce=1`.
+
+.`root` user running <<lttng-sessiond,`lttng-sessiond`>> which fails to load a required <<lttng-modules,kernel module>> due to the signature enforcement policies.
+====
+[role="term"]
+----
+# lttng-sessiond
+Warning: No tracing group detected
+modprobe: ERROR: could not insert 'lttng_ring_buffer_client_discard': Key was rejected by service
+Error: Unable to load required module lttng-ring-buffer-client-discard
+Warning: No kernel tracer available
+----
+====
+
+There are several methods to enroll trusted keys for signing modules
+that are built from source. The precise details vary from one Linux
+version to another, and distributions may have their own mechanisms. For
+example, https://github.com/dell/dkms[DKMS] may autogenerate a key and
+sign modules, but the key isn't automatically enrolled.
+
+See
+https://www.kernel.org/doc/html/latest/admin-guide/module-signing.html[Kernel
+module signing facility] and the documentation of your distribution
+to learn more about signing Linux kernel modules.
 
 [[getting-started]]
 == Quick start
@@ -2396,7 +2434,8 @@ Generally, you don't have to load the LTTng kernel modules manually
 (using man:modprobe(8), for example): a root session daemon loads the
 necessary modules when starting. If you have extra probe modules, you
 can specify to load them to the session daemon on the command line
-(see the opt:lttng-sessiond(8):--extra-kmod-probes option).
+(see the opt:lttng-sessiond(8):--extra-kmod-probes option). See also
+<<linux-kernel-sig,Linux kernel module signature>>.
 
 The LTTng kernel modules are installed in
 +/usr/lib/modules/__release__/extra+ by default, where +__release__+ is