diff --git a/website/content/en/docs/config/environment-variables.md b/website/content/en/docs/config/environment-variables.md index 064917e91d7..69acb1e1f26 100644 --- a/website/content/en/docs/config/environment-variables.md +++ b/website/content/en/docs/config/environment-variables.md @@ -109,18 +109,18 @@ This page documents the environment variables used in Lima. ### `LIMA_SSH_PORT_FORWARDER` - **Description**: Specifies to use the SSH port forwarder (slow) instead of gRPC (fast, previously unstable) -- **Default**: `false` (since v1.1.0-beta.0) +- **Default**: `false` (since v1.1.0) - **Usage**: ```sh export LIMA_SSH_PORT_FORWARDER=false ``` - **The history of the default value**: - | Version | Default value | - |---------------|---------------------| - | v0.1.0 | `true`, effectively | - | v1.0.0 | `false` | - | v1.0.1 | `true` | - | v1.1.0-beta.0 | `false` | + | Version | Default value | + |---------|---------------------| + | v0.1.0 | `true`, effectively | + | v1.0.0 | `false` | + | v1.0.1 | `true` | + | v1.1.0 | `false` | ### `LIMA_USERNET_RESOLVE_IP_ADDRESS_TIMEOUT` diff --git a/website/content/en/docs/config/multi-arch.md b/website/content/en/docs/config/multi-arch.md index bbe90ede19e..443eeea48c8 100644 --- a/website/content/en/docs/config/multi-arch.md +++ b/website/content/en/docs/config/multi-arch.md @@ -3,7 +3,7 @@ title: Intel-on-ARM and ARM-on-Intel weight: 20 --- -Lima supports two modes for running Intel-on-ARM and ARM-on-Intel: +Lima supports several modes for running Intel-on-ARM and ARM-on-Intel: - [Slow mode](#slow-mode) - [Fast mode](#fast-mode) - [Fast mode 2](#fast-mode-2) diff --git a/website/content/en/docs/config/plugin/_index.md b/website/content/en/docs/config/plugin/_index.md new file mode 100644 index 00000000000..850e58c33ab --- /dev/null +++ b/website/content/en/docs/config/plugin/_index.md @@ -0,0 +1,4 @@ +--- +title: Plug-in +weight: 90 +--- diff --git a/website/content/en/docs/config/plugin/cli.md b/website/content/en/docs/config/plugin/cli.md new file mode 100644 index 00000000000..78be0ef0fc6 --- /dev/null +++ b/website/content/en/docs/config/plugin/cli.md @@ -0,0 +1,60 @@ +--- +title: CLI plugins +weight: 2 +--- + + | ⚡ Requirement | Lima >= 2.0 | + |----------------|-------------| + +Lima supports a plugin-like command aliasing system similar to `git`, `kubectl`, and `docker`. When you run a `limactl` command that doesn't exist, Lima will automatically look for an external program named `limactl-` in your system's PATH. + +## Creating Custom Aliases + +To create a custom alias, create an executable script with the name `limactl-` and place it somewhere in your PATH. + +**Example: Creating a `ps` alias for listing instances** + +1. Create a script called `limactl-ps`: + ```bash + #!/bin/sh + # Show instances in a compact format + limactl list --format table "$@" + ``` + +2. Make it executable and place it in your PATH: + ```bash + chmod +x limactl-ps + sudo mv limactl-ps /usr/local/bin/ + ``` + +3. Now you can use it: + ```bash + limactl ps # Shows instances in table format + limactl ps --quiet # Shows only instance names + ``` + +**Example: Creating an `sh` alias** + +```bash +#!/bin/sh +# limactl-sh - Connect to an instance shell +limactl shell "$@" +``` + +After creating this alias: +```bash +limactl sh default # Equivalent to: limactl shell default +limactl sh myinstance bash # Equivalent to: limactl shell myinstance bash +``` + +## How It Works + +1. When you run `limactl `, Lima first tries to find a built-in command +2. If no built-in command is found, Lima searches for `limactl-` in your PATH +3. If found, Lima executes the external program and passes all remaining arguments to it +4. If not found, Lima shows the standard "unknown command" error + +This system allows you to: +- Create personal shortcuts and aliases +- Extend Lima's functionality without modifying the core application +- Share custom commands with your team by distributing scripts \ No newline at end of file diff --git a/website/content/en/docs/config/plugin/vm.md b/website/content/en/docs/config/plugin/vm.md new file mode 100644 index 00000000000..13779e3be26 --- /dev/null +++ b/website/content/en/docs/config/plugin/vm.md @@ -0,0 +1,7 @@ +--- +title: VM driver plugins +weight: 1 +--- + +See [Virtual Machine Drivers](../../dev/drivers.md). + \ No newline at end of file diff --git a/website/content/en/docs/config/port.md b/website/content/en/docs/config/port.md index 5fd1edabcdc..164e4b57ae7 100644 --- a/website/content/en/docs/config/port.md +++ b/website/content/en/docs/config/port.md @@ -11,12 +11,12 @@ Lima supports two port forwarders: SSH and GRPC. The default port forwarder is shown in the following table. -| Version | Default | -| ------------- | ------- | -| v0.1.0 | SSH | -| v1.0.0 | GRPC | -| v1.0.1 | SSH | -| v1.1.0-beta.0 | GRPC | +| Version | Default | +| --------| ------- | +| v0.1.0 | SSH | +| v1.0.0 | GRPC | +| v1.0.1 | SSH | +| v1.1.0 | GRPC | The default was once changed to GRPC in Lima v1.0, but it was reverted to SSH in v1.0.1 due to stability reasons. The default was further reverted to GRPC in Lima v1.1, as the stability issues were resolved. diff --git a/website/content/en/docs/config/vmtype.md b/website/content/en/docs/config/vmtype.md deleted file mode 100644 index 15d234e44d2..00000000000 --- a/website/content/en/docs/config/vmtype.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: VM types -weight: 10 ---- - -Lima supports two ways of running guest machines: -- [qemu](#qemu) -- [vz](#vz) - -The vmType can be specified only on creating the instance. -The vmType of existing instances cannot be changed. - -> **💡 For developers**: See [Virtual Machine Drivers](../../dev/drivers) for technical details about driver architecture and creating custom drivers. - - -See the following flowchart to choose the best vmType for you: -```mermaid -flowchart - host{"Host OS"} -- "Windows" --> wsl2["WSL2"] - host -- "Linux" --> qemu["QEMU"] - host -- "macOS" --> intel_on_arm{"Need to run
Intel binaries
on ARM?"} - intel_on_arm -- "Yes" --> just_elf{"Just need to
run Intel userspace (fast),
or entire Intel VM (slow)?"} - just_elf -- "Userspace (fast)" --> vz - just_elf -- "VM (slow)" --> qemu - intel_on_arm -- "No" --> vz["VZ"] -``` - -The default vmType is QEMU in Lima prior to v1.0. -Starting with Lima v1.0, Lima will use VZ by default on macOS (>= 13.5) for new instances, -unless the config is incompatible with VZ. (e.g., legacyBIOS or 9p is enabled) - -## QEMU -"qemu" option makes use of QEMU to run guest operating system. - -Recommended QEMU version: -- v8.2.1 or later (macOS) -- v6.2.0 or later (Linux) - -## VZ - -| ⚡ Requirement | Lima >= 0.14, macOS >= 13.0 | -|-------------------|-----------------------------| - -"vz" option makes use of native virtualization support provided by macOS Virtualization.Framework. - -An example configuration: -{{< tabpane text=true >}} -{{% tab header="CLI" %}} -```bash -limactl start --vm-type=vz --mount-type=virtiofs -``` -{{% /tab %}} -{{% tab header="YAML" %}} -```yaml -# Example to run ubuntu using vmType: vz instead of qemu (Default) -vmType: "vz" -images: -- location: "https://cloud-images.ubuntu.com/releases/24.04/release/ubuntu-24.04-server-cloudimg-amd64.img" - arch: "x86_64" -- location: "https://cloud-images.ubuntu.com/releases/24.04/release/ubuntu-24.04-server-cloudimg-arm64.img" - arch: "aarch64" -mounts: - - location: "~" -mountType: "virtiofs" -``` -{{% /tab %}} -{{< /tabpane >}} -### Caveats -- "vz" option is only supported on macOS 13 or above -- Virtualization.framework doesn't support running "intel guest on arm" and vice versa - -### Known Issues -- "vz" doesn't support `legacyBIOS: true` option, so guest machine like centos-stream and oraclelinux will not work -- When running lima using "vz", `${LIMA_HOME}//serial.log` will not contain kernel boot logs -- 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. - kernel v6.3 and later should boot, as long as it is booted via GRUB. - https://github.com/lima-vm/lima/issues/1577#issuecomment-1565625668 - The issue is fixed in macOS 13.5. - -## WSL2 -> **Warning** -> "wsl2" mode is experimental - -| ⚡ Requirement | Lima >= 0.18 + (Windows >= 10 Build 19041 OR Windows 11) | -| ----------------- | -------------------------------------------------------- | - -"wsl2" option makes use of native virtualization support provided by Windows' `wsl.exe` ([more info](https://learn.microsoft.com/en-us/windows/wsl/about)). - -An example configuration: -{{< tabpane text=true >}} -{{% tab header="CLI" %}} -```bash -limactl start --vm-type=wsl2 --mount-type=wsl2 --containerd=system -``` -{{% /tab %}} -{{% tab header="YAML" %}} -```yaml -# Example to run Fedora using vmType: wsl2 -vmType: wsl2 -images: -# Source: https://github.com/runfinch/finch-core/blob/main/Dockerfile -- location: "https://deps.runfinch.com/common/x86-64/finch-rootfs-production-amd64-1690920103.tar.zst" - arch: "x86_64" - digest: "sha256:53f2e329b8da0f6a25e025d1f6cc262ae228402ba615ad095739b2f0ec6babc9" -mountType: wsl2 -containerd: - system: true - user: false -``` -{{% /tab %}} -{{< /tabpane >}} - -### Caveats -- "wsl2" option is only supported on newer versions of Windows (roughly anything since 2019) - -### Known Issues -- "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. -- When running lima using "wsl2", `${LIMA_HOME}//serial.log` will not contain kernel boot logs -- WSL2 requires a `tar` formatted rootfs archive instead of a VM image -- 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. diff --git a/website/content/en/docs/config/vmtype/_index.md b/website/content/en/docs/config/vmtype/_index.md new file mode 100644 index 00000000000..469e917b11f --- /dev/null +++ b/website/content/en/docs/config/vmtype/_index.md @@ -0,0 +1,28 @@ +--- +title: VM types +weight: 10 +--- + +Lima supports several VM drivers for running guest machines: + +The vmType can be specified only on creating the instance. +The vmType of existing instances cannot be changed. + +> **💡 For developers**: See [Virtual Machine Drivers](../../dev/drivers) for technical details about driver architecture and creating custom drivers. + + +See the following flowchart to choose the best vmType for you: +```mermaid +flowchart + host{"Host OS"} -- "Windows" --> wsl2["WSL2"] + host -- "Linux" --> qemu["QEMU"] + host -- "macOS" --> intel_on_arm{"Need to run
Intel binaries
on ARM?"} + intel_on_arm -- "Yes" --> just_elf{"Just need to
run Intel userspace (fast),
or entire Intel VM (slow)?"} + just_elf -- "Userspace (fast)" --> vz + just_elf -- "VM (slow)" --> qemu + intel_on_arm -- "No" --> vz["VZ"] +``` + +The default vmType is QEMU in Lima prior to v1.0. +Starting with Lima v1.0, Lima will use VZ by default on macOS (>= 13.5) for new instances, +unless the config is incompatible with VZ. (e.g., legacyBIOS or 9p is enabled) \ No newline at end of file diff --git a/website/content/en/docs/config/vmtype/qemu.md b/website/content/en/docs/config/vmtype/qemu.md new file mode 100644 index 00000000000..8cb5e45b5a2 --- /dev/null +++ b/website/content/en/docs/config/vmtype/qemu.md @@ -0,0 +1,10 @@ +--- +title: QEMU +weight: 1 +--- + +"qemu" option makes use of QEMU to run guest operating system. + +Recommended QEMU version: +- v8.2.1 or later (macOS) +- v6.2.0 or later (Linux) \ No newline at end of file diff --git a/website/content/en/docs/config/vmtype/vz.md b/website/content/en/docs/config/vmtype/vz.md new file mode 100644 index 00000000000..cc35d294fc6 --- /dev/null +++ b/website/content/en/docs/config/vmtype/vz.md @@ -0,0 +1,42 @@ +--- +title: VZ +weight: 2 +--- + +| ⚡ Requirement | Lima >= 0.14, macOS >= 13.0 | +|-------------------|-----------------------------| + +"vz" option makes use of native virtualization support provided by macOS Virtualization.Framework. + +An example configuration: +{{< tabpane text=true >}} +{{% tab header="CLI" %}} +```bash +limactl start --vm-type=vz +``` +{{% /tab %}} +{{% tab header="YAML" %}} +```yaml +# Example to run ubuntu using vmType: vz instead of qemu (Default) +vmType: "vz" +images: +- location: "https://cloud-images.ubuntu.com/releases/24.04/release/ubuntu-24.04-server-cloudimg-amd64.img" + arch: "x86_64" +- location: "https://cloud-images.ubuntu.com/releases/24.04/release/ubuntu-24.04-server-cloudimg-arm64.img" + arch: "aarch64" +mounts: + - location: "~" +``` +{{% /tab %}} +{{< /tabpane >}} +### Caveats +- "vz" option is only supported on macOS 13 or above +- Virtualization.framework doesn't support running "intel guest on arm" and vice versa + +### Known Issues +- "vz" doesn't support `legacyBIOS: true` option, so guest machine like `centos-stream` and `oraclelinux-8` will not work on Intel Mac. +- When running lima using "vz", `${LIMA_HOME}//serial.log` will not contain kernel boot logs +- 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. + kernel v6.3 and later should boot, as long as it is booted via GRUB. + https://github.com/lima-vm/lima/issues/1577#issuecomment-1565625668 + The issue is fixed in macOS 13.5. \ No newline at end of file diff --git a/website/content/en/docs/config/vmtype/wsl2.md b/website/content/en/docs/config/vmtype/wsl2.md new file mode 100644 index 00000000000..b62117c2215 --- /dev/null +++ b/website/content/en/docs/config/vmtype/wsl2.md @@ -0,0 +1,45 @@ +--- +title: WSL2 +weight: 3 +--- + +> **Warning** +> "wsl2" mode is experimental + +| ⚡ Requirement | Lima >= 0.18 + (Windows >= 10 Build 19041 OR Windows 11) | +| ----------------- | -------------------------------------------------------- | + +"wsl2" option makes use of native virtualization support provided by Windows' `wsl.exe` ([more info](https://learn.microsoft.com/en-us/windows/wsl/about)). + +An example configuration: +{{< tabpane text=true >}} +{{% tab header="CLI" %}} +```bash +limactl start --vm-type=wsl2 --mount-type=wsl2 --containerd=system +``` +{{% /tab %}} +{{% tab header="YAML" %}} +```yaml +# Example to run Fedora using vmType: wsl2 +vmType: wsl2 +images: +# Source: https://github.com/runfinch/finch-core/blob/main/Dockerfile +- location: "https://deps.runfinch.com/common/x86-64/finch-rootfs-production-amd64-1690920103.tar.zst" + arch: "x86_64" + digest: "sha256:53f2e329b8da0f6a25e025d1f6cc262ae228402ba615ad095739b2f0ec6babc9" +mountType: wsl2 +containerd: + system: true + user: false +``` +{{% /tab %}} +{{< /tabpane >}} + +### Caveats +- "wsl2" option is only supported on newer versions of Windows (roughly anything since 2019) + +### Known Issues +- "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. +- When running lima using "wsl2", `${LIMA_HOME}//serial.log` will not contain kernel boot logs +- WSL2 requires a `tar` formatted rootfs archive instead of a VM image +- 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. diff --git a/website/content/en/docs/examples/_index.md b/website/content/en/docs/examples/_index.md index 6370ffa2c6e..52a69605fc0 100644 --- a/website/content/en/docs/examples/_index.md +++ b/website/content/en/docs/examples/_index.md @@ -14,12 +14,9 @@ By default, the VM has read-only accesses to `/Users/`. To allow writing to `/Users/`: ```bash -limactl edit --mount-writable --mount-type=virtiofs +limactl edit --mount-writable ``` -Specifying `--mount-type=virtiofs` is not necessary here, but it is highly recommended -for the best performance and stability. - {{% alert title="Hint" color=success %}} Lima prior to v2.0 mounts `/tmp/lima` too in read-write mode. @@ -81,7 +78,6 @@ limactl start \ --memory=8 \ --vm-type=vz \ --rosetta \ - --mount-type=virtiofs \ --mount-writable \ --network=vzNAT \ template://fedora @@ -92,7 +88,6 @@ limactl start \ - `--memory=8`: Set the amount of the memory to 8 GiB - `--vm-type=vz`: Use Apple's Virtualization.framework (vz) to enable Rosetta, virtiofs, and vzNAT - `--rosetta`: Allow running Intel (AMD) binaries on ARM -- `--mount-type=virtiofs`: Use virtiofs for better performance - `--mount-writable`: Make the home mount (`/Users/`) writable - `--network=vzNAT`: Make the VM reachable from the host by its IP address - `template://fedora`: Use Fedora diff --git a/website/content/en/docs/installation/_index.md b/website/content/en/docs/installation/_index.md index 40834393282..42222c6873b 100644 --- a/website/content/en/docs/installation/_index.md +++ b/website/content/en/docs/installation/_index.md @@ -19,6 +19,9 @@ Prerequisite: brew install lima ``` +Hint: specify `--HEAD` to install the HEAD (master) version. +The HEAD version provides early access to the latest features and improvements before they are officially released. + Homebrew formula is available [here](https://github.com/Homebrew/homebrew-core/blob/master/Formula/l/lima.rb). Supports macOS and Linux. {{% /tab %}} diff --git a/website/content/en/docs/reference/_index.md b/website/content/en/docs/reference/_index.md index 0294f49bb3d..802f1ddf6b6 100644 --- a/website/content/en/docs/reference/_index.md +++ b/website/content/en/docs/reference/_index.md @@ -1,4 +1,4 @@ --- title: Command Reference -weight: 5 +weight: 999 --- \ No newline at end of file diff --git a/website/content/en/docs/talks/_index.md b/website/content/en/docs/talks/_index.md index 1f2775fb785..032c7372483 100644 --- a/website/content/en/docs/talks/_index.md +++ b/website/content/en/docs/talks/_index.md @@ -30,3 +30,33 @@ Watch the [video](https://www.youtube.com/watch?v=GDInFocQJTU). [Akihiro Suda](https://github.com/AkihiroSuda) presented Lima in the CNCF project pavilion. Read the [slides](https://www.slideshare.net/AkihiroSuda/kubeconeu2023-lima-pavilion). + +### KubeCon + CloudNativeCon North America 2023 + +[Akihiro Suda](https://github.com/AkihiroSuda) presented Lima in the CNCF project pavilion. + +Read the [slides](https://github.com/AkihiroSuda/AkihiroSuda/blob/master/slides/2023/20231107%20%5BKubeCon%20NA%20Pavilion%5D%20Lima.pdf). + +## 2024 +### KubeCon + CloudNativeCon Europe 2024 + +[Akihiro Suda](https://github.com/AkihiroSuda) presented Lima in the CNCF project pavilion. + +Read the [slides](https://github.com/AkihiroSuda/AkihiroSuda/blob/master/slides/2024/20240321%20%5BKubeCon%20EU%20Pavilion%5D%20Lima.pdf). + +### KubeCon + CloudNativeCon North America 2024 + +[Akihiro Suda](https://github.com/AkihiroSuda) presented Lima in the CNCF project pavilion. + +Read the [slides](https://github.com/AkihiroSuda/AkihiroSuda/blob/master/slides/2024/20241115%20%5BKubeCon%20NA%20Pavilion%5D%20Lima.pdf). + +He also mentioned Lima in the presentation "What’s Going on in the Containerd Neighborhood?" in the context of case study of nerdctl. + +Read the [slides](https://static.sched.com/hosted_files/kccncna2024/74/KCCNC-SLC-24-Containerd-session.pdf)or watch the [video](https://www.youtube.com/watch?v=kCNhgNXVdxw). + +## 2025 +### KubeCon + CloudNativeCon Europe 2025 + +[Akihiro Suda](https://github.com/AkihiroSuda) presented Lima in the CNCF project pavilion. + +Read the [slides](https://github.com/AkihiroSuda/AkihiroSuda/blob/master/slides/2025/20250402%20%5BKubeCon%20EU%20Pavilion%5D%20Lima.pdf). \ No newline at end of file diff --git a/website/content/en/docs/usage/_index.md b/website/content/en/docs/usage/_index.md index 74ae09a8ea6..7a77bb564c4 100644 --- a/website/content/en/docs/usage/_index.md +++ b/website/content/en/docs/usage/_index.md @@ -72,61 +72,6 @@ Then you can connect directly: ssh lima-default ``` -### Command Aliasing (Plugin System) - -Lima supports a plugin-like command aliasing system similar to `git`, `kubectl`, and `docker`. When you run a `limactl` command that doesn't exist, Lima will automatically look for an external program named `limactl-` in your system's PATH. - -#### Creating Custom Aliases - -To create a custom alias, create an executable script with the name `limactl-` and place it somewhere in your PATH. - -**Example: Creating a `ps` alias for listing instances** - -1. Create a script called `limactl-ps`: - ```bash - #!/bin/sh - # Show instances in a compact format - limactl list --format table "$@" - ``` - -2. Make it executable and place it in your PATH: - ```bash - chmod +x limactl-ps - sudo mv limactl-ps /usr/local/bin/ - ``` - -3. Now you can use it: - ```bash - limactl ps # Shows instances in table format - limactl ps --quiet # Shows only instance names - ``` - -**Example: Creating an `sh` alias** - -```bash -#!/bin/sh -# limactl-sh - Connect to an instance shell -limactl shell "$@" -``` - -After creating this alias: -```bash -limactl sh default # Equivalent to: limactl shell default -limactl sh myinstance bash # Equivalent to: limactl shell myinstance bash -``` - -#### How It Works - -1. When you run `limactl `, Lima first tries to find a built-in command -2. If no built-in command is found, Lima searches for `limactl-` in your PATH -3. If found, Lima executes the external program and passes all remaining arguments to it -4. If not found, Lima shows the standard "unknown command" error - -This system allows you to: -- Create personal shortcuts and aliases -- Extend Lima's functionality without modifying the core application -- Share custom commands with your team by distributing scripts - ### Shell completion - To enable bash completion, add `source <(limactl completion bash)` to `~/.bash_profile`. - To enable zsh completion, see `limactl completion zsh --help`