Managed networks

• 1: Managed networks (macOS)
• 2: Managed networks (Linux)

1 - Managed networks (macOS)

VMNet assigns a “real” IP address that is reachable from the host.

On Linux hosts, the same shared, host and bridged networks are provided by lima-privileged-net instead.

For VZ instances, the vzNAT network is easier to set up, as it needs neither socket_vmnet nor the sudoers file.

To connect to a socket_vmnet daemon that is not controlled by Lima, see Unmanaged networks.

socket_vmnet

Managed (192.168.105.0/24)

socket_vmnet can be used for adding another guest IP that is accessible from the host and other guests, without depending on vz. It must be installed according to the instruction provided on https://github.com/lima-vm/socket_vmnet.

Note that installation using Homebrew is not secure and not recommended by the Lima project. Homebrew installation will only work with Lima if password-less sudo is enabled for the current user. The limactl sudoers command requires that socket_vmnet is installed into a secure path only writable by root and will reject socket_vmnet installed by Homebrew into a user-writable location.

# Install socket_vmnet as root from source to /opt/socket_vmnet
# using instructions on https://github.com/lima-vm/socket_vmnet
# This assumes that Xcode Command Line Tools are already installed
git clone https://github.com/lima-vm/socket_vmnet
cd socket_vmnet
# Change "v1.2.2" to the actual latest release in https://github.com/lima-vm/socket_vmnet/releases
git checkout v1.2.2
make
sudo make PREFIX=/opt/socket_vmnet install.bin

# Set up the sudoers file for launching socket_vmnet from Lima
limactl sudoers >etc_sudoers.d_lima
less etc_sudoers.d_lima  # verify that the file looks correct
sudo install -o root etc_sudoers.d_lima /etc/sudoers.d/lima
rm etc_sudoers.d_lima

Note

Lima before v0.12 used vde_vmnet for managing the networks. vde_vmnet is no longer supported.

Lima v0.14.0 and later used to also accept socket_vmnet installations if they were owned by the admin user. Starting with v1.0.0 only root ownership is acceptable.

The networks are defined in $LIMA_HOME/_config/networks.yaml. If this file doesn’t already exist, it will be created with these default settings:

# Path to socket_vmnet executable. Because socket_vmnet is invoked via sudo it should be
# installed where only root can modify/replace it. This means also none of the
# parent directories should be writable by the user.
#
# The varRun directory also must not be writable by the user because it will
# include the socket_vmnet pid file. Those will be terminated via sudo, so replacing
# the pid file would allow killing of arbitrary privileged processes. varRun
# however MUST be writable by the daemon user.
#
# None of the paths segments may be symlinks, why it has to be /private/var
# instead of /var etc.
paths:
# socketVMNet requires Lima >= 0.12 .
  socketVMNet: /opt/socket_vmnet/bin/socket_vmnet
  varRun: /private/var/run/lima
  sudoers: /private/etc/sudoers.d/lima

# The group that is allowed to run socket_vmnet via sudo and to access the
# socket_vmnet socket (macOS only; ignored on other platforms). Non-admin users
# must set this to a group they belong to (e.g. "staff").
group: admin

networks:
  shared:
    mode: shared
    gateway: 192.168.105.1
    dhcpEnd: 192.168.105.254
    netmask: 255.255.255.0
  bridged:
    mode: bridged
    interface: en0
    # bridged mode doesn't have a gateway; dhcp is managed by outside network
  host:
    mode: host
    gateway: 192.168.106.1
    dhcpEnd: 192.168.106.254
    netmask: 255.255.255.0

Instances can then reference these networks:

• CLI
• YAML

limactl start --network=lima:shared

networks:
  # Lima can manage the socket_vmnet daemon for networks defined in $LIMA_HOME/_config/networks.yaml automatically.
  # The socket_vmnet binary must be installed into a secure location only alterable by the "root" user.
  # - lima: shared
  #   # MAC address of the instance; lima will pick one based on the instance name,
  #   # so DHCP assigned ip addresses should remain constant over instance restarts.
  #   macAddress: ""
  #   # Interface name, defaults to "lima0", "lima1", etc.
  #   interface: ""

The network daemon is started automatically when the first instance referencing them is started, and will stop automatically once the last instance has stopped. Daemon logs will be stored in the $LIMA_HOME/_networks directory.

Since the commands to start and stop the socket_vmnet daemon requires root, the user either must have password-less sudo enabled, or add the required commands to a sudoers file. This can be done via:

limactl sudoers >etc_sudoers.d_lima
less etc_sudoers.d_lima  # verify that the file looks correct
sudo install -o root etc_sudoers.d_lima /etc/sudoers.d/lima
rm etc_sudoers.d_lima

The sudoers file grants the members of the group configured in networks.yaml permission to run socket_vmnet as root. Since Lima v2.2, group defaults to admin instead of everyone, so the permission is no longer granted to non-admin and non-local accounts. A non-admin user must set group to a group they belong to (e.g. staff).

The IP address is automatically assigned by macOS’s bootpd. If the IP address is not assigned, try the following commands:

sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/libexec/bootpd
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblock /usr/libexec/bootpd

2 - Managed networks (Linux)

Warning

This feature is experimental and subject to change.

On Linux hosts, the shared, host and bridged networks defined in $LIMA_HOME/_config/networks.yaml assign a “real” IP address that is reachable from the host, in the same way socket_vmnet does on macOS.

They are managed by lima-privileged-net, a privileged helper that ships with Lima and is installed to <PREFIX>/libexec/lima/privileged/lima-privileged-net. It creates a Linux bridge per network and attaches one tap device per instance.

Requirements

lima-privileged-net calls the dnsmasq for DHCP and DNS, which must be installed. Only QEMU instances are supported. The VZ and krunkit drivers are macOS-only.

Setting up the sudoers file

Creating a bridge and a tap device requires root, so the user either must have password-less sudo enabled, or add the required commands to a sudoers file:

limactl sudoers >etc_sudoers.d_lima
less etc_sudoers.d_lima  # verify that the file looks correct
sudo install -o root -m 0440 etc_sudoers.d_lima /etc/sudoers.d/lima
rm etc_sudoers.d_lima

The generated file whitelists the exact command lines Lima needs, and nothing else:

# Manage "shared" network daemons

%wheel ALL=(root:root) NOPASSWD:NOSETENV: \
    sha256:f705f79886fc248802e0bc388a66e2a61d09c827471d9639a5e558cf71080c72 /usr/local/libexec/lima/privileged/lima-privileged-net start --pidfile=/run/lima/shared_lima-privileged-net.pid --mode=shared --bridge=lima-shared --gateway=192.168.105.1 --dhcp-end=192.168.105.254 --netmask=255.255.255.0, \
    sha256:f705f79886fc248802e0bc388a66e2a61d09c827471d9639a5e558cf71080c72 /usr/local/libexec/lima/privileged/lima-privileged-net tap --bridge=lima-shared --network=shared -- *, \
    sha256:f705f79886fc248802e0bc388a66e2a61d09c827471d9639a5e558cf71080c72 /usr/local/libexec/lima/privileged/lima-privileged-net stop --pidfile=/run/lima/shared_lima-privileged-net.pid

The instance ID, a hash of the instance directory, is the only wildcard in the tap line. The -- ends the helper’s flag parsing, so an ID that smuggles in extra words - including a second --bridge - is rejected as a surplus positional argument. The device name itself is never passed in: the helper derives it from the network, the instance, and the uid that sudo reports, so a tap device can only ever belong to the user who asked for it.

The sha256: prefix is a sudo Digest_Spec (sudo >= 1.8.7): sudo hashes the helper right before executing it and falls back to asking for a password when the binary no longer matches, so a helper that was swapped out after the file was installed cannot be run as root. Unlike the ownership checks limactl performs, this is enforced inside sudo itself and is therefore not subject to a time-of-check/time-of-use race.

Re-run limactl sudoers and re-install the file whenever networks.yaml changes or lima-privileged-net is reinstalled, otherwise sudo will reject the command line. As the installed file is not readable by the user, check it with sudo cat /etc/sudoers.d/lima | limactl sudoers --check /dev/stdin, which reports when it is out of sync.

The group setting in networks.yaml selects the group that is granted these permissions; it defaults to sudo or wheel, whichever exists on the host.

limactl sudoers refuses to generate a file unless the helper is owned by root and none of its parent directories are writable by the user, so Lima must be installed with sudo make install rather than run from _output.

The path of the helper is not configurable: it is always <PREFIX>/libexec/lima/privileged/lima-privileged-net, resolved relative to the limactl binary that is running.

Configuration

networks.yaml is generated once and never rewritten. Earlier Lima releases wrote the macOS defaults into it on Linux too; Lima rejects such a file because of its paths.socketVMNet, so delete ~/.lima/_config/networks.yaml to regenerate it.

The defaults generated on a Linux host are:

paths:
  socketVMNet: ""
  varRun: /run/lima
  sudoers: /etc/sudoers.d/lima

group: wheel

networks:
  user-v2:
    mode: user-v2
    gateway: 192.168.104.1
    netmask: 255.255.255.0
  shared:
    mode: shared
    gateway: 192.168.105.1
    dhcpEnd: 192.168.105.254
    netmask: 255.255.255.0
  bridged:
    mode: bridged
    interface: br0
    # bridged mode doesn't have a gateway; dhcp is managed by outside network
  host:
    mode: host
    gateway: 192.168.106.1
    dhcpEnd: 192.168.106.254
    netmask: 255.255.255.0

Instances can then reference these networks:

• CLI
• YAML

limactl start --network=lima:shared

networks:
- lima: shared
  # MAC address of the instance; lima will pick one based on the instance name,
  # so DHCP assigned ip addresses should remain constant over instance restarts.
  macAddress: ""
  # Interface name, defaults to "lima0", "lima1", etc.
  interface: ""

The network daemon is started automatically when the first instance referencing it is started, and stops automatically once the last instance has stopped. Daemon logs are stored in the $LIMA_HOME/_networks directory.

Modes

shared (192.168.105.0/24)

Creates the lima-shared bridge. Guests reach the host, each other, and the outside world through NAT (MASQUERADE, scoped to the network’s own subnet). Enabling this turns on net.ipv4.ip_forward on the host. If Lima was the one that enabled it, Lima turns it off again on teardown, unless another Lima network is still up at that point; in that case it stays on.

host (192.168.106.0/24)

Creates the lima-host bridge. Guests reach the host and each other, but FORWARD rules block everything else, including other Lima networks.

Note that an instance also has the default user-mode (slirp) network, which still provides outbound connectivity. The host network only guarantees that no traffic is routed through the host off the lima-host bridge.

bridged

Attaches the instance directly to an existing host bridge, so that it gets an address from the outside network’s DHCP server and is reachable from the LAN.

Unlike on macOS, interface must name a bridge that already exists, created by the host administrator with NetworkManager, systemd-networkd or netplan. Lima never creates it and never enslaves a physical interface, because doing so can disconnect the host.

For example, with NetworkManager, the following creates a br0 bridge and moves the host’s address from the physical interface eth0 onto it (replace eth0 with the name shown by nmcli device). Run it from a local console, as the host loses its connection while the address moves to the bridge:

sudo nmcli connection add type bridge ifname br0 con-name br0 bridge.stp no
sudo nmcli connection add type bridge-slave ifname eth0 master br0 con-name br0-port-eth0
sudo nmcli connection up br0-port-eth0

The bridge then obtains its address from the LAN’s DHCP server. Set interface of the bridged network in networks.yaml to the bridge name if it is not br0. Wi-Fi interfaces usually cannot be enslaved to a bridge.

Warning

A bridged instance is exposed to every host on the LAN, and its tap device stays on the bridge until the network is torn down.

Firewall

Guests must be able to reach the host’s DHCP and DNS ports, which host firewalls block by default.

• With firewalld, the bridge is bound to the first existing zone out of lima, nm-shared (installed by NetworkManager), and libvirt (installed by libvirt). All three forward the guests’ traffic and block most services on the host itself, but they do not expose the same ones:

  • lima, which Lima creates permanently when none of the three exists, exposes only DHCP, DNS and ICMP.
  • nm-shared also exposes SSH.
  • libvirt also exposes SSH, TFTP and DHCPv6.

  Define a lima zone to override that policy.

• With ufw, rules allowing UDP 67 and UDP/TCP 53 on the bridge are added.

• Otherwise, equivalent iptables rules are added.

The bridge is removed from the zone, and the ufw and iptables rules are deleted, when the network is torn down. A lima zone that Lima created stays.

Security

lima-privileged-net runs as root for as long as the network is up. It creates the bridge and the tap devices, configures the firewall and forwarding with firewall-cmd, ufw, iptables and sysctl, and runs dnsmasq as a root child process. The tap device is handed to the calling user (ip tuntap add ... user "$UID"), so QEMU itself runs unprivileged and needs no network capabilities.

The varRun directory (/run/lima) must stay owned by root and must not be writable by the user, because it holds the PID files that lima-privileged-net stop reads as root to pick the process to signal.