mirror of
https://github.com/Lakr233/vphone-cli.git
synced 2026-10-01 23:54:35 +08:00
Document the network modes and tunnel mode
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Lakr
@@ -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>')"
|
||||
```
|
||||
@@ -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) | パッチと実装の詳細 |
|
||||
|
||||
|
||||
@@ -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) | 패치와 구현 세부 사항 |
|
||||
|
||||
|
||||
@@ -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) | 补丁与实现细节 |
|
||||
|
||||
|
||||
@@ -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 |
|
||||
|
||||
|
||||
Reference in New Issue
Block a user