Run a virtual iPhone on an Apple Silicon Mac.
Swift
Document the network modes and tunnel mode
Lakr6b08b0ce7a97
diff --git a/Documents/Guides/networking.md b/Documents/Guides/networking.mdnew file mode 100644index 00000000..a2b6d343--- /dev/null+++ b/Documents/Guides/networking.md@@ -0,0 +1,89 @@+# Networking++[Documentation](../README.md) · [Create a VM](create-and-run.md) · [Troubleshooting](troubleshooting.md)++Each VM has one network mode, stored in its `config.plist`. It is read when the+VM starts, so a change applies from the next launch.++| Mode | How the guest reaches the internet | Use it when |+| --- | --- | --- |+| `nat` | Virtualization.framework's built-in NAT | The default. The Mac has no VPN, or the VPN does not need to carry the guest. |+| `bridged` | Directly on a physical interface of the Mac, with its own address on that network | The guest has to be reachable from other machines on the LAN. |+| `tunnel` | Through ordinary connections opened by `vphone-vm` on the Mac | The Mac's traffic goes through a VPN or a proxy app, and the guest's traffic must follow it. |+| `none` | No network device | The guest must stay offline. |++## Choosing a mode++In Launchpad, stop the machine, then choose Settings… from the `⋯` menu or the+right-click menu. The Network section has a Mode picker. New Machine sets the mode under+Advanced Options.++From the command line:++```sh+vphone-cli vm config <name> --network tunnel+# or through Launchpad+vphone-launchpad-cli exec vm config <name> --network tunnel+```++`tunnel` needs a `VPhone.bundle` that lists it in `vphone-cli vm config --help`.+An older bundle rejects the setting.++## Why `tunnel` exists++`nat` and `bridged` send the guest's packets out through a physical interface.+When a VPN owns the Mac's default route (WireGuard, Cloudflare WARP, or a proxy+app in TUN mode such as Surge or Clash), those packets skip the VPN. They leave+unencrypted, or not at all.++In `tunnel` mode the guest's network card is implemented inside `vphone-vm`.+It answers DHCP, ARP and ping for the gateway, and turns each guest TCP+connection and UDP flow into a normal socket on the Mac. Those sockets follow+the Mac's routing table like any other app's, so the VPN carries them. It needs+no root, no new network interface and no change to the Mac's network settings.++In a proxy app the guest shows up as its own client, named after the machine,+and the app's rules apply to it as they would to any other app.++## What the guest sees++| Item | Value |+| --- | --- |+| Guest address | `192.168.127.3/24`, by DHCP |+| Gateway and DNS | `192.168.127.1` |+| MTU | 1500 |+| DNS | Queries to `192.168.127.1` go to the Mac's resolver |++## Limits++- **IPv4 only.** The guest gets no IPv6 address, and IPv6 traffic is dropped.+- **Outbound only.** Nothing on the Mac or the LAN can connect to a port in the+ guest through this network. USB access (`iproxy`, `ideviceinstaller`) and+ `vphone.sock` do not use the guest network, so they still work.+- **Ping reaches the gateway only.** ICMP to the internet is not forwarded,+ so `ping 1.1.1.1` in the guest fails even while TCP and UDP work.+- **Throughput is limited by `vphone-vm`.** Every packet is handled in this+ process. Downloads and video work, but `nat` is faster when no VPN is involved.++## Checking it works++1. Start the machine and wait for it to finish booting.+2. Read the guest's address:++ ```sh+ vphone-launchpad-cli guest rpc <name> device.network+ ```++ `en0` should show `192.168.127.3`. If it shows only an `fe80::` address,+ DHCP has not finished yet. Wait a few seconds and try again.+3. Open a page in the guest:++ ```sh+ vphone-launchpad-cli guest rpc <name> apps.open_url '{"url":"https://example.com"}'+ ```++4. On the Mac, the connections belong to `vphone-vm` and use the VPN's address:++ ```sh+ lsof -nP -a -i -p "$(pgrep -f 'vphone-vm.*<name>')"+ ```diff --git a/Documents/README_ja.md b/Documents/README_ja.mdindex 26c07a69..8e2f0ec1 100644--- a/Documents/README_ja.md+++ b/Documents/README_ja.md@@ -106,6 +106,7 @@ token は起動のたびに新しく生成されます。token を固定する| [作成と実行](Guides/create-and-run.md) | ファームウェアの入手元、作成の流れ、ストレージとバックアップ || [互換性ガイド](Guides/compatibility.md) | 検証済みのファームウェアの組み合わせ || [トラブルシューティング](Guides/troubleshooting.md) | よくあるエラーと対処方法 |+| [ネットワーク](Guides/networking.md) | ネットワークモードと、Mac が VPN やプロキシを使うときの `tunnel` || [Launchpad コマンドライン](Guides/launchpad-cli.md) | `vphone-launchpad-cli` でローカルビルドをインストールしてテストする || [研究記録](../Research/README.md) | パッチと実装の詳細 |diff --git a/Documents/README_ko.md b/Documents/README_ko.mdindex b401eb30..ba80b3ca 100644--- a/Documents/README_ko.md+++ b/Documents/README_ko.md@@ -106,6 +106,7 @@ curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8765/v1/health| [생성 및 실행](Guides/create-and-run.md) | 펌웨어 출처, 생성 절차, 저장과 백업 || [호환성 안내](Guides/compatibility.md) | 검증된 펌웨어 조합 || [문제 해결](Guides/troubleshooting.md) | 자주 발생하는 오류와 해결 방법 |+| [네트워크](Guides/networking.md) | 네트워크 모드, 그리고 Mac이 VPN이나 프록시를 쓸 때의 `tunnel` || [Launchpad 명령줄](Guides/launchpad-cli.md) | `vphone-launchpad-cli`로 로컬 빌드 설치 및 테스트 || [연구 기록](../Research/README.md) | 패치와 구현 세부 사항 |diff --git a/Documents/README_zh.md b/Documents/README_zh.mdindex 6b6a953b..b1385e72 100644--- a/Documents/README_zh.md+++ b/Documents/README_zh.md@@ -106,6 +106,7 @@ curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8765/v1/health| [创建与运行](Guides/create-and-run.md) | 固件来源、创建流程、存储与备份 || [兼容性说明](Guides/compatibility.md) | 已验证的固件组合 || [故障排查](Guides/troubleshooting.md) | 常见错误及解决方法 |+| [网络](Guides/networking.md) | 网络模式,以及在 Mac 使用 VPN 或代理时用的 `tunnel` || [Launchpad 命令行](Guides/launchpad-cli.md) | 用 `vphone-launchpad-cli` 安装和测试本地构建 || [研究记录](../Research/README.md) | 补丁与实现细节 |diff --git a/README.md b/README.mdindex 39a88ff5..9004aff4 100644--- a/README.md+++ b/README.md@@ -106,6 +106,7 @@ Start with [Troubleshooting](Documents/Guides/troubleshooting.md), which covers| [Create and Run](Documents/Guides/create-and-run.md) | Firmware sources, the creation process, storage and backups || [Compatibility](Documents/Guides/compatibility.md) | Verified firmware pairings || [Troubleshooting](Documents/Guides/troubleshooting.md) | Common errors and how to fix them |+| [Networking](Documents/Guides/networking.md) | Network modes, and `tunnel` for a Mac behind a VPN or proxy || [Launchpad Command Line](Documents/Guides/launchpad-cli.md) | Install and test a local build with `vphone-launchpad-cli` || [Research Notes](Research/README.md) | Patch and implementation details |