From 1b24f4d357fd922a5c3202fce2904da29a04ed12 Mon Sep 17 00:00:00 2001
From: Eric Leblond <el@stamus-networks.com>
Date: Wed, 3 Aug 2022 23:36:51 +0200
Subject: [PATCH] doc: document landlock feature

---
 doc/userguide/configuration/index.rst    |  1 +
 doc/userguide/configuration/landlock.rst | 57 ++++++++++++++++++++++++
 2 files changed, 58 insertions(+)
 create mode 100644 doc/userguide/configuration/landlock.rst

diff --git a/doc/userguide/configuration/index.rst b/doc/userguide/configuration/index.rst
index 4bf805c8ac..5467d8a3fb 100644
--- a/doc/userguide/configuration/index.rst
+++ b/doc/userguide/configuration/index.rst
@@ -8,3 +8,4 @@ Configuration
    snort-to-suricata
    multi-tenant
    dropping-privileges
+   landlock
diff --git a/doc/userguide/configuration/landlock.rst b/doc/userguide/configuration/landlock.rst
new file mode 100644
index 0000000000..00d0660c85
--- /dev/null
+++ b/doc/userguide/configuration/landlock.rst
@@ -0,0 +1,57 @@
+Using Landlock LSM
+==================
+
+Landlock is a Linux Security Module that has been introduced in Linux 5.13.
+It allows an application to sandbox itself by selecting access right to
+directories using a deny by default approach.
+
+Given its nature, Suricata knows where it is going to read files and where
+it is going to write them. So it is possible to implement an efficient
+Landlock sandboxing policy.
+
+Landlock is not active by default and needs to be activated in the
+YAML configuration. Configuration should come with sane default (defined
+at build time) and the command line options are used to dynamically add
+some permissions.
+
+Please note that Landlock is in blocking mode by default so careful testing
+is needed in production.
+
+To enable Landlock, edit the YAML and set ``enabled`` to ``yes``:
+
+::
+
+  landlock:
+    enabled: yes
+    directories:
+      write:
+        - /var/log/suricata/
+        - /var/run/
+      read:
+        - /usr/
+        - /etc/
+        - /etc/suricata/
+
+Following your running configuration you may have to add some directories.
+There are two lists you can use, ``write`` to add directories where write is needed
+and ``read`` for directories where read access is needed.
+
+Landlock is not active in some distributions and you may need to activate it
+at boot by adding ``lsm=landock`` to the Linux command line. For example,
+on a Debian distribution with at least a linux 5.13, you can edit ``/etc/default/grub``
+and update the ``GRUB_CMDLINE_LINUX_DEFAULT`` option:
+
+::
+
+  GRUB_CMDLINE_LINUX_DEFAULT="quiet lsm=landlock"
+
+Then run ``sudo update-grub`` and reboot.
+
+You can check at boot if it is running by doing:
+
+::
+
+  sudo dmesg | grep landlock || journalctl -kg landlock
+
+If you are interested in reading more about Landlock, you can use https://docs.kernel.org/userspace-api/landlock.html
+as entry point.