Skip to content

Commit b11fe11

Browse files
AkihiroSudaAkihiroSuda
committed
docs/config/vmtype: split to multiple pages
Signed-off-by: Akihiro Suda <akihiro.suda.cz@hco.ntt.co.jp>
1 parent 436ea60 commit b11fe11

File tree

5 files changed

+125
-119
lines changed

5 files changed

+125
-119
lines changed

‎website/content/en/docs/config/vmtype.md‎

Lines changed: 0 additions & 119 deletions
This file was deleted.

‎website/content/en/docs/config/vmtype/_index.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: VM types
3+
weight: 10
4+
---
5+
6+
Lima supports several VM drivers for running guest machines:
7+
8+
The vmType can be specified only on creating the instance.
9+
The vmType of existing instances cannot be changed.
10+
11+
> **💡 For developers**: See [Virtual Machine Drivers](../../dev/drivers) for technical details about driver architecture and creating custom drivers.
12+
13+
14+
See the following flowchart to choose the best vmType for you:
15+
```mermaid
16+
flowchart
17+
host{"Host OS"} -- "Windows" --> wsl2["WSL2"]
18+
host -- "Linux" --> qemu["QEMU"]
19+
host -- "macOS" --> intel_on_arm{"Need to run <br> Intel binaries <br> on ARM?"}
20+
intel_on_arm -- "Yes" --> just_elf{"Just need to <br> run Intel userspace (fast), <br> or entire Intel VM (slow)?"}
21+
just_elf -- "Userspace (fast)" --> vz
22+
just_elf -- "VM (slow)" --> qemu
23+
intel_on_arm -- "No" --> vz["VZ"]
24+
```
25+
26+
The default vmType is QEMU in Lima prior to v1.0.
27+
Starting with Lima v1.0, Lima will use VZ by default on macOS (>= 13.5) for new instances,
28+
unless the config is incompatible with VZ. (e.g., legacyBIOS or 9p is enabled)

‎website/content/en/docs/config/vmtype/qemu.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: QEMU
3+
weight: 1
4+
---
5+
6+
"qemu" option makes use of QEMU to run guest operating system.
7+
8+
Recommended QEMU version:
9+
- v8.2.1 or later (macOS)
10+
- v6.2.0 or later (Linux)

‎website/content/en/docs/config/vmtype/vz.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: VZ
3+
weight: 2
4+
---
5+
6+
| ⚡ Requirement | Lima >= 0.14, macOS >= 13.0 |
7+
|-------------------|-----------------------------|
8+
9+
"vz" option makes use of native virtualization support provided by macOS Virtualization.Framework.
10+
11+
An example configuration:
12+
{{< tabpane text=true >}}
13+
{{% tab header="CLI" %}}
14+
```bash
15+
limactl start --vm-type=vz
16+
```
17+
{{% /tab %}}
18+
{{% tab header="YAML" %}}
19+
```yaml
20+
# Example to run ubuntu using vmType: vz instead of qemu (Default)
21+
vmType: "vz"
22+
images:
23+
- location: "https://cloud-images.ubuntu.com/releases/24.04/release/ubuntu-24.04-server-cloudimg-amd64.img"
24+
arch: "x86_64"
25+
- location: "https://cloud-images.ubuntu.com/releases/24.04/release/ubuntu-24.04-server-cloudimg-arm64.img"
26+
arch: "aarch64"
27+
mounts:
28+
- location: "~"
29+
```
30+
{{% /tab %}}
31+
{{< /tabpane >}}
32+
### Caveats
33+
- "vz" option is only supported on macOS 13 or above
34+
- Virtualization.framework doesn't support running "intel guest on arm" and vice versa
35+
36+
### Known Issues
37+
- "vz" doesn't support `legacyBIOS: true` option, so guest machine like `centos-stream` and `oraclelinux-8` will not work on Intel Mac.
38+
- When running lima using "vz", `${LIMA_HOME}/<INSTANCE>/serial.log` will not contain kernel boot logs
39+
- On Intel Mac with macOS prior to 13.5, Linux kernel v6.2 (used by Ubuntu 23.04, Fedora 38, etc.) is known to be unbootable on vz.
40+
kernel v6.3 and later should boot, as long as it is booted via GRUB.
41+
https://github.com/lima-vm/lima/issues/1577#issuecomment-1565625668
42+
The issue is fixed in macOS 13.5.

‎website/content/en/docs/config/vmtype/wsl2.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: WSL2
3+
weight: 3
4+
---
5+
6+
> **Warning**
7+
> "wsl2" mode is experimental
8+
9+
| ⚡ Requirement | Lima >= 0.18 + (Windows >= 10 Build 19041 OR Windows 11) |
10+
| ----------------- | -------------------------------------------------------- |
11+
12+
"wsl2" option makes use of native virtualization support provided by Windows' `wsl.exe` ([more info](https://learn.microsoft.com/en-us/windows/wsl/about)).
13+
14+
An example configuration:
15+
{{< tabpane text=true >}}
16+
{{% tab header="CLI" %}}
17+
```bash
18+
limactl start --vm-type=wsl2 --mount-type=wsl2 --containerd=system
19+
```
20+
{{% /tab %}}
21+
{{% tab header="YAML" %}}
22+
```yaml
23+
# Example to run Fedora using vmType: wsl2
24+
vmType: wsl2
25+
images:
26+
# Source: https://github.com/runfinch/finch-core/blob/main/Dockerfile
27+
- location: "https://deps.runfinch.com/common/x86-64/finch-rootfs-production-amd64-1690920103.tar.zst"
28+
arch: "x86_64"
29+
digest: "sha256:53f2e329b8da0f6a25e025d1f6cc262ae228402ba615ad095739b2f0ec6babc9"
30+
mountType: wsl2
31+
containerd:
32+
system: true
33+
user: false
34+
```
35+
{{% /tab %}}
36+
{{< /tabpane >}}
37+
38+
### Caveats
39+
- "wsl2" option is only supported on newer versions of Windows (roughly anything since 2019)
40+
41+
### Known Issues
42+
- "wsl2" currently doesn't support many of Lima's options. See [this file](https://github.com/lima-vm/lima/blob/master/pkg/wsl2/wsl_driver_windows.go#L19) for the latest supported options.
43+
- When running lima using "wsl2", `${LIMA_HOME}/<INSTANCE>/serial.log` will not contain kernel boot logs
44+
- WSL2 requires a `tar` formatted rootfs archive instead of a VM image
45+
- Windows doesn't ship with ssh.exe, gzip.exe, etc. which are used by Lima at various points. The easiest way around this is to run `winget install -e --id Git.MinGit` (winget is now built in to Windows as well), and add the resulting `C:\Program Files\Git\usr\bin\` directory to your path.

0 commit comments

Comments
 (0)