Merge pull request #1237 from AkihiroSuda/dev

docs: update

README.ja.md

@@ -1,8 +1,8 @@
-This is an *informal* translation of [`README.md` (revision b65049d4, 2022-Oct-23)](https://github.com/lima-vm/lima/blob/b65049d4b89421fca5c73f494bb35e23b3c576c0/README.md) in Japanese.
+This is an *informal* translation of [`README.md` (revision c1368f45, 2022-Dec-12)](https://github.com/lima-vm/lima/blob/c1368f45d908947dd0828bc5caa00baa4a46be5c/README.md) in Japanese.
 This translation might be out of sync with the English version.
 Please refer to the [English `README.md`](README.md) for the latest information.
 
-[`README.md` (リビジョン b65049d4, 2022年10月23日)](https://github.com/lima-vm/lima/blob/b65049d4b89421fca5c73f494bb35e23b3c576c0/README.md)の *非正式* な日本語訳です。
+[`README.md` (リビジョン c1368f45, 2022年12月12日)](https://github.com/lima-vm/lima/blob/c1368f45d908947dd0828bc5caa00baa4a46be5c/README.md)の *非正式* な日本語訳です。
 英語版からの翻訳が遅れていることがあります。
 最新の情報については[英語版 `README.md`](README.md)をご覧ください。
 
@@ -53,7 +53,7 @@ Limaの目的は、Macユーザに[nerdctl (contaiNERDctl)](https://github.com/c
 コンテナ環境:
 - [Rancher Desktop](https://rancherdesktop.io/): デスクトップで管理できるKubernetesとコンテナ
 - [Colima](https://github.com/abiosoft/colima): macOSで小さく始めるDocker(とKubernetes)
-
+- [Finch](https://github.com/runfinch/finch): Finchはローカルでのコンテナ開発用のコマンドラインクライアント
 
 GUI:
 - [Lima xbar plugin](https://github.com/unixorn/lima-xbar-plugin): [xbar](https://xbarapp.com/) メニューバーから仮想マシンを開始・終了でき、稼働状態を確認できるプラグイン
@@ -126,15 +126,7 @@ brew install lima
 
 #### QEMU をインストールする
 
-最近のバージョンのQEMUをインストールしてください。
-
-M1のmacOSでは、[Homebrew版のQEMU `6.2.0_1`](https://github.com/Homebrew/homebrew-core/pull/96743) 以降が望ましいです。
-
-もしHomebrewを使っていないなら、最近のLinuxゲストを起動するには以下のコミットを含めてください:
-- https://github.com/qemu/qemu/commit/ad99f64f `hvf: arm: Use macros for sysreg shift/masking`
-- https://github.com/qemu/qemu/commit/7f6c295c `hvf: arm: Handle unknown ID registers as RES0`
-
-これらのコミットはQEMU 7.0には含まれていますが、 [QEMU 7.0はM1で3 GiB以上のメモリを使うのにmacOS 12.4以降を要する点に注意が必要です](https://github.com/lima-vm/lima/pull/796)。
+QEMU 7.0 以降をインストールしてください。
 
 #### Lima をインストールする
 
@@ -234,6 +226,14 @@ $ limactl start --name=default https://raw.githubusercontent.com/lima-vm/lima/ma
 #### `limactl edit`
 `limactl edit <INSTANCE>`: インスタンスを編集します
 
+#### `limactl disk`
+
+`limactl disk create <DISK> --size <SIZE>`: 新しい外部ディスクを作成しインスタンスに取り付けます
+
+`limactl disk delete <DISK>`: 既存のディスクを削除します
+
+`limactl disk list`: 既存のディスクの一覧を表示します
+
 #### `limactl completion`
 - bash補完を有効にするには、`~/.bash_profile`へ`source <(limactl completion bash)`を追加します。
 
@@ -262,8 +262,8 @@ Limaにはデータの喪失を引き起こすバグが含まれているかも
 
 ## 動作する仕組み
 
-- ハイパーバイザ: HVFアクセラレータを搭載したQEMU
-- ファイルシステム共有: [リバースsshfs (デフォルト)、もしくは virtio-9p-pci またの名を virtfs](./docs/mount.md)
+- ハイパーバイザ: [QEMU + HVFアクセラレータ(デフォルト)、もしくはVirtualization.framework](./docs/vmtype.md)
+- ファイルシステム共有: [リバースsshfs (デフォルト)、もしくは virtio-9p-pci またの名を virtfs、もしくはvirtiofs](./docs/mount.md)
 - ポートフォワーディング: ゲストの`/proc/net/tcp`と`iptables`を自動的に見つつ`ssh -L`
 
 ## 開発者ガイド
@@ -275,10 +275,10 @@ Limaにはデータの喪失を引き起こすバグが含まれているかも
 
 ### 助けを求めています
 :pray:
+- ドキュメント
+- CLIのユーザエクスペリエンス
 - パフォーマンス最適化
-- より多くのゲストディストリビューション
 - Windows ホスト
-- virtio-fs で、virtio-9p-pci またの名を virtfs を置き換える (QEMU側リポジトリで作業をする必要があります)
 - SSHを置き換える[vsock](https://github.com/apple/darwin-xnu/blob/xnu-7195.81.3/bsd/man/man4/vsock.4)(QEMU側リポジトリで作業をする必要があります)
 
 ## FAQとトラブルシューティング
@@ -300,13 +300,12 @@ Limaにはデータの喪失を引き起こすバグが含まれているかも
   - ["QEMUが遅いです"](#qemu%E3%81%8C%E9%81%85%E3%81%84%E3%81%A7%E3%81%99)
   - ["killed -9" エラー](#killed--9-%E3%82%A8%E3%83%A9%E3%83%BC)
   - ["`vmx_write_mem: mmu_gva_to_gpa XXXXXXXXXXXXXXXX failed`でQEMUがクラッシュします"](#vmx_write_mem-mmu_gva_to_gpa-xxxxxxxxxxxxxxxx-failed%E3%81%A7qemu%E3%81%8C%E3%82%AF%E3%83%A9%E3%83%83%E3%82%B7%E3%83%A5%E3%81%97%E3%81%BE%E3%81%99)
-- [SSH](#ssh)
-  - ["ポートフォワーディングが動きません"](#%E3%83%9D%E3%83%BC%E3%83%88%E3%83%95%E3%82%A9%E3%83%AF%E3%83%BC%E3%83%87%E3%82%A3%E3%83%B3%E3%82%B0%E3%81%8C%E5%8B%95%E3%81%8D%E3%81%BE%E3%81%9B%E3%82%93)
-  - ["Waiting for the essential requirement 1 of X: "ssh" で固まります"](#waiting-for-the-essential-requirement-1-of-x-ssh-%E3%81%A7%E5%9B%BA%E3%81%BE%E3%82%8A%E3%81%BE%E3%81%99)
-  - [`limactl cp`コマンドで"Permission denied"](#limactl-cp%E3%82%B3%E3%83%9E%E3%83%B3%E3%83%89%E3%81%A7permission-denied)
 - [ネットワーク](#%E3%83%8D%E3%83%83%E3%83%88%E3%83%AF%E3%83%BC%E3%82%AF)
   - ["ホストからゲストのIP 192.168.5.15にアクセスできない"](#%E3%83%9B%E3%82%B9%E3%83%88%E3%81%8B%E3%82%89%E3%82%B2%E3%82%B9%E3%83%88%E3%81%AEip-192168515%E3%81%AB%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9%E3%81%A7%E3%81%8D%E3%81%AA%E3%81%84)
-  - [Pingのパケットが重複してたり応答が極めて遅かったりする](#ping%E3%81%AE%E3%83%91%E3%82%B1%E3%83%83%E3%83%88%E3%81%8C%E9%87%8D%E8%A4%87%E3%81%97%E3%81%A6%E3%81%9F%E3%82%8A%E5%BF%9C%E7%AD%94%E3%81%8C%E6%A5%B5%E3%82%81%E3%81%A6%E9%81%85%E3%81%8B%E3%81%A3%E3%81%9F%E3%82%8A%E3%81%99%E3%82%8B)
+  - ["Pingのパケットが重複してたり応答が極めて遅かったりする"](#ping%E3%81%AE%E3%83%91%E3%82%B1%E3%83%83%E3%83%88%E3%81%8C%E9%87%8D%E8%A4%87%E3%81%97%E3%81%A6%E3%81%9F%E3%82%8A%E5%BF%9C%E7%AD%94%E3%81%8C%E6%A5%B5%E3%82%81%E3%81%A6%E9%81%85%E3%81%8B%E3%81%A3%E3%81%9F%E3%82%8A%E3%81%99%E3%82%8B)
+- [ファイルシステム共有](#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%82%B7%E3%82%B9%E3%83%86%E3%83%A0%E5%85%B1%E6%9C%89)
+  - ["ファイルシステムが遅い"](#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%82%B7%E3%82%B9%E3%83%86%E3%83%A0%E3%81%8C%E9%81%85%E3%81%84)
+  - ["ファイルシステムに書き込めない"](#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%82%B7%E3%82%B9%E3%83%86%E3%83%A0%E3%81%AB%E6%9B%B8%E3%81%8D%E8%BE%BC%E3%82%81%E3%81%AA%E3%81%84)
 - [外部プロジェクト](#%E5%A4%96%E9%83%A8%E3%83%97%E3%83%AD%E3%82%B8%E3%82%A7%E3%82%AF%E3%83%88)
   - ["Rancher Desktopを使っています。内蔵されているLimaを弄るにはどうすればよいですか。"](#rancher-desktop%E3%82%92%E4%BD%BF%E3%81%A3%E3%81%A6%E3%81%84%E3%81%BE%E3%81%99%E5%86%85%E8%94%B5%E3%81%95%E3%82%8C%E3%81%A6%E3%81%84%E3%82%8Blima%E3%82%92%E5%BC%84%E3%82%8B%E3%81%AB%E3%81%AF%E3%81%A9%E3%81%86%E3%81%99%E3%82%8C%E3%81%B0%E3%82%88%E3%81%84%E3%81%A7%E3%81%99%E3%81%8B)
 - ["ほかの問題をデバッグするためのヒントは？"](#%E3%81%BB%E3%81%8B%E3%81%AE%E5%95%8F%E9%A1%8C%E3%82%92%E3%83%87%E3%83%90%E3%83%83%E3%82%B0%E3%81%99%E3%82%8B%E3%81%9F%E3%82%81%E3%81%AE%E3%83%92%E3%83%B3%E3%83%88%E3%81%AF)
@@ -412,32 +411,6 @@ codesign -s - --entitlements entitlements.xml --force /usr/local/bin/qemu-system
 
 https://bugs.launchpad.net/qemu/+bug/1838390
 
-### SSH
-#### "ポートフォワーディングが動きません"
-Lima v0.7.0以前では、Limaは特権ポート(1-1023)のフォワーディングはサポートしていませんでした。例: 80番ではなく8080番を使わなければなりませんでした。
-
-macOSホストのLima v0.7.0 とそれ以降のバージョンでは、特権ポートのフォワーディングをサポートしています。
-
-Linuxホストでは、sysctlの値`net.ipv4.ip_unprivileged_port_start=0`をセットする必要があるかもしれません。
-
-#### "Waiting for the essential requirement 1 of X: "ssh" で固まります"
-
-
-M1のmacOSでは、最近のLinuxゲストを実行するには[Homebrew版のQEMU `6.2.0_1`](https://github.com/Homebrew/homebrew-core/pull/96743) 以降が必要です。
-`brew upgrade` を実行してQEMUを更新してください。
-
-もしHomebrewを使っていないならば、[インストール](#インストール)の節の「手動でのインストール方法」をご覧ください。
-
-デバッグするには、`~/.lima/<インスタンス>` にある `serial.log` もご覧ください。
-
-#### `limactl cp`コマンドで"Permission denied"
-
-`copy`コマンドはLima 0.5.0かそれ以降で作成されたインスタンスでのみ動作します。`INSTANCE`を実際のインスタンス名に置き換えることで古いインスタンスでの手動で必要なアイデンティティをインストールすることができます。
-
-```console
-< ~/.lima/_config/user.pub limactl shell INSTANCE sh -c 'tee -a ~/.ssh/authorized_keys'
-```
-
 ### ネットワーク
 #### "ホストからゲストのIP 192.168.5.15にアクセスできない"
 
@@ -448,7 +421,7 @@ M1のmacOSでは、最近のLinuxゲストを実行するには[Homebrew版のQE
 
 [`./docs/network.md`](./docs/network.md)を参照してください。
 
-#### Pingのパケットが重複してたり応答が極めて遅かったりする
+#### "Pingのパケットが重複してたり応答が極めて遅かったりする"
 
 LimaはQEMUのSLIRPネットワークを使うので`ping`はそのままでは動きません:
 
@@ -461,6 +434,22 @@ PING google.com (172.217.165.14): 56 data bytes
 
 詳しくは, [Documentation/Networking](https://wiki.qemu.org/Documentation/Networking#User_Networking_.28SLIRP.29)をご覧ください。
 
+### ファイルシステム共有
+#### "ファイルシステムが遅い"
+virtiofsを試してください。 [`docs/mount.md`](./docs/mount.md)をご覧ください。
+
+#### "ファイルシステムに書き込めない"
+ホームディレクトリはデフォルトでは読み込み専用でマウントされます。
+書き込みを有効化するには、YAMLに `writable: true` を指定してください:
+
+```yaml
+mounts:
+- location: "~"
+  writable: true
+```
+
+既存のインスタンスのYAMLを編集するには `limactl edit <インスタンス>` を実行してください。
+
 ### 外部プロジェクト
 #### "Rancher Desktopを使っています。内蔵されているLimaを弄るにはどうすればよいですか。"
 

README.md

@@ -116,15 +116,7 @@ brew install lima
 
 #### Install QEMU
 
-Install recent version of QEMU.
-
-On M1 macOS, [Homebrew's QEMU `6.2.0_1`](https://github.com/Homebrew/homebrew-core/pull/96743) or later is recommended.
-
-If you are not using Homebrew, make sure to include the following commits to boot recent Linux guests:
-- https://github.com/qemu/qemu/commit/ad99f64f `hvf: arm: Use macros for sysreg shift/masking`
-- https://github.com/qemu/qemu/commit/7f6c295c `hvf: arm: Handle unknown ID registers as RES0`
-
-These commits are also included in the QEMU 7.0, however, [it should be noted that QEMU 7.0 needs macOS 12.4 or later to use more than 3 GiB memory on M1](https://github.com/lima-vm/lima/pull/796).
+Install QEMU 7.0 or later.
 
 #### Install Lima
 
@@ -262,8 +254,8 @@ The current default spec:
 
 ## How it works
 
-- Hypervisor: QEMU with HVF accelerator
-- Filesystem sharing: [Reverse SSHFS (default),  or virtio-9p-pci aka virtfs](./docs/mount.md)
+- 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
 
 ## Developer guide
@@ -276,10 +268,10 @@ The current default spec:
 
 ### Help wanted
 :pray:
+- Documents
+- CLI user experience
 - Performance optimization
-- More guest distros
 - Windows hosts
-- virtio-fs to replace virtio-9p-pci aka virtfs (work has to be done on QEMU repo)
 - [vsock](https://github.com/apple/darwin-xnu/blob/xnu-7195.81.3/bsd/man/man4/vsock.4) to replace SSH (work has to be done on QEMU repo)
 
 ## FAQs & Troubleshooting
@@ -301,13 +293,12 @@ The current default spec:
   - ["QEMU is slow"](#qemu-is-slow)
   - [error "killed -9"](#error-killed--9)
   - ["QEMU crashes with `vmx_write_mem: mmu_gva_to_gpa XXXXXXXXXXXXXXXX failed`"](#qemu-crashes-with-vmx_write_mem-mmu_gva_to_gpa-xxxxxxxxxxxxxxxx-failed)
-- [SSH](#ssh)
-  - ["Port forwarding does not work"](#port-forwarding-does-not-work)
-  - [stuck on "Waiting for the essential requirement 1 of X: "ssh"](#stuck-on-waiting-for-the-essential-requirement-1-of-x-ssh)
-  - ["permission denied" for `limactl cp` command](#permission-denied-for-limactl-cp-command)
 - [Networking](#networking)
   - ["Cannot access the guest IP 192.168.5.15 from the host"](#cannot-access-the-guest-ip-192168515-from-the-host)
-  - [Ping shows duplicate packets and massive response times](#ping-shows-duplicate-packets-and-massive-response-times)
+  - ["Ping shows duplicate packets and massive response times"](#ping-shows-duplicate-packets-and-massive-response-times)
+- [Filesystem sharing](#filesystem-sharing)
+  - ["Filesystem is slow"](#filesystem-is-slow)
+  - ["Filesystem is not writable"](#filesystem-is-not-writable)
 - [External projects](#external-projects)
   - ["I am using Rancher Desktop. How to deal with the underlying Lima?"](#i-am-using-rancher-desktop-how-to-deal-with-the-underlying-lima)
 - ["Hints for debugging other problems?"](#hints-for-debugging-other-problems)
@@ -417,31 +408,6 @@ A workaround is to set environment variable `QEMU_SYSTEM_X86_64="qemu-system-x86
 
 https://bugs.launchpad.net/qemu/+bug/1838390
 
-### SSH
-#### "Port forwarding does not work"
-Prior to Lima v0.7.0, Lima did not support forwarding privileged ports (1-1023). e.g., you had to use 8080, not 80.
-
-Lima v0.7.0 and later supports forwarding privileged ports on macOS hosts.
-
-On Linux hosts, you might have to set sysctl value `net.ipv4.ip_unprivileged_port_start=0`.
-
-#### stuck on "Waiting for the essential requirement 1 of X: "ssh"
-
-On M1 macOS, QEMU needs to be [Homebrew's QEMU `6.2.0_1`](https://github.com/Homebrew/homebrew-core/pull/96743) or later to run recent Linux guests.
-Run `brew upgrade` to upgrade QEMU.
-
-If you are not using Homebrew, see the "Manual installation steps" in the [Installation](#installation) section.
-
-See also `serial.log` in `~/.lima/<INSTANCE>` for debugging.
-
-#### "permission denied" for `limactl cp` command
-
-The `copy` command only works for instances that have been created by lima 0.5.0 or later. You can manually install the required identity on older instances with (replace `INSTANCE` with actual instance name):
-
-```console
-< ~/.lima/_config/user.pub limactl shell INSTANCE sh -c 'tee -a ~/.ssh/authorized_keys'
-```
-
 ### Networking
 #### "Cannot access the guest IP 192.168.5.15 from the host"
 
@@ -452,7 +418,7 @@ or [`vde_vmnet`](https://github.com/lima-vm/vde_vmnet) (Deprecated).
 
 See [`./docs/network.md`](./docs/network.md).
 
-#### Ping shows duplicate packets and massive response times
+#### "Ping shows duplicate packets and massive response times"
 
 Lima uses QEMU's SLIRP networking which does not support `ping` out of the box:
 
@@ -465,6 +431,22 @@ PING google.com (172.217.165.14): 56 data bytes
 
 For more details, see [Documentation/Networking](https://wiki.qemu.org/Documentation/Networking#User_Networking_.28SLIRP.29).
 
+### Filesystem sharing
+#### "Filesystem is slow"
+Try virtiofs. See [`docs/mount.md`](./docs/mount.md)
+
+#### "Filesystem is not writable"
+The home directory is mounted as read-only by default.
+To enable writing, specify `writable: true` in the YAML:
+
+```yaml
+mounts:
+- location: "~"
+  writable: true
+```
+
+Run `limactl edit <INSTANCE>` to open the YAML editor for an existing instance.
+
 ### External projects
 #### "I am using Rancher Desktop. How to deal with the underlying Lima?"
 

docs/deprecated.md

@@ -0,0 +1,13 @@
+# Deprecated features
+
+The following features are deprecated:
+
+- VDE support, including VNL and `vde_vmnet`
+- CentOS 7 support
+- Loading non-strict YAMLs (i.e., YAMLs with unknown properties)
+
+## Removed features
+- YAML property `network`: deprecated in [Lima v0.7.0](https://github.com/lima-vm/lima/commit/07e68230e70b21108d2db3ca5e0efd0e43842fbd)
+  and removed in Lima v0.14.0, in favor of `networks`
+- YAML property `useHostResolver`: deprecated in [Lima v0.8.1](https://github.com/lima-vm/lima/commit/eaeee31b0496174363c55da732c855ae21e9ad97)
+  and removed in Lima v0.14.0,in favor of `hostResolver.enabled`

docs/experimental.md

@@ -0,0 +1,7 @@
+# Experimental features
+
+The following features are experimental and subject to change:
+
+- `mountType: 9p`
+- `vmType: vz` and relevant configurations (`mountType: virtiofs`, `rosetta`, `[]networks.vzNAT`)
+- `arch: riscv64`

docs/multi-arch.md

@@ -3,6 +3,7 @@
 Lima supports two modes for running Intel-on-ARM and ARM-on-Intel:
 - [Slow mode](#slow-mode)
 - [Fast mode](#fast-mode)
+- [Fast mode 2](#fast-mode-2)
 
 ## [Slow mode: Intel VM on ARM Host / ARM VM on Intel Host](#slow-mode)
 
@@ -26,21 +27,21 @@ containerd:
 ```
 
 Running a VM with a foreign architecture is extremely slow.
-Consider using [Fast mode](#fast-mode) whenever possible.
+Consider using [Fast mode](#fast-mode) or [Fast mode 2](#fast-mode-2) whenever possible.
 
 ## [Fast mode: Intel containers on ARM VM on ARM Host / ARM containers on Intel VM on Intel Host](#fast-mode)
 
-This mode is significantly faster but often sacrifices compatibility.
+This mode uses QEMU User Mode Emulation.
+QEMU User Mode Emulation is significantly faster than QEMU System Mode Emulation, but it often sacrifices compatibility.
 
-Fast mode requires Lima v0.7.3 (nerdctl v0.13.0) or later.
+| :zap: Requirement | Lima >= 0.7.3 |
+|-------------------|---------------|
 
-If your VM was created with Lima prior to v0.7.3, you have to recreate the VM with Lima >= 0.7.3,
-or upgrade `/usr/local/bin/nerdctl` binary in the VM to [>= 0.13.0](https://github.com/containerd/nerdctl/releases) manually.
 
 Set up:
 ```bash
 lima sudo systemctl start containerd
-lima sudo nerdctl run --privileged --rm tonistiigi/binfmt --install all
+lima sudo nerdctl run --privileged --rm tonistiigi/binfmt:qemu-v7.0.0-28@sha256:66e11bea77a5ea9d6f0fe79b57cd2b189b5d15b93a2bdb925be22949232e4e55 --install all
 ```
 
 Run containers:
@@ -59,3 +60,24 @@ $ lima nerdctl push --all-platforms example.com/foo:latest
 ```
 
 See also https://github.com/containerd/nerdctl/blob/master/docs/multi-platform.md
+
+## [Fast mode 2 (Rosetta): Intel containers on ARM VM on ARM Host](#fast-mode-2)
+
+> **Warning**
+> "vz" mode, including support for Rosetta, is experimental
+
+| :zap: Requirement | Lima >= 0.14, macOS >= 13.0, ARM |
+|-------------------|----------------------------------|
+
+[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.
+
+```yaml
+vmType: "vz"
+rosetta:
+  # Enable Rosetta for Linux.
+  # Hint: try `softwareupdate --install-rosetta` if Lima gets stuck at `Installing rosetta...`
+  enabled: true
+  # Register rosetta to /proc/sys/fs/binfmt_misc
+  binfmt: true
+```