Skip to content

Commit 5d11d4b

Browse files
AkihiroSudaAkihiroSuda
authored
Merge pull request #20 from AkihiroSuda/dev
README.md: update for Homebrew
2 parents efae138 + 9b6ae59 commit 5d11d4b

File tree

1 file changed

+158
-28
lines changed

1 file changed

+158
-28
lines changed

‎README.md

Lines changed: 158 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -9,33 +9,162 @@
99
`socket_vmnet` was forked from [`vde_vmnet`](https://github.com/lima-vm/vde_vmnet) v0.6.0.
1010
Unlike `vde_vmnet`, `socket_vmnet` does not depend on VDE.
1111

12+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
13+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
14+
15+
16+
- [Install](#install)
17+
- [From Homebrew](#from-homebrew)
18+
- [From source](#from-source)
19+
- [Usage](#usage)
20+
- [QEMU](#qemu)
21+
- [Lima](#lima)
22+
- [Advanced usage](#advanced-usage)
23+
- [Multi VM](#multi-vm)
24+
- [Bridged mode](#bridged-mode)
25+
- [FAQs](#faqs)
26+
- [Why does `socket_vmnet` require root?](#why-does-socket_vmnet-require-root)
27+
- [Is it possible to run `socket_vmnet` with SETUID?](#is-it-possible-to-run-socket_vmnet-with-setuid)
28+
- [How is socket_vmnet related to vde_vmnet?](#how-is-socket_vmnet-related-to-vde_vmnet)
29+
- [How is socket_vmnet related to QEMU-builtin vmnet support?](#how-is-socket_vmnet-related-to-qemu-builtin-vmnet-support)
30+
- [How to use static IP addresses?](#how-to-use-static-ip-addresses)
31+
- [How to reserve DHCP addresses?](#how-to-reserve-dhcp-addresses)
32+
- [Links](#links)
33+
- [Troubleshooting](#troubleshooting)
34+
35+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
36+
1237
## Install
1338

1439
Requires macOS 10.15 or later.
1540

16-
Install from source:
41+
### From Homebrew
42+
43+
```bash
44+
brew install socket_vmnet
45+
```
46+
47+
The binaries will be installed onto the following paths:
48+
- `${HOMEBREW_PREFIX}/opt/socket_vmnet/bin/socket_vmnet`
49+
- `${HOMEBREW_PREFIX}/opt/socket_vmnet/bin/socket_vmnet_client`
50+
51+
The `${HOMEBREW_PREFIX}` path defaults to `/opt/homebrew` on ARM, `/usr/local` on Intel.
52+
53+
The `${HOMEBREW_PREFIX}/opt/socket_vmnet` directory is usually symlinked to `../Cellar/socket_vmnet/${VERSION}`.
54+
55+
Run the following command to start the daemon:
56+
```bash
57+
sudo ${HOMEBREW_PREFIX}/opt/socket_vmnet/bin/socket_vmnet --vmnet-gateway=192.168.105.1 ${HOMEBREW_PREFIX}/var/run/socket_vmnet
58+
```
59+
60+
> **Warning**
61+
>
62+
> Typically, the `socket_vmnet` binary in the `${HOMEBREW_PREFIX}` can be replaced by any user in the `admin` group.
63+
64+
<details>
65+
66+
<summary>Launchd (optional, not needed for Lima)</summary>
67+
68+
<p>
69+
70+
71+
To install the launchd service:
1772
```bash
18-
sudo make PREFIX=/opt/socket_vmnet install
73+
brew tap homebrew/services
74+
# sudo is necessary for the next line
75+
sudo ${HOMEBREW_PREFIX}/bin/brew services start socket_vmnet
76+
```
77+
78+
The launchd unit file will be installed as `/Library/LaunchDaemons/homebrew.mxcl.socket_vmnet.plist`.
79+
80+
Default configuration:
81+
82+
Config | Value
83+
--------|--------------------------------------------------
84+
Socket | `${HOMEBREW_PREFIX}/var/run/socket_vmnet`
85+
Stdout | `${HOMEBREW_PREFIX}/var/run/socket_vmnet.stdout`
86+
Stderr | `${HOMEBREW_PREFIX}/var/run/socket_vmnet.stderr`
87+
Gateway | 192.168.105.1
88+
89+
To uninstall the launchd service:
90+
```bash
91+
sudo ${HOMEBREW_PREFIX}/bin/brew services stop socket_vmnet
92+
```
93+
94+
</p>
95+
96+
</details>
97+
98+
### From source
99+
100+
<details>
101+
102+
<p>
103+
104+
```bash
105+
sudo make PREFIX=/opt/socket_vmnet install.bin
19106
```
20107

21108
The `PREFIX` dir below does not necessarily need to be `/opt/socket_vmnet`, however, it is highly recommended
22109
to set the prefix to a directory that can be only written by the root.
23110

24-
Note that `/usr/local` is typically chowned for a non-root user on Homebrew environments, so
25-
`/usr/local` is *not* an appropriate prefix.
111+
Note that `/usr/local/bin` is sometimes chowned for a non-admin user, so `/usr/local` is *not* an appropriate prefix.
26112

27-
The following files will be installed:
113+
The binaries will be installed onto the following paths:
28114
- `/opt/socket_vmnet/bin/socket_vmnet`
29115
- `/opt/socket_vmnet/bin/socket_vmnet_client`
30-
- `/Library/LaunchDaemons/io.github.lima-vm.socket_vmnet.plist`
31-
- Configured to use `192.168.105.0/24`. Modifiy the file if it conflicts with your local network.
32116

33-
See ["Testing without launchd"](#testing-without-launchd) if you don't prefer to use launchd.
117+
Run the following command to start the daemon:
118+
```bash
119+
sudo /opt/socket_vmnet/bin/socket_vmnet --vmnet-gateway=192.168.105.1 /var/run/socket_vmnet
120+
```
121+
122+
<details>
123+
124+
<summary>Launchd (optional, not needed for Lima)</summary>
125+
126+
<p>
127+
128+
129+
To install the launchd service:
130+
```bash
131+
sudo make PREFIX=/opt/socket_vmnet install.launchd
132+
```
133+
134+
The launchd unit file will be installed as `/Library/LaunchDaemons/io.github.lima-vm.socket_vmnet.plist`.
135+
136+
Default configuration:
137+
138+
Config | Value
139+
--------|--------------------------------------------------
140+
Socket | `/var/run/socket_vmnet`
141+
Stdout | `/var/run/socket_vmnet.stdout`
142+
Stderr | `/var/run/socket_vmnet.stderr`
143+
Gateway | 192.168.105.1
144+
145+
146+
To uninstall the launchd service:
147+
```bash
148+
sudo make PREFIX=/opt/socket_vmnet uninstall.launchd
149+
```
150+
151+
</p>
152+
153+
</details>
154+
155+
</p>
156+
157+
</details>
34158

35159
## Usage
36160

161+
### QEMU
162+
Make sure that the `socket_vmnet` daemon is running, and execute QEMU via `socket_vmnet_client` as follows:
163+
37164
```console
38-
/opt/socket_vmnet/bin/socket_vmnet_client /var/run/socket_vmnet qemu-system-x86_64 \
165+
${HOMEBREW_PREFIX}/opt/socket_vmnet/bin/socket_vmnet_client \
166+
${HOMEBREW_PREFIX}/var/run/socket_vmnet \
167+
qemu-system-x86_64 \
39168
-device virtio-net-pci,netdev=net0 -netdev socket,id=net0,fd=3 \
40169
-m 4096 -accel hvf -cdrom ubuntu-22.04-desktop-amd64.iso
41170
```
@@ -46,7 +175,7 @@ The guest is accessible to the internet, and the guest IP is accessible from the
46175

47176
To confirm, run `sudo apt-get update && sudo apt-get install -y apache2` in the guest, and access the guest IP via Safari on the host.
48177

49-
### Lima integration
178+
### Lima
50179

51180
Lima (since v0.12.0) provides built-in support for `socket_vmnet`:
52181

@@ -57,6 +186,7 @@ $ limactl start --name=default template://vmnet
57186

58187
See also https://github.com/lima-vm/lima/blob/master/docs/network.md
59188

189+
## Advanced usage
60190
### Multi VM
61191
Multiple VMs can be connected to a single `socket_vmnet` instance.
62192

@@ -67,26 +197,26 @@ You do not need to configure (and you can't, currently) the MAC address of `sock
67197

68198
### Bridged mode
69199

70-
Run `sudo make install BRIDGED=en0`.
71-
72-
The following additional file will be installed:
73-
- `/Library/LaunchDaemons/io.github.lima-vm.socket_vmnet.bridged.en0.plist`
74-
75-
Use `/var/run/socket_vmnet.bridged.en0` as the socket.
76-
77-
## Advanced usage
200+
See [`./launchd/io.github.lima-vm.socket_vmnet.bridged.en0.plist`](./launchd/io.github.lima-vm.socket_vmnet.bridged.en0.plist).
78201

79-
### Testing without launchd
80-
81-
```console
82-
sudo make install.bin
202+
Install:
203+
```bash
204+
BRIDGED=en0
205+
sed -e "s@/opt@${HOMEBREW_PREFIX}/opt@g; s@/var@${HOMEBREW_PREFIX}/var@g; s@en0@${BRIDGED}@g" ./launchd/io.github.lima-vm.socket_vmnet.bridged.en0.plist \
206+
sudo tee /Library/LaunchDaemons/io.github.lima-vm.socket_vmnet.bridged.${BRIDGED}.plist
207+
sudo launchctl bootstrap system /Library/LaunchDaemons/io.github.lima-vm.socket_vmnet.bridged.${BRIDGED}.plist
208+
sudo launchctl enable system/io.github.lima-vm.socket_vmnet.bridged.${BRIDGED}
209+
sudo launchctl kickstart -kp system/io.github.lima-vm.socket_vmnet.bridged.${BRIDGED}
83210
```
84211

85-
```console
86-
sudo socket_vmnet --vmnet-gateway=192.168.105.1 /tmp/socket_vmnet
87-
```
212+
Use `${HOMEBREW_PREFIX}/var/run/socket_vmnet.bridged.en0` as the socket.
88213

89-
Note: make sure to run `socket_vmnet` with root (`sudo`). See [FAQs](#FAQs) for the reason.
214+
Uninstall:
215+
```bash
216+
BRIDGED=en0
217+
sudo launchctl bootout system /Library/LaunchDaemons/io.github.lima-vm.socket_vmnet.bridged.${BRIDGED}.plist
218+
sudo rm /Library/LaunchDaemons/io.github.lima-vm.socket_vmnet.bridged.${BRIDGED}.plist
219+
```
90220

91221
## FAQs
92222

@@ -115,7 +245,7 @@ See [`./etc_sudoers.d/socket_vmnet`](./etc_sudoers.d/socket_vmnet) to allow runn
115245
Unlike `vde_vmnet`, `socket_vmnet` does not depend on VDE.
116246

117247
### How is socket_vmnet related to QEMU-builtin vmnet support?
118-
There is a proposal to add builtin vmnet support for QEMU: [`[v22] Add vmnet.framework based network backend`](https://patchwork.kernel.org/project/qemu-devel/cover/[email protected]/).
248+
QEMU 7.1 added [the built-in support for vmnet](https://github.com/qemu/qemu/blob/v7.1.0/qapi/net.json#L626-L631).
119249

120250
However, QEMU-builtin vmnet requires running the entire QEMU process as root.
121251

@@ -159,4 +289,4 @@ You do not need to configure (and you can't, currently) the MAC address of `sock
159289

160290
## Troubleshooting
161291
- Set environment variable `DEBUG=1`
162-
- See `/var/run/socket_vmnet.{stdout,stderr}` (when using launchd)
292+
- See `${HOMEBREW_PREFIX}/var/run/socket_vmnet.{stdout,stderr}` (when using launchd)

0 commit comments

Comments
 (0)