docs: documentation for running non-root VMM

Documentation for running non-root QEMU VMM in Kata runtime Fixes: kata-containers#2545 Signed-off-by: Feng Wang <[email protected]>
dong-df · Sep 21, 2021 · 305afc8 · 305afc8
1 parent 3a4aca4
commit 305afc8
Show file tree

Hide file tree

Showing 3 changed files with 35 additions and 2 deletions.
diff --git a/docs/how-to/README.md b/docs/how-to/README.md
@@ -35,3 +35,4 @@
 - [How to monitor Kata Containers in K8s](how-to-set-prometheus-in-k8s.md)
 - [How to use hotplug memory on arm64 in Kata Containers](how-to-hotplug-memory-arm64.md)
 - [How to setup swap devices in guest kernel](how-to-setup-swap-devices-in-guest-kernel.md)
+- [How to run rootless vmm](how-to-run-rootless-vmm.md)
diff --git a/docs/how-to/how-to-run-rootless-vmm.md b/docs/how-to/how-to-run-rootless-vmm.md
@@ -0,0 +1,33 @@
+## Introduction
+To improve security, Kata Container supports running the VMM process (currently only QEMU) as a non-`root` user.
+This document describes how to enable the rootless VMM mode and its limitations.
+
+## Pre-requisites
+The permission and ownership of the `kvm` device node (`/dev/kvm`) need to be configured to:
+```
+$ crw-rw---- 1 root kvm
+```
+use the following commands:
+```
+$ sudo groupadd kvm -r
+$ sudo chown root:kvm /dev/kvm
+$ sudo chmod 660 /dev/kvm
+```
+
+## Configure rootless VMM
+By default, the VMM process still runs as the root user. There are two ways to enable rootless VMM:
+1. Set the `rootless` flag to `true` in the hypervisor section of `configuration.toml`.
+2. Set the Kubernetes annotation `io.katacontainers.hypervisor.rootless` to `true`.
+
+## Implementation details
+When `rootless` flag is enabled, upon a request to create a Pod, Kata Containers runtime creates a random user and group (e.g. `kata-123`), and uses them to start the hypervisor process. 
+The `kvm` group is also given to the hypervisor process as a supplemental group to give the hypervisor process access to the `/dev/kvm` device. 
+Another necessary change is to move the hypervisor runtime files (e.g. `vhost-fs.sock`, `qmp.sock`) to a directory (under `/run/user/[uid]/`) where only the non-root hypervisor has access to.
+
+## Limitations
+
+1. Only the VMM process is running as a non-root user. Other processes such as Kata Container shimv2 and `virtiofsd` still run as the root user.
+2. Currently, this feature is only supported in QEMU. Still need to bring it to Firecracker and Cloud Hypervisor (see https://github.com/kata-containers/kata-containers/issues/2567).
+3. Certain features will not work when rootless VMM is enabled, including:
+   1. Passing devices to the guest (`virtio-blk`, `virtio-scsi`) will not work if the non-privileged user does not have permission to access it (leading to a permission denied error). A more permissive permission (e.g. 666) may overcome this issue. However, you need to be aware of the potential security implications of reducing the security on such devices.
+   2. `vfio` device will also not work because of permission denied error.
diff --git a/src/runtime/README.md b/src/runtime/README.md
@@ -26,8 +26,7 @@ to work seamlessly with both Docker and Kubernetes respectively.
 ## License
 
 The code is licensed under an Apache 2.0 license.
-
-See [the license file](../../LICENSE) for further details.
+See [the license file](https://github.com/kata-containers/kata-containers/blob/main/LICENSE) for further details.
 
 ## Platform support