Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/containers/libkrun

A dynamic library providing Virtualization-based process isolation capabilities
https://github.com/containers/libkrun

Last synced: 7 days ago
JSON representation

A dynamic library providing Virtualization-based process isolation capabilities

Awesome Lists containing this project

README 

        
# libkrun



```libkrun``` is a dynamic library that allows programs to easily acquire the ability to run processes in a partially isolated environment using [KVM](https://www.kernel.org/doc/Documentation/virtual/kvm/api.txt) Virtualization on Linux and [HVF](https://developer.apple.com/documentation/hypervisor) on macOS/ARM64.



It integrates a VMM (Virtual Machine Monitor, the userspace side of an Hypervisor) with the minimum amount of emulated devices required to its purpose, abstracting most of the complexity that comes from Virtual Machine management, offering users a simple C API.



## Use cases



* [crun](https://github.com/containers/crun/blob/main/krun.1.md): Adding Virtualization-based isolation to container and confidential workloads.

* [kunkit](https://github.com/containers/krunkit): Running GPU-enabled (via [venus](https://docs.mesa3d.org/drivers/venus.html)) lightweight VMs on macOS.

* [muvm](https://github.com/AsahiLinux/muvm): Launching a microVM with GPU acceleration (via [native context](https://www.youtube.com/watch?v=9sFP_yddLLQ)) for running games that require 4k pages.



## Goals and non-goals



### Goals



* Enable other projects to easily gain KVM-based process isolation capabilities.

* Be self-sufficient (no need for calling to an external VMM) and very simple to use.

* Be as small as possible, implementing only the features required to achieve its goals.

* Have the smallest possible footprint in every aspect (RAM consumption, CPU usage and boot time).

* Be compatible with a reasonable amount of workloads.



### Non-goals



* Become a generic VMM.

* Be compatible with all kinds of workloads.



## Variants



This project provides two different variants of the library:



- **libkrun**: Generic variant compatible with all Virtualization-capable systems.

- **libkrun-sev**: Variant including support for AMD SEV (SEV, SEV-ES and SEV-SNP) memory encryption and remote attestation. Requires an SEV-capable CPU.

- **libkrun-efi**: Variant that bundles OVMF/EDK2 for booting a distribution-provided kernel (only available on macOS).



Each variant generates a dynamic library with a different name (and ```soname```), so both can be installed at the same time in the same system.



## Virtio device support



### All variants



* virtio-console

* virtio-block

* virtio-fs

* virtio-gpu (venus and native-context)

* virtio-net

* virtio-vsock (for TSI and socket redirection)

* virtio-balloon (only free-page reporting)

* virtio-rng

* virtio-snd



## Networking



In ```libkrun```, networking is provided by two different, mutually exclusive techniques:



- **virtio-vsock + TSI**: A novel technique called **Transparent Socket Impersonation** which allows the VM to have network connectivity without a virtual interface. This technique supports both outgoing and incoming connections. It's possible for userspace applications running in the VM to transparently connect to endpoints outside the VM and receive connections from the outside to ports listening inside the VM. Requires a custom kernel (like the one bundled in **libkrunfw**) and it's limited to AF_INET SOCK_DGRAM and SOCK_STREAM sockets.



- **virtio-net + passt/gvproxy**: A conventional virtual interface that allows the guest to communicate with the outside through the VMM using a supporting application like [passt](https://passt.top/passt/about/) or [gvproxy](https://github.com/containers/gvisor-tap-vsock). 



## Building and installing



### Linux (generic variant)



#### Requirements



* [libkrunfw](https://github.com/containers/libkrunfw)

* A working [Rust](https://www.rust-lang.org/) toolchain

* C Library static libraries, as the [init](init/init.c) binary is statically linked (package ```glibc-static``` in Fedora)

* patchelf



#### Optional features



* **GPU=1**: Enables virtio-gpu. Requires virglrenderer-devel.

* **VIRGL_RESOURCE_MAP2=1**: Uses virgl_resource_map2 function. Requires a virglrenderer-devel patched with [1374](https://gitlab.freedesktop.org/virgl/virglrenderer/-/merge_requests/1374)

* **BLK=1**: Enables virtio-block.

* **NET=1**: Enables virtio-net.

* **SND=1**: Enables virtio-snd.



#### Compiling



```

make [FEATURE_OPTIONS]

```



#### Installing



```

sudo make [FEATURE_OPTIONS] install

```



### Linux (SEV variant)



#### Requirements



* The SEV variant of [libkrunfw](https://github.com/containers/libkrunfw), which provides a ```libkrunfw-sev.so``` library.

* A working [Rust](https://www.rust-lang.org/) toolchain

* C Library static libraries, as the [init](init/init.c) binary is statically linked (package ```glibc-static``` in Fedora)

* patchelf

* OpenSSL headers and libraries (package ```openssl-devel``` in Fedora).



#### Compiling



```

make SEV=1

```



#### Installing



```

sudo make SEV=1 install

```



### macOS (EFI variant)



#### Requirements



* A working [Rust](https://www.rust-lang.org/) toolchain



#### Compiling



```

make EFI=1

```



#### Installing



```

sudo make EFI=1 install



```



## Using the library



Despite being written in Rust, this library provides a simple C API defined in [include/libkrun.h](include/libkrun.h)



## Examples



### chroot_vm



This is a simple example providing ```chroot```-like functionality using ```libkrun```.



#### Building chroot_vm



```

cd examples

make

```



#### Running chroot_vm



To be able to ```chroot_vm```, you need first a directory to act as the root filesystem for your isolated program.



Use the ```rootfs``` target to get a rootfs prepared from the Fedora container image (note: you must have [podman](https://podman.io/) installed):



```

make rootfs

```



Now you can use ```chroot_vm``` to run a process within this new root filesystem:



```

./chroot_vm ./rootfs_fedora /bin/sh

```



If the ```libkrun``` and/or ```libkrunfw``` libraries were installed on a path that's not included in your ```/etc/ld.so.conf``` configuration, you may get an error like this one:



```

./chroot_vm: error while loading shared libraries: libkrun.so: cannot open shared object file: No such file or directory

```



To avoid this problem, use the ```LD_LIBRARY_PATH``` environment variable to point to the location where the libraries were installed. For example, if the libraries were installed in ```/usr/local/lib64```, use something like this:



```

LD_LIBRARY_PATH=/usr/local/lib64 ./chroot_vm rootfs/ /bin/sh

```



## Status



```libkrun``` has achieved maturity and starting version ```1.0.0``` the public API is guaranteed to be stable, following [SemVer](https://semver.org/).



## Getting in contact



The main communication channel is the [libkrun Matrix channel](https://matrix.to/#/#libkrun:matrix.org).



## Acknowledgments



```libkrun``` incorporates code from [Firecracker](https://github.com/firecracker-microvm/firecracker), [rust-vmm](https://github.com/rust-vmm/) and [Cloud-Hypervisor](https://github.com/cloud-hypervisor/).