Merge pull request #1836 from AkihiroSuda/docs

docs/config: add more tabpanes

Author: AkihiroSuda

website/content/en/docs/Config/Mount/_index.md

@@ -22,6 +22,13 @@ While the host works as an SFTP server, the host does not open any TCP port,
 as the host initiates an SSH connection into the guest and let the guest connect to the SFTP server via the stdin.
 
 An example configuration:
+{{< tabpane text=true >}}
+{{% tab header="CLI" %}}
+```bash
+limactl start --mount-type=reverse-sshfs
+```
+{{% /tab %}}
+{{% tab header="YAML" %}}
 ```yaml
 mountType: "reverse-sshfs"
 mounts:
@@ -43,6 +50,8 @@ mounts:
     # 🟢 Builtin default: "openssh-sftp-server" if OpenSSH SFTP Server binary is found, otherwise "builtin"
     sftpDriver: null
 ```
+{{% /tab %}}
+{{< /tabpane >}}
 
 The default value of `sftpDriver` has been set to "openssh-sftp-server" since Lima v0.10, when an OpenSSH SFTP Server binary
 such as `/usr/libexec/sftp-server` is detected on the host.
@@ -60,7 +69,15 @@ The "9p" mount type is implemented by using QEMU's virtio-9p-pci devices.
 virtio-9p-pci is also known as "virtfs", but note that this is unrelated to [virtio-fs](https://virtio-fs.gitlab.io/).
 
 An example configuration:
+{{< tabpane text=true >}}
+{{% tab header="CLI" %}}
+```bash
+limactl start --vm-type=qemu --mount-type=9p
+```
+{{% /tab %}}
+{{% tab header="YAML" %}}
 ```yaml
+vmType: "qemu"
 mountType: "9p"
 mounts:
 - location: "~"
@@ -81,6 +98,8 @@ mounts:
     # 🟢 Builtin default: "fscache" for non-writable mounts, "mmap" for writable mounts
     cache: null
 ```
+{{% /tab %}}
+{{< /tabpane >}}
 
 The "9p" mount type requires Lima v0.10.0 or later.
 
@@ -98,12 +117,21 @@ The "virtiofs" mount type is implemented via the virtio-fs device by using apple
 Linux guest kernel must enable the CONFIG_VIRTIO_FS support for this support.
 
 An example configuration:
+{{< tabpane text=true >}}
+{{% tab header="CLI" %}}
+```bash
+limactl start --vm-type=vz --mount-type=virtiofs
+```
+{{% /tab %}}
+{{% tab header="YAML" %}}
 ```yaml
 vmType: "vz"  # only for macOS; Linux uses 'qemu'
 mountType: "virtiofs"
 mounts:
 - location: "~"
 ```
+{{% /tab %}}
+{{< /tabpane >}}
 
 #### Caveats
 - For macOS, the "virtiofs" mount type is supported only on macOS 13 or above with `vmType: vz` config. See also [`vmtype.md`](./vmtype.md).
@@ -120,10 +148,19 @@ mounts:
 The "wsl2" mount type relies on using WSL2's navite disk sharing, where the root disk is available by default at `/mnt/$DISK_LETTER` (e.g. `/mnt/c/`).
 
 An example configuration:
+{{< tabpane text=true >}}
+{{% tab header="CLI" %}}
+```bash
+limactl start --vm-type=wsl2 --mount-type=wsl2
+```
+{{% /tab %}}
+{{% tab header="YAML" %}}
 ```yaml
 vmType: "wsl2"
 mountType: "wsl2"
 ```
+{{% /tab %}}
+{{< /tabpane >}}
 
 #### Caveats
 - WSL2 file permissions may not work exactly as expected when accessing files that are natively on the Windows disk ([more info](https://github.com/MicrosoftDocs/WSL/blob/mattw-wsl2-explainer/WSL/file-permissions.md))

website/content/en/docs/Config/Multi-arch/_index.md

@@ -71,6 +71,13 @@ See also https://github.com/containerd/nerdctl/blob/master/docs/multi-platform.m
 [Rosetta](https://developer.apple.com/documentation/virtualization/running_intel_binaries_in_linux_vms_with_rosetta) is known to be much faster than QEMU User Mode Emulation.
 Rosetta is available for [VZ](./vmtype.md) instances on ARM hosts.
 
+{{< tabpane text=true >}}
+{{% tab header="CLI" %}}
+```bash
+limactl start --vm-type=vz --rosetta
+```
+{{% /tab %}}
+{{% tab header="YAML" %}}
 ```yaml
 vmType: "vz"
 rosetta:
@@ -80,3 +87,5 @@ rosetta:
   # Register rosetta to /proc/sys/fs/binfmt_misc
   binfmt: true
 ```
+{{% /tab %}}
+{{< /tabpane >}}

website/content/en/docs/Config/Network/_index.md

@@ -3,7 +3,19 @@ title: Network
 weight: 30
 ---
 
-## user-mode network (192.168.5.0/24)
+See the following flowchart to choose the best network for you:
+```mermaid
+flowchart
+  connect_to_vm_via{"Connect to the VM via"} -- "localhost" --> default["Default"]
+  connect_to_vm_via -- "IP" --> connect_from{"Connect to the VM IP from"}
+  connect_from -- "Host" --> vm{"VM type"}
+  vm -- "vz" --> vzNAT["vzNAT"]
+  vm -- "qemu" --> shared["socket_vmnet (shared)"]
+  connect_from -- "Other VMs" --> userV2["user-v2"]
+  connect_from -- "Other hosts" --> bridged["socket_vmnet (bridged)"]
+```
+
+## Default user-mode network (192.168.5.0/24)
 
 By default Lima only enables the user-mode networking aka "slirp".
 
@@ -125,8 +137,15 @@ networks:
 
 </details>
 
-Instances can then reference these networks from their `lima.yaml` file:
+Instances can then reference these networks:
 
+{{< tabpane text=true >}}
+{{% tab header="CLI" %}}
+```bash
+limactl start --network=lima:shared
+```
+{{% /tab %}}
+{{% tab header="YAML" %}}
 ```yaml
 networks:
   # Lima can manage the socket_vmnet daemon for networks defined in $LIMA_HOME/_config/networks.yaml automatically.
@@ -139,6 +158,8 @@ networks:
   #   # Interface name, defaults to "lima0", "lima1", etc.
   #   interface: ""
 ```
+{{% /tab %}}
+{{< /tabpane >}}
 
 The network daemon is started automatically when the first instance referencing them is started,
 and will stop automatically once the last instance has stopped. Daemon logs will be stored in the
@@ -170,10 +191,19 @@ networks:
 |-------------------|-----------------------------|
 
 For [VZ](./vmtype.md) instances, the "vzNAT" network can be configured as follows:
+{{< tabpane text=true >}}
+{{% tab header="CLI" %}}
+```bash
+limactl start --vm-type=vz --network=vzNAT
+```
+{{% /tab %}}
+{{% tab header="YAML" %}}
 ```yaml
 networks:
 - vzNAT: true
 ```
+{{% /tab %}}
+{{< /tabpane >}}
 
 The range of the IP address is not specifiable.
 
@@ -201,10 +231,19 @@ networks:
 
 Instances can then reference these networks from their `lima.yaml` file:
 
+{{< tabpane text=true >}}
+{{% tab header="CLI" %}}
+```bash
+limactl start --network=lima:example-user-v2
+```
+{{% /tab %}}
+{{% tab header="YAML" %}}
 ```yaml
 networks:
    - lima: example-user-v2
 ```
+{{% /tab %}}
+{{< /tabpane >}}
 
 _Note_
 

website/content/en/docs/Config/VMType/_index.md

@@ -36,6 +36,13 @@ This option is used by default if "vmType" is not set.
 "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"
@@ -48,7 +55,8 @@ 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
@@ -71,6 +79,13 @@ mountType: "virtiofs"
 "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
@@ -84,6 +99,8 @@ containerd:
   system: true
   user: false
 ```
+{{% /tab %}}
+{{< /tabpane >}}
 
 ### Caveats
 - "wsl2" option is only supported on newer versions of Windows (roughly anything since 2019)

website/content/en/docs/Config/_index.md

@@ -4,3 +4,11 @@ weight: 5
 ---
 
 For all the configuration items, see <https://github.com/lima-vm/lima/blob/master/examples/default.yaml>.
+
+The current default spec:
+- OS: Ubuntu
+- CPU: 4 cores
+- Memory: 4 GiB
+- Disk: 100 GiB
+- Mounts: `~` (read-only), `/tmp/lima` (writable)
+- SSH: 127.0.0.1:60022

website/content/en/docs/Usage/_index.md

@@ -3,11 +3,10 @@ title: Usage
 weight: 2
 ---
 
-## Start a linux instance
+## Starting a Linux instance
 
-```console
-limactl start [--name=NAME] [--tty=false] <template://TEMPLATE>
-```
+Run `limactl start <INSTANCE>` to create and start the first instance.
+The `<INSTANCE>` name defaults to "default".
 
 ```console
 $ limactl start
@@ -24,38 +23,34 @@ Choose `Proceed with the current configuration`, and wait until "READY" to be pr
 
 For automation,  `--tty=false` flag can be used for disabling the interactive user interface.
 
-### Advanced usage
+### Customization
 To create an instance "default" from a template "docker":
-```console
-$ limactl start --name=default template://docker
+```bash
+limactl create --name=default template://docker
+limactl start default
 ```
 
-To create an instance "default" with modified parameters:
-```console
-$ limactl start --set='.cpus = 2 | .memory = "2GiB"'
-```
+See also the command reference:
+- [`limactl create`](../reference/limactl_create/)
+- [`limactl start`](../reference/limactl_start/)
+- [`limactl edit`](../reference/limactl_edit/)
 
-To see the template list:
-```console
-$ limactl start --list-templates
+### Executing Linux commands
+Run `limactl shell <INSTANCE> <COMMAND>` to launch `<COMMAND>` on the VM:
+```bash
+limactl shell default uname -a
 ```
 
-To create an instance "default" from a local file:
-```console
-$ limactl start --name=default /usr/local/share/lima/templates/fedora.yaml
-```
-
-To create an instance "default" from a remote URL (use carefully, with a trustable source):
-```console
-$ limactl start --name=default https://raw.githubusercontent.com/lima-vm/lima/master/examples/alpine.yaml
-```
-
-#### limactl shell
-`limactl shell <INSTANCE> <COMMAND>`: launch `<COMMAND>` on Linux.
+See also the command reference:
+- [`limactl shell`](../reference/limactl_shell/)
 
 For the "default" instance, this command can be shortened as `lima <COMMAND>`.
+```bash
+lima uname -a
+```
 The `lima` command also accepts the instance name as the environment variable `$LIMA_INSTANCE`.
 
+
 SSH can be used too:
 ```console
 $ limactl ls --format='{{.SSHConfigFile}}' default
@@ -64,28 +59,6 @@ $ limactl ls --format='{{.SSHConfigFile}}' default
 $ ssh -F /Users/example/.lima/default/ssh.config lima-default
 ```
 
-#### limactl completion
+### Shell completion
 - To enable bash completion, add `source <(limactl completion bash)` to `~/.bash_profile`.
-
 - To enable zsh completion, see `limactl completion zsh --help`
-
-## Configuration
-{{% fixlinks %}}
-
-See [`./examples/default.yaml`](./examples/default.yaml).
-
-The current default spec:
-- OS: Ubuntu 23.04 (Lunar Lobster)
-- CPU: 4 cores
-- Memory: 4 GiB
-- Disk: 100 GiB
-- Mounts: `~` (read-only), `/tmp/lima` (writable)
-- SSH: 127.0.0.1:60022
-
-## How it works
-
-- Hypervisor: [QEMU with HVF accelerator (default), or Virtualization.framework](./docs/vmtype.md)
-- Filesystem sharing: [Reverse SSHFS (default),  or virtio-9p-pci aka virtfs, or virtiofs](./docs/mount.md)
-- Port forwarding: `ssh -L`, automated by watching `/proc/net/tcp` and `iptables` events in the guest
-
-{{% /fixlinks %}}