doc: LSM: update usage document for current LSM stacking
Subsystems (2)
cover doc: LSM: update usage document for current LSM stacking
The LSM usage document (Documentation/admin-guide/LSM/index.rst) has not kept up with the LSM stacking infrastructure. It still describes CONFIG_DEFAULT_SECURITY, which no longer exists, and its description of the module ordering in /sys/kernel/security/lsm does not match what the framework actually does.
Patch 1 updates the selection mechanism description to CONFIG_LSM and the "lsm=" parameter, keeping "security=" documented as the deprecated legacy option. This revisits an earlier attempt by Randy Dunlap [1] that was rejected for treating the two parameters as equivalent; the new text keeps them distinct.
Patch 2 fixes the ordering description: lockdown precedes capability when CONFIG_SECURITY_LOCKDOWN_LSM_EARLY is enabled, the integrity modules are always placed at the end of the list, and the remaining modules follow the order given by CONFIG_LSM or "lsm=".
[1] https://lore.kernel.org/r/[email protected]
Lincoln Wallace (2):
doc: LSM: describe CONFIG_LSM and lsm= as the selection mechanism
doc: LSM: fix module ordering description for /sys/kernel/security/lsm
Documentation/admin-guide/LSM/index.rst | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-)
Signature · 1 line
2.53.0
PATCH 1/2 doc: LSM: describe CONFIG_LSM and lsm= as the selection mechanism
The LSM usage document states that security modules are selectable at build time via CONFIG_DEFAULT_SECURITY and can be overridden at boot time via the "security=..." kernel command line argument.
CONFIG_DEFAULT_SECURITY no longer exists: LSMs are enabled via CONFIG_LSM, an ordered list of the LSMs to initialize, which can be overridden at boot time with the "lsm=" parameter. The "security=" parameter remains as a deprecated way to choose a legacy "major" security module, and is ignored when "lsm=" is specified; see commit 89a9684ea158 ("LSM: Ignore "security=" when "lsm=" is specified").
A previous attempt replaced "security=" with "lsm=" in place [1], which was rejected because the parameters are not equivalent:
"security=" selects a single major module while the built-in CONFIG_LSM list otherwise remains active, whereas "lsm=" must list every LSM to enable.
Update the paragraph to describe CONFIG_LSM and "lsm=" as the current selection mechanism, keeping "security=" documented as the deprecated legacy option, matching the wording in kernel-parameters.txt.
--- Documentation/admin-guide/LSM/index.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-)
Documentation/admin-guide/LSM/index.rst +5 -3
@@ -6,9 +6,11 @@ The Linux Security Module (LSM) framework provides a mechanism for various security checks to be hooked by new kernel extensions. The name "module" is a bit of a misnomer since these extensions are not actually loadable kernel modules. Instead, they are selectable at build-time via -CONFIG_DEFAULT_SECURITY and can be overridden at boot-time via the -``"security=..."`` kernel command line argument, in the case where multiple -LSMs were built into a given kernel. +CONFIG_LSM, an ordered list of the LSMs to enable, and can be +overridden at boot-time via the ``"lsm=..."`` kernel command line +argument. The ``"security=..."`` kernel command line argument remains +available to choose a legacy "major" security module, but has been +deprecated by the ``"lsm=..."`` parameter. The primary users of the LSM interface are Mandatory Access Control (MAC) extensions which provide a comprehensive security policy. Examples
Signature · 1 line
2.53.0
Re: [PATCH 1/2] doc: LSM: describe CONFIG_LSM and lsm= as the selection mechanism
Quoted 22 lines · On Jul 13, 2026 Lincoln Wallace <[email protected]> wrote:
The LSM usage document states that security modules are selectable at build time via
CONFIG_DEFAULT_SECURITYand can be overridden at boot time via the "security=..." kernel command line argument.
CONFIG_DEFAULT_SECURITYno longer exists: LSMs are enabled viaCONFIG_LSM, an ordered list of the LSMs to initialize, which can be overridden at boot time with the "lsm=" parameter. The "security=" parameter remains as a deprecated way to choose a legacy "major" security module, and is ignored when "lsm=" is specified; see commit89a9684ea158("LSM: Ignore "security=" when "lsm=" is specified").A previous attempt replaced "security=" with "lsm=" in place [1], which was rejected because the parameters are not equivalent:
"security=" selects a single major module while the built-inCONFIG_LSMlist otherwise remains active, whereas "lsm=" must list every LSM to enable.Update the paragraph to describe
CONFIG_LSMand "lsm=" as the current selection mechanism, keeping "security=" documented as the deprecated legacy option, matching the wording in kernel-parameters.txt.
Quoted 6 lines
Signed-off-by Lincoln Wallace <[email protected]>--- Documentation/admin-guide/LSM/index.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-)
Merged into lsm/dev, thanks!
--
paul-moore.com
PATCH 2/2 doc: LSM: fix module ordering description for /sys/kernel/security/lsm
In reply to Lincoln WallaceThe LSM usage document states that the capability module will always be first in /sys/kernel/security/lsm, followed by any "minor" modules and then the one "major" module.
This does not match the current LSM infrastructure:
- When CONFIG_SECURITY_LOCKDOWN_LSM_EARLY is enabled, lockdown is initialized as an early LSM, before all other modules including capability, and appears first in the list.
- The integrity modules (e.g. IMA and EVM) register with LSM_ORDER_LAST and are always placed at the end of the list, regardless of the position of the major module.
- The relative order of the remaining modules is not fixed by the framework; it follows CONFIG_LSM or the "lsm=" kernel command line parameter.
Rewrite the paragraph to describe the actual ordering: lockdown first when early lockdown is enabled, capability otherwise, integrity modules at the end, and the remaining modules in the configured order.
--- Documentation/admin-guide/LSM/index.rst | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-)
Documentation/admin-guide/LSM/index.rst +9 -3
@@ -27,9 +27,15 @@ man-pages project. A list of the active security modules can be found by reading ``/sys/kernel/security/lsm``. This is a comma separated list, and will always include the capability module. The list reflects the -order in which checks are made. The capability module will always -be first, followed by any "minor" modules (e.g. Yama) and then -the one "major" module (e.g. SELinux) if there is one configured. +order in which checks are made. The capability module will be +first, unless CONFIG_SECURITY_LOCKDOWN_LSM_EARLY is enabled, in +which case the lockdown module will precede it. The integrity +modules (e.g. IMA and EVM), if enabled in the kernel +configuration, are always placed at the end of the list. Any +other "minor" modules (e.g. Yama) and the one "major" module +(e.g. SELinux), if there is one configured, appear in between, +in the order given by CONFIG_LSM or the ``"lsm=..."`` kernel +command line parameter. Process attributes associated with "major" security modules should be accessed and maintained using the special files in ``/proc/.../attr``.
Signature · 1 line
2.53.0
Re: [PATCH 2/2] doc: LSM: fix module ordering description for /sys/kernel/security/lsm
Quoted 24 lines · On Jul 13, 2026 Lincoln Wallace <[email protected]> wrote:
The LSM usage document states that the capability module will always be first in
/sys/kernel/security/lsm, followed by any "minor" modules and then the one "major" module.This does not match the current LSM infrastructure:
- When
CONFIG_SECURITY_LOCKDOWN_LSM_EARLYis enabled, lockdown is initialized as an early LSM, before all other modules including capability, and appears first in the list.- The integrity modules (e.g. IMA and EVM) register with
LSM_ORDER_LASTand are always placed at the end of the list, regardless of the position of the major module.- The relative order of the remaining modules is not fixed by the framework; it follows
CONFIG_LSMor the "lsm=" kernel command line parameter.Rewrite the paragraph to describe the actual ordering: lockdown first when early lockdown is enabled, capability otherwise, integrity modules at the end, and the remaining modules in the configured order.
Quoted 4 lines
Signed-off-by Lincoln Wallace <[email protected]>--- Documentation/admin-guide/LSM/index.rst | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-)
Merged into lsm/dev, thanks!
--
paul-moore.com
Quoted 5 lines · Lincoln Wallace
The LSM usage document (
Documentation/admin-guide/LSM/index.rst) has not kept up with the LSM stacking infrastructure. It still describesCONFIG_DEFAULT_SECURITY, which no longer exists, and its description of the module ordering in/sys/kernel/security/lsmdoes not match what the framework actually does.
I've been stewing on this since it came up. We should probably remove the somewhat complicated logic from the Kconfig files if it's not adding value.
Quoted 21 lines
Patch 1 updates the selection mechanism description to
CONFIG_LSMand the "lsm=" parameter, keeping "security=" documented as the deprecated legacy option. This revisits an earlier attempt by Randy Dunlap [1] that was rejected for treating the two parameters as equivalent; the new text keeps them distinct.Patch 2 fixes the ordering description: lockdown precedes capability when
CONFIG_SECURITY_LOCKDOWN_LSM_EARLYis enabled, the integrity modules are always placed at the end of the list, and the remaining modules follow the order given byCONFIG_LSMor "lsm=".[1] https://lore.kernel.org/r/[email protected]
Lincoln Wallace (2):
doc: LSM: describeCONFIG_LSMand lsm= as the selection mechanism
doc: LSM: fix module ordering description for/sys/kernel/security/lsmDocumentation/admin-guide/LSM/index.rst | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-)
Quoted 3 lines · Casey Schaufler
I've been stewing on this since it came up. We should probably remove the somewhat complicated logic from the
Kconfigfiles if it's not adding value.
That seems worth doing, but it looks like a separate change to me. The document currently describes behaviour the code does not have, and that's worth correcting either way. If the Kconfig is simplified later, updating these paragraphs again should be a small part of that series.
Happy to help with the Kconfig cleanup if that would be useful.
Do you see anything in the two patches that needs adjusting as they stand?