diff --git a/README.md b/README.md index 0169d79c..1820fb2f 100644 --- a/README.md +++ b/README.md @@ -15,12 +15,12 @@ Demo GIF

-A Nix Flake to build NixOS and run it on one of several Type-2 -Hypervisors on NixOS/Linux. The project is intended to provide a more -isolated alternative to `nixos-container`. You can either build and -run MicroVMs like Nix packages, or alternatively install them as -systemd services declaratively in your host's Nix Flake or -imperatively with the provided `microvm` command. +A Nix Flake to build NixOS and run it virtualized by one of several +Virtual Machine Monitors (VMMs) on NixOS/Linux (kvm). The project is intended +to provide a more isolated alternative to `nixos-container`s. You can either +build and run MicroVMs like Nix packages, or alternatively install them as +systemd services declaratively in your host's Nix Flake or imperatively with +the provided `microvm` command. [Project Presentation (video)](https://media.ccc.de/v/nixcon-2023-34861-microvm-nix) @@ -28,8 +28,8 @@ imperatively with the provided `microvm` command. - MicroVMs are Virtual Machines but use special device interfaces (virtio) for high performance. -- This project runs them on NixOS hosts. -- You can choose one of five hypervisors for each MicroVM. +- This project runs them on NixOS (Linux/KVM) hosts. +- You can choose one of five VMMs for each MicroVM. - MicroVMs have a fixed RAM allocation (default: 512 MB) but can be shrunk using `microvm-balloon` - MicroVMs have a read-only root disk with either a prepopulated @@ -45,9 +45,12 @@ imperatively with the provided `microvm` command. attached to a MicroVM. `qemu` and `kvmtool` also support *user* networking which requires no additional setup on the host. -## Hypervisors +## Virtual Machine Monitors (VMM) ("Hypervisors") -| Hypervisor | Language | Restrictions | +_Hypervisor refer to the kernel part of a virtualization stack, such as KVM. +A VMM refers to the user-space part. Some also call them device managers._ + +| VMM (leveraging KVM) | Language | Restrictions | |-------------------------------------------------------------------------|----------|------------------------------------------| | [qemu](https://www.qemu.org/) | C | | | [cloud-hypervisor](https://www.cloudhypervisor.org/) | Rust | no 9p shares | @@ -88,7 +91,7 @@ nix run microvm#kvmtool-example nix run microvm#stratovirt-example ``` -### Run a MicroVM example with nested MicroVMs on 5 different Hypervisors +### Run a MicroVM example with nested MicroVMs on 5 different VMMs ```shell nix run microvm#vm diff --git a/doc/src/conventions.md b/doc/src/conventions.md index c27c5f7d..a774b217 100644 --- a/doc/src/conventions.md +++ b/doc/src/conventions.md @@ -17,10 +17,10 @@ MicroVM deployments using the information on this page. | | `share/microvm/system` | | `config.system.build.toplevel` symlink, used for comparing versions when running `microvm -l` | -## Generating custom operating system hypervisor packages +## Generating custom operating system VMM packages Because a microvm.nix runner package completely defines how to run the -Hypervisor, it is possible to define independent packages that +VMM, it is possible to define independent packages that virtualize other operating systems than NixOS. - Your NixOS configurations should export their runner package as diff --git a/doc/src/cpu-emulation.md b/doc/src/cpu-emulation.md index 2160492c..f295885f 100644 --- a/doc/src/cpu-emulation.md +++ b/doc/src/cpu-emulation.md @@ -1,7 +1,7 @@ # CPU emulation It's possible to emulate a CPU if desired. This feature is only -supported by the qemu hypervisor. +supported by the qemu VMM. **Note:** this feature has a significant performance impact. @@ -17,7 +17,7 @@ settings: environment. - Set `microvm.hypervisor` to `qemu`, given this is the only - hypervisor that supports this feature. + VMM that supports this feature. - Set `microvm.cpu` to the desired emulated CPU. You can find a [list of the available systems diff --git a/doc/src/faq.md b/doc/src/faq.md index b933aca9..c6416173 100644 --- a/doc/src/faq.md +++ b/doc/src/faq.md @@ -48,7 +48,7 @@ Once your MicroVM's journal data is visible in the `/var/log/journal/$machineId/` directories, `journalctl` can pick it up using the `-m`/`--merge` switch. -## Can I build with hypervisors from the host's nixpkgs instead of the MicroVM's? +## Can I build with VMMs from the host's nixpkgs instead of the MicroVM's? Yes. This scenario is enabled through the flake's `lib.buildRunner` function. See the [`nix run diff --git a/doc/src/interfaces.md b/doc/src/interfaces.md index c8962f73..1d19506f 100644 --- a/doc/src/interfaces.md +++ b/doc/src/interfaces.md @@ -31,7 +31,7 @@ configuration is necessary inside the MicroVM. Use a virtual tuntap Ethernet interface. Its name is the value of `id`. -Some Hypervisors may be able to automatically create these interfaces +Some VMMs may be able to automatically create these interfaces when running as root, which we advise against. Instead, create the interfaces before starting a MicroVM: diff --git a/doc/src/intro.md b/doc/src/intro.md index dbce17d6..c766579c 100644 --- a/doc/src/intro.md +++ b/doc/src/intro.md @@ -45,6 +45,6 @@ overhead has been reduced a lot by replacing emulated devices with *virtio* interfaces that have been optimized for this environment. This Flake offers you to run your MicroVMs not only on QEMU but with -other Hypervisors that have been explicitly authored for +other VMMs that have been explicitly authored for *virtio*. Some of them are written in Rust, a programming language that is renowned for being safer than C. diff --git a/doc/src/options.md b/doc/src/options.md index 38e7e9ac..4626d5b9 100644 --- a/doc/src/options.md +++ b/doc/src/options.md @@ -5,14 +5,14 @@ available for customization. These are the most important ones: | Option | Purpose | |--------------------------------|-----------------------------------------------------------------------------------------------------| -| `microvm.hypervisor` | Hypervisor to use by default in `microvm.declaredRunner` | +| `microvm.hypervisor` | VMM to use by default in `microvm.declaredRunner` | | `microvm.vcpu` | Number of Virtual CPU cores | | `microvm.mem` | RAM allocation in MB | | `microvm.interfaces` | Network interfaces | | `microvm.volumes` | Block device images | | `microvm.shares` | Shared filesystem directories | | `microvm.devices` | PCI/USB devices for host-to-vm passthrough | -| `microvm.socket` | Control socket for the Hypervisor so that a MicroVM can be shutdown cleanly | +| `microvm.socket` | Control socket for the VMM so that a MicroVM can be shutdown cleanly | | `microvm.user` | (qemu only) User account which Qemu will switch to when started as root | | `microvm.forwardPorts` | (qemu user-networking only) TCP/UDP port forwarding | | `microvm.kernelParams` | Like `boot.kernelParams` but will not end up in `system.build.toplevel`, saving you rebuilds | diff --git a/doc/src/output-options.md b/doc/src/output-options.md index ad27010e..c09eef8c 100644 --- a/doc/src/output-options.md +++ b/doc/src/output-options.md @@ -1,6 +1,6 @@ # MicroVM output options -Hypervisor runners are provided in the `config` generated by a +VMM runners are provided in the `config` generated by a nixosSystem for you to use inside and outside your configuration. | Option | Purpose | @@ -8,7 +8,7 @@ nixosSystem for you to use inside and outside your configuration. | `microvm.declaredRunner` | Runner package selected according to `microvm.hypervisor` | | `microvm.runners` | Attribute set of runner packages per known Hypervisor. | -The `microvm.declaredRunner` selects the hypervisor according to the +The `microvm.declaredRunner` selects the VMM according to the configured `microvm.hypervisor`. ```bash @@ -16,7 +16,7 @@ nix run .#nixosConfigurations.my-microvm.config.microvm.declaredRunner ``` The `microvm.runners` option provides a runner for each known -Hypervisor regardless of the `microvm.hypervisor` config setting. To +VMM regardless of the `microvm.hypervisor` config setting. To build *my-microvm* for Firecracker for example: ```bash @@ -28,7 +28,7 @@ nix run .#nixosConfigurations.my-microvm.config.microvm.runners.firecracker One of the `microvm.runners` is picked by `microvm.declaredRunner` by evaluating `microvm.hypervisor`. -You may switch the Hypervisor quickly, but use `declaredRunner` in +You may switch the VMM quickly, but use `declaredRunner` in production. Any other NixOS configuration that evaluates the `microvm.hypervisor` option can be wrong when you pick from `microvm.runners` directly. One example would be the defaults set by diff --git a/doc/src/shares.md b/doc/src/shares.md index 271da658..3e85d9df 100644 --- a/doc/src/shares.md +++ b/doc/src/shares.md @@ -3,7 +3,7 @@ In `microvm.shares` elements the `proto` field allows either of two values: -- `9p` (default) is built into many hypervisors, allowing you to +- `9p` (default) is built into many VMMs, allowing you to quickly share a directory tree - `virtiofs` requires a separate virtiofsd service which is only