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>
 The LTTng Documentation
 =======================
 Philippe Proulx <pproulx@efficios.com>

-v2.12, 3 November 2023
+v2.12, 28 November 2023

 
 
 include::../common/copyright.txt[]
 
 
 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.
 
 
 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
 
 [[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
 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
 
 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>
 The LTTng Documentation
 =======================
 Philippe Proulx <pproulx@efficios.com>

-v2.13, 17 October 2023
+v2.13, 28 November 2023

 
 
 include::../common/copyright.txt[]
 
 
 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.
 
 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
 
 [[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
 (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
 
 The LTTng kernel modules are installed in
 +/usr/lib/modules/__release__/extra+ by default, where +__release__+ is