[v2,1/2] landlock: Extend documentation for kernel support
Commit Message
Extend the kernel support section with one subsection for build time
configuration and another for boot time configuration.
Extend the boot time subsection with a concrete example.
Update the journalctl command to include the boot option.
Cc: Günther Noack <gnoack@google.com>
Cc: Kees Cook <keescook@chromium.org>
Signed-off-by: Mickaël Salaün <mic@digikod.net>
---
Changes since v1:
* New patch, suggested by Kees Cook.
---
Documentation/userspace-api/landlock.rst | 57 +++++++++++++++++++++---
1 file changed, 51 insertions(+), 6 deletions(-)
base-commit: b4007fd27206c478a4b76e299bddf4a71787f520
Comments
On Tue, Feb 27, 2024 at 12:05:49PM +0100, Mickaël Salaün wrote:
> Extend the kernel support section with one subsection for build time
> configuration and another for boot time configuration.
>
> Extend the boot time subsection with a concrete example.
>
> Update the journalctl command to include the boot option.
>
> Cc: Günther Noack <gnoack@google.com>
> Cc: Kees Cook <keescook@chromium.org>
> Signed-off-by: Mickaël Salaün <mic@digikod.net>
> ---
>
> Changes since v1:
> * New patch, suggested by Kees Cook.
> ---
> Documentation/userspace-api/landlock.rst | 57 +++++++++++++++++++++---
> 1 file changed, 51 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
> index 2e3822677061..838cc27db232 100644
> --- a/Documentation/userspace-api/landlock.rst
> +++ b/Documentation/userspace-api/landlock.rst
> +Boot time configuration
> +-----------------------
> +
> If the running kernel does not have ``landlock`` in ``CONFIG_LSM``, then we can
> -still enable it by adding ``lsm=landlock,[...]`` to
> +enable Landlock by adding ``lsm=landlock,[...]`` to
> Documentation/admin-guide/kernel-parameters.rst thanks to the bootloader
> configuration.
I would suggest: s/thanks to/in/
> +For example, if the current built-in configuration is:
> +
> +.. code-block:: console
> +
> + $ zgrep -h "^CONFIG_LSM=" "/boot/config-$(uname -r)" /proc/config.gz 2>/dev/null
> + CONFIG_LSM="lockdown,yama,integrity,apparmor"
> +
> +...and if the cmdline doesn't contain ``landlock`` either:
> +
> +.. code-block:: console
> +
> + $ sed -n 's/.*\(\<lsm=\S\+\).*/\1/p' /proc/cmdline
> + lsm=lockdown,yama,integrity,apparmor
> +
> +...we should configure the bootloader to set a cmdline extending the ``lsm``
> +list with the ``landlock,`` prefix::
Nit: Is the double colon at the end of this line accidental?
(It does not appear before the previous code block.)
> +
> + lsm=landlock,lockdown,yama,integrity,apparmor
> +
> +After a reboot, we can check that Landlock is up and running by looking at
> +kernel logs:
> +
> +.. code-block:: console
> +
> + # dmesg | grep landlock || journalctl -kb -g landlock
> + [ 0.000000] Command line: [...] lsm=landlock,lockdown,yama,integrity,apparmor
> + [ 0.000000] Kernel command line: [...] lsm=landlock,lockdown,yama,integrity,apparmor
> + [ 0.000000] LSM: initializing lsm=lockdown,capability,landlock,yama,integrity,apparmor
> + [ 0.000000] landlock: Up and running.
> +
> +Note that according to the built time kernel configuration,
s/built time/build time/
^
It feels like the phrase "according to" could be slightly more specific here.
To paraphrase Alejandro Colomar, "Note that" is usually redundant.
https://lore.kernel.org/all/0aafcdd6-4ac7-8501-c607-9a24a98597d7@gmail.com/
I'd suggest:
The kernel may be configured at build time to always load the ``lockdown`` and
``capability`` LSMs. In that case, these LSMs will appear at the beginning of
the ``LSM: initializing`` log line as well, even if they are not configured in
the boot loader.
> +``lockdown,capability,`` may always stay at the beginning of the ``LSM:
> +initializing lsm=`` list even if they are not configured with the bootloader,
Nit: The man pages spell this in two words as "boot loader".
> +which is OK.
> +
> +Network support
> +---------------
> +
> To be able to explicitly allow TCP operations (e.g., adding a network rule with
> ``LANDLOCK_ACCESS_NET_BIND_TCP``), the kernel must support TCP
> (``CONFIG_INET=y``). Otherwise, sys_landlock_add_rule() returns an
>
> base-commit: b4007fd27206c478a4b76e299bddf4a71787f520
> --
> 2.44.0
>
Reviewed-by: Günther Noack <gnoack@google.com>
@@ -19,11 +19,12 @@ unexpected/malicious behaviors in user space applications. Landlock empowers
any process, including unprivileged ones, to securely restrict themselves.
We can quickly make sure that Landlock is enabled in the running system by
-looking for "landlock: Up and running" in kernel logs (as root): ``dmesg | grep
-landlock || journalctl -kg landlock`` . Developers can also easily check for
-Landlock support with a :ref:`related system call <landlock_abi_versions>`. If
-Landlock is not currently supported, we need to :ref:`configure the kernel
-appropriately <kernel_support>`.
+looking for "landlock: Up and running" in kernel logs (as root):
+``dmesg | grep landlock || journalctl -kb -g landlock`` .
+Developers can also easily check for Landlock support with a
+:ref:`related system call <landlock_abi_versions>`.
+If Landlock is not currently supported, we need to
+:ref:`configure the kernel appropriately <kernel_support>`.
Landlock rules
==============
@@ -499,6 +500,9 @@ access rights.
Kernel support
==============
+Build time configuration
+------------------------
+
Landlock was first introduced in Linux 5.13 but it must be configured at build
time with ``CONFIG_SECURITY_LANDLOCK=y``. Landlock must also be enabled at boot
time as the other security modules. The list of security modules enabled by
@@ -507,11 +511,52 @@ contains ``CONFIG_LSM=landlock,[...]`` with ``[...]`` as the list of other
potentially useful security modules for the running system (see the
``CONFIG_LSM`` help).
+Boot time configuration
+-----------------------
+
If the running kernel does not have ``landlock`` in ``CONFIG_LSM``, then we can
-still enable it by adding ``lsm=landlock,[...]`` to
+enable Landlock by adding ``lsm=landlock,[...]`` to
Documentation/admin-guide/kernel-parameters.rst thanks to the bootloader
configuration.
+For example, if the current built-in configuration is:
+
+.. code-block:: console
+
+ $ zgrep -h "^CONFIG_LSM=" "/boot/config-$(uname -r)" /proc/config.gz 2>/dev/null
+ CONFIG_LSM="lockdown,yama,integrity,apparmor"
+
+...and if the cmdline doesn't contain ``landlock`` either:
+
+.. code-block:: console
+
+ $ sed -n 's/.*\(\<lsm=\S\+\).*/\1/p' /proc/cmdline
+ lsm=lockdown,yama,integrity,apparmor
+
+...we should configure the bootloader to set a cmdline extending the ``lsm``
+list with the ``landlock,`` prefix::
+
+ lsm=landlock,lockdown,yama,integrity,apparmor
+
+After a reboot, we can check that Landlock is up and running by looking at
+kernel logs:
+
+.. code-block:: console
+
+ # dmesg | grep landlock || journalctl -kb -g landlock
+ [ 0.000000] Command line: [...] lsm=landlock,lockdown,yama,integrity,apparmor
+ [ 0.000000] Kernel command line: [...] lsm=landlock,lockdown,yama,integrity,apparmor
+ [ 0.000000] LSM: initializing lsm=lockdown,capability,landlock,yama,integrity,apparmor
+ [ 0.000000] landlock: Up and running.
+
+Note that according to the built time kernel configuration,
+``lockdown,capability,`` may always stay at the beginning of the ``LSM:
+initializing lsm=`` list even if they are not configured with the bootloader,
+which is OK.
+
+Network support
+---------------
+
To be able to explicitly allow TCP operations (e.g., adding a network rule with
``LANDLOCK_ACCESS_NET_BIND_TCP``), the kernel must support TCP
(``CONFIG_INET=y``). Otherwise, sys_landlock_add_rule() returns an