Skip to content

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.md
new file mode 100644
index 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.md
index 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.md
index 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.md
index 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.md
index 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 |