Skip to contentSkip to conversation

doc: LSM: update usage document for current LSM stacking

PATCH Applied Lincoln Wallace 3 participants 7 messages Jul 14 – Sep 11

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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
index b44ef68f6e4d..c24310c709dc 100644
@@ -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
maintainer Applied
#2 lore raw

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_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.

Quoted 6 lines
---
 Documentation/admin-guide/LSM/index.rst | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

Merged into lsm/dev, thanks!

--
paul-moore.com

#3 lore raw

PATCH 2/2 doc: LSM: fix module ordering description for /sys/kernel/security/lsm

In reply to Lincoln Wallace

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_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
index c24310c709dc..9518495edfbc 100644
@@ -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
maintainer Applied
#4 lore raw

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_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.

Quoted 4 lines
---
 Documentation/admin-guide/LSM/index.rst | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

Merged into lsm/dev, thanks!

--
paul-moore.com

#5 lore raw
In reply to Lincoln Wallace
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 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.

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_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(-)
#6 lore raw
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 Kconfig files 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?