The LTTng Documentation
=======================
Philippe Proulx <pproulx@efficios.com>
-v2.13, 17 October 2023
+v2.13, 28 November 2023
include::../common/copyright.txt[]
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
kernel events>> and <<tracing-your-own-user-application,Record user
application events>> tutorials, you can inspect the recorded events.
-There are many tools you can use to read LTTng traces:
+There are tools you can use to read LTTng traces:
https://babeltrace.org/[Babeltrace{nbsp}2]::
A rich, flexible trace manipulation toolkit which includes
A graphical user interface for viewing and analyzing any type of
logs or traces, including those of LTTng.
-https://github.com/lttng/lttng-analyses[LTTng analyses]::
- An experimental project which includes many high-level analyses of
- LTTng kernel traces, like scheduling statistics, interrupt
- frequency distribution, top CPU usage, and more.
-
NOTE: This section assumes that LTTng wrote the traces it recorded
during the previous tutorials to their default location, in the
dir:{$LTTNG_HOME/lttng-traces} directory. The env:LTTNG_HOME
(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
An analysis can use the state dump event records to set an initial state
before it builds the rest of the state from the subsequent event
-records. http://tracecompass.org/[Trace Compass] and
-https://github.com/lttng/lttng-analyses[LTTng analyses] are notable
-examples of applications which use the state dump of an LTTng trace.
+records. http://tracecompass.org/[Trace Compass] is a notable
+example of an application which uses the state dump of an LTTng trace.
When you <<taking-a-snapshot,take a snapshot>>, it's possible that the
state dump event records aren't included in the snapshot trace files
reboot, without flushing to typical _storage_.
Linux supports NVRAM file systems thanks to either
-http://pramfs.sourceforge.net/[PRAMFS] or
https://www.kernel.org/doc/Documentation/filesystems/dax.txt[DAX]{nbsp}+{nbsp}http://lkml.iu.edu/hypermail/linux/kernel/1504.1/03463.html[pmem]
-(requires Linux{nbsp}4.1+).
+(requires Linux{nbsp}4.1+) or http://pramfs.sourceforge.net/[PRAMFS] (requires Linux{nbsp}<{nbsp}4).
This section doesn't describe how to operate such file systems; we
assume that you have a working persistent memory file system.
project which you can use to send and receive control messages to and
from a <<def-session-daemon,session daemon>>.
-LTTng analyses::
- The https://github.com/lttng/lttng-analyses[LTTng analyses] project,
- which is a set of analyzing programs that you can use to obtain a
- higher level view of an <<def-lttng,LTTng>> <<def-trace,trace>>.
-
cmd:lttng-consumerd::
The name of the <<def-consumer-daemon,consumer daemon>> program.