Skip to content

Commit a4920c1

Browse files
janduboisjandubois
committed
Add documentation about managed networks
Signed-off-by: Jan Dubois <[email protected]>
1 parent 455c070 commit a4920c1

File tree

3 files changed

+116
-33
lines changed

3 files changed

+116
-33
lines changed

‎docs/network.md

Lines changed: 82 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -28,21 +28,89 @@ the host and other guests.
2828
To enable `vde_vmnet` (in addition the user-mode network), add the following lines to the YAML after installing `vde_vmnet`.
2929

3030
```yaml
31-
network:
32-
# The instance can get routable IP addresses from the vmnet framework using
33-
# https://github.com/lima-vm/vde_vmnet. Both vde_switch and vde_vmnet
34-
# daemons must be running before the instance is started. The interface type
35-
# (host, shared, or bridged) is configured in vde_vmnet and not lima.
36-
vde:
37-
# vnl (virtual network locator) points to the vde_switch socket directory,
38-
# optionally with vde:// prefix
39-
- vnl: "vde:///var/run/vde.ctl"
40-
# MAC address of the instance; lima will pick one based on the instance name,
41-
# so DHCP assigned ip addresses should remain constant over instance restarts.
42-
macAddress: ""
43-
# Interface name, defaults to "vde0", "vde1", etc.
44-
name: ""
31+
networks:
32+
# vnl (virtual network locator) points to the vde_switch socket directory,
33+
# optionally with vde:// prefix
34+
# - vnl: "vde:///var/run/vde.ctl"
35+
# # VDE Switch port number (not TCP/UDP port number). Set to 65535 for PTP mode.
36+
# # Default: 0
37+
# switchPort: 0
38+
# # MAC address of the instance; lima will pick one based on the instance name,
39+
# # so DHCP assigned ip addresses should remain constant over instance restarts.
40+
# macAddress: ""
41+
# # Interface name, defaults to "lima0", "lima1", etc.
42+
# interface: ""
4543
```
4644

4745
The IP address range is typically `192.168.105.0/24`, but depends on the configuration of `vde_vmnet`.
4846
See [the documentation of `vde_vmnet`](https://github.com/lima-vm/vde_vmnet) for further information.
47+
48+
## Managed VMNet networks (via vde_vmnet)
49+
50+
Starting with version v0.7.0 lima can manage the networking daemons automatically. Networks are defined in
51+
`$LIMA_HOME/_config/networks.yaml`. If this file doesn't already exist, it will be created with these default
52+
settings:
53+
54+
```yaml
55+
# Paths to vde executables. Because vde_vmnet is invoked via sudo it should be
56+
# installed where only root can modify/replace it. This means also none of the
57+
# parent directories should be writable by the user.
58+
#
59+
# The varRun directory also must not be writable by the user because it will
60+
# include the vde_vmnet pid files. Those will be terminated via sudo, so replacing
61+
# the pid files would allow killing of arbitrary privileged processes. varRun
62+
# however MUST be writable by the daemon user.
63+
#
64+
# None of the paths segments may be symlinks, why it has to be /private/var
65+
# instead of /var etc.
66+
paths:
67+
vdeSwitch: /opt/vde/bin/vde_switch
68+
vdeVMNet: /opt/vde/bin/vde_vmnet
69+
varRun: /private/var/run/lima
70+
sudoers: /private/etc/sudoers.d/lima
71+
72+
group: staff
73+
74+
networks:
75+
shared:
76+
mode: shared
77+
gateway: 192.168.105.1
78+
dhcpEnd: 192.168.105.254
79+
netmask: 255.255.255.0
80+
bridged:
81+
mode: bridged
82+
interface: en0
83+
# bridged mode doesn't have a gateway; dhcp is managed by outside network
84+
host:
85+
mode: host
86+
gateway: 192.168.106.1
87+
dhcpEnd: 192.168.106.254
88+
netmask: 255.255.255.0
89+
```
90+
91+
Instances can then reference these networks from their `lima.yaml` file:
92+
93+
```yaml
94+
networks:
95+
# Lima can manage daemons for networks defined in $LIMA_HOME/_config/networks.yaml
96+
# automatically. Both vde_switch and vde_vmnet binaries must be installed into
97+
# secure locations only alterable by the "root" user.
98+
# - lima: shared
99+
# # MAC address of the instance; lima will pick one based on the instance name,
100+
# # so DHCP assigned ip addresses should remain constant over instance restarts.
101+
# macAddress: ""
102+
# # Interface name, defaults to "lima0", "lima1", etc.
103+
# interface: ""
104+
```
105+
106+
The network daemons are started automatically when the first instance referencing them is started,
107+
and will stop automatically once the last instance has stopped. Daemon logs will be stored in the
108+
`$LIMA_HOME/_networks` directory.
109+
110+
Since the commands to start and stop the `vde_vmnet` daemon requires root, the user either must
111+
have password-less `sudo` enabled, or add the required commands to a `sudoers` file. This can
112+
be done via:
113+
114+
```shell
115+
limactl sudoers | sudo tee /etc/sudoers.d/lima
116+
```

‎pkg/limayaml/default.yaml

Lines changed: 28 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -121,23 +121,34 @@ video:
121121
# Default: "none"
122122
display: "none"
123123

124-
network:
125-
# The instance can get routable IP addresses from the vmnet framework using
126-
# https://github.com/lima-vm/vde_vmnet. Both vde_switch and vde_vmnet
127-
# daemons must be running before the instance is started. The interface type
128-
# (host, shared, or bridged) is configured in vde_vmnet and not lima.
129-
vde:
130-
# vnl (virtual network locator) points to the vde_switch socket directory,
131-
# optionally with vde:// prefix
132-
# - vnl: "vde:///var/run/vde.ctl"
133-
# # VDE Switch port number (not TCP/UDP port number). Set to 65535 for PTP mode.
134-
# # Default: 0
135-
# switchPort: 0
136-
# # MAC address of the instance; lima will pick one based on the instance name,
137-
# # so DHCP assigned ip addresses should remain constant over instance restarts.
138-
# macAddress: ""
139-
# # Interface name, defaults to "vde0", "vde1", etc.
140-
# name: ""
124+
# The instance can get routable IP addresses from the vmnet framework using
125+
# https://github.com/lima-vm/vde_vmnet.
126+
networks:
127+
# Lima can manage daemons for networks defined in $LIMA_HOME/_config/networks.yaml
128+
# automatically. Both vde_switch and vde_vmnet binaries must be installed into
129+
# secure locations only alterable by the "root" user.
130+
# - lima: shared
131+
# # MAC address of the instance; lima will pick one based on the instance name,
132+
# # so DHCP assigned ip addresses should remain constant over instance restarts.
133+
# macAddress: ""
134+
# # Interface name, defaults to "lima0", "lima1", etc.
135+
# interface: ""
136+
#
137+
# Lima can also connect to "unmanaged" vde networks addressed by "vnl". This
138+
# means that the daemons will not be controlled by Lima, but must be started
139+
# before the instance. The interface type (host, shared, or bridged) is
140+
# configured in vde_vmnet and not in lima.
141+
# vnl (virtual network locator) points to the vde_switch socket directory,
142+
# optionally with vde:// prefix
143+
# - vnl: "vde:///var/run/vde.ctl"
144+
# # VDE Switch port number (not TCP/UDP port number). Set to 65535 for PTP mode.
145+
# # Default: 0
146+
# switchPort: 0
147+
# # MAC address of the instance; lima will pick one based on the instance name,
148+
# # so DHCP assigned ip addresses should remain constant over instance restarts.
149+
# macAddress: ""
150+
# # Interface name, defaults to "lima0", "lima1", etc.
151+
# interface: ""
141152

142153
# Port forwarding rules. Forwarding between ports 22 and ssh.localPort cannot be overridden.
143154
# Rules are checked sequentially until the first one matches.

‎pkg/networks/networks.yaml

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,13 @@
22
# installed where only root can modify/replace it. This means also none of the
33
# parent directories should be writable by the user.
44
#
5-
# The var_run directory also must not be writable by the user because it will
5+
# The varRun directory also must not be writable by the user because it will
66
# include the vde_vmnet pid files. Those will be terminated via sudo, so replacing
7-
# the pid files would allow killing of arbitrary privileged processes.
7+
# the pid files would allow killing of arbitrary privileged processes. varRun
8+
# however MUST be writable by the daemon user.
9+
#
10+
# None of the paths segments may be symlinks, why it has to be /private/var
11+
# instead of /var etc.
812
paths:
913
vdeSwitch: /opt/vde/bin/vde_switch
1014
vdeVMNet: /opt/vde/bin/vde_vmnet

0 commit comments

Comments
 (0)