doc: document landlock feature

diff --git a/doc/userguide/configuration/index.rst b/doc/userguide/configuration/index.rst
index 4bf805c8ac9511a9598765532a84858403ccebc2..5467d8a3fb5f90584e0cb2589fc74b65c5981094 100644 (file)
--- 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 (file)
index 0000000..00d0660
--- /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.