diff --git a/docs/how-to/README.md b/docs/how-to/README.md index 07a46bcc22..177083c159 100644 --- 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 new file mode 100644 index 0000000000..3986de252b --- /dev/null +++ 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. \ No newline at end of file diff --git a/src/runtime/README.md b/src/runtime/README.md index f8a3efe5d8..2a893681f1 100644 --- 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