From b785e00317011382ff22336842f9271a42c5dde0 Mon Sep 17 00:00:00 2001
From: Praveen K Paladugu <prapal@linux.microsoft.com>
Date: Tue, 11 Jun 2024 11:41:49 +0000
Subject: [PATCH] docs: Add doc for Landlock feature

Signed-off-by: Praveen K Paladugu <prapal@linux.microsoft.com>
---
 docs/landlock.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 docs/landlock.md

diff --git a/docs/landlock.md b/docs/landlock.md
new file mode 100644
index 000000000..4067151c7
--- /dev/null
+++ b/docs/landlock.md
@@ -0,0 +1,86 @@
+# Sandboxing using Landlock
+
+Landlock is a lightweight mechanism to allow unprivileged applications to
+sandbox themselves.
+
+During initial stages of running, applications can define the set of resources
+(mostly files) they need to access during their lifetime. All such rules are
+used to create a ruleset. Once the ruleset is applied, the process cannot access
+any resources outside of the ruleset during its lifetime, even if it were
+compromised.
+
+Under the scope of `read` and `write` access, Landlock currently allows some
+additional accesses (eg: for now, access to extended file attributes is always
+allowed). Eventually, Landlock will only allow accesses similar to Unix
+permissions.
+
+## Host Setup
+
+Landlock should be enabled in Host kernel to use it with cloud-hypervisor.
+Please following [Kernel-Support](https://docs.kernel.org/userspace-api/landlock.html#kernel-support) link to enable Landlock on Host kernel.
+
+
+Landlock support can be checked with following command:
+```
+$ sudo dmesg | grep -w  landlock
+[    0.000000] landlock: Up and running.
+```
+Linux kernel confirms Landlock support with above message in dmesg.
+
+## Implementation Details
+
+To enable Landlock, Cloud-Hypervisor process needs the full list of files it
+needs to access over its lifetime. Most of these files are received as VM
+Configuration (`struct VmConfig`). Landlock is enabled in `vm_create` stage, as
+this is the earliest stage in guest boot sequence which has access to guest's
+VM Configuration.
+
+## Enable Landlock
+
+Append `--landlock` to Cloud-Hypervisor's command line to enable Landlock
+support.
+
+If you expect guest to access additional paths after it boots
+(ex: during hotplug), those paths can be passed using `--landlock-rules` command
+line parameter.
+
+## Usage Examples
+
+To enable Landlock:
+
+```
+./cloud-hypervisor \
+	--kernel ./linux-cloud-hypervisor/arch/x86/boot/compressed/vmlinux.bin \
+	--disk path=focal-server-cloudimg-amd64.raw path=/tmp/ubuntu-cloudinit.img \
+	--cmdline "console=hvc0 root=/dev/vda1 rw" \
+	--cpus boot=4 \
+	--memory size=1024M \
+	--net "tap=,mac=,ip=,mask=" \
+	--landlock
+```
+Hotplugging any new file-backed resources to above guest will result in
+**Permission Denied** error.
+
+To enable Landlock with hotplug support:
+
+```
+./cloud-hypervisor \
+	--api-socket /tmpXXXX/ch.socket \
+	--kernel ./linux-cloud-hypervisor/arch/x86/boot/compressed/vmlinux.bin \
+	--disk path=focal-server-cloudimg-amd64.raw path=/tmp/ubuntu-cloudinit.img \
+	--cmdline "console=hvc0 root=/dev/vda1 rw" \
+	--cpus boot=4 \
+	--memory size=1024M \
+	--net "tap=,mac=,ip=,mask=" \
+	--landlock \
+	--landlock-rules path="/path/to/hotplug1",access="rw" path="/path/to/hotplug2",access="rw"
+
+./ch-remote --api-socket /tmpXXXX/ch.socket \
+	add-disk "path=/path/to/hotplug/blk.raw"
+```
+
+`--landlock-rules` accepts file or directory paths among its options.
+
+# References
+
+* https://landlock.io/