- Generic
- Configuration
- QEMU
- VZ
- Networking
- Filesystem sharing
- External projects
- “Hints for debugging other problems?”
Generic
“How does Lima work?”
- Hypervisor: QEMU with HVF accelerator (default), or Virtualization.framework
- Filesystem sharing: Reverse SSHFS (default), or virtio-9p-pci aka virtfs, or virtiofs
- Port forwarding:
ssh -L
, automated by watching/proc/net/tcp
andiptables
events in the guest
“What’s my login password?”
Password is disabled and locked by default.
You have to use limactl shell bash
(or lima bash
) to open a shell.
Alternatively, you may also directly ssh into the guest: ssh -p 60022 -i ~/.lima/_config/user -o NoHostAuthenticationForLocalhost=yes 127.0.0.1
.
“Does Lima work on ARM Mac?”
Yes, it should work, but not regularly tested on ARM (due to lack of CI).
“Can I run non-Ubuntu guests?”
AlmaLinux, Alpine, Arch Linux, Debian, Fedora, openSUSE, Oracle Linux, and Rocky are also known to work.
See ./examples/
.
An image has to satisfy the following requirements:
- systemd or OpenRC
- cloud-init
- The following binaries to be preinstalled:
sudo
- The following binaries to be preinstalled, or installable via the package manager:
sshfs
newuidmap
andnewgidmap
apt-get
,dnf
,apk
,pacman
, orzypper
(if you want to contribute support for another package manager, rungit grep apt-get
to find out where to modify)
“Can I run other container engines such as Docker and Podman? What about Kubernetes?”
Yes, any container engine should work with Lima.
Container runtime examples:
./examples/docker.yaml
: Docker./examples/podman.yaml
: Podman./examples/apptainer.yaml
: Apptainer
Container image builder examples:
./examples/buildkit.yaml
: BuildKit
Container orchestrator examples:
./examples/k3s.yaml
: Kubernetes (k3s)./examples/k8s.yaml
: Kubernetes (kubeadm)
The default Ubuntu image also contains LXD. Run lima sudo lxc init
to set up LXD.
See also third party containerd projects based on Lima:
- Rancher Desktop: Kubernetes and container management to the desktop
- Colima: Docker (and Kubernetes) on macOS with minimal setup
Or third party "containers" projects compatible with Lima:
- Podman Desktop: Containers and Kubernetes for application developers
“Can I run Lima with a remote Linux machine?”
Lima itself does not support connecting to a remote Linux machine, but sshocker, the predecessor or Lima, provides similar features for remote Linux machines.
e.g., run sshocker -v /Users/foo:/home/foo/mnt -p 8080:80 <USER>@<HOST>
to expose /Users/foo
to the remote machine as /home/foo/mnt
,
and forward localhost:8080
to the port 80 of the remote machine.
“Advantages compared to Docker for Mac?”
Lima is free software (Apache License 2.0), while Docker for Mac is not.
Configuration
“Is it possible to disable mounts, port forwarding, containerd, etc. ?”
Yes, since Lima v0.18:
limactl start --plain
plain: true
When the “plain” mode is enabled:
- the YAML properties for mounts, port forwarding, containerd, etc. will be ignored
- guest agent will not be running
- dependency packages like sshfs will not be installed into the VM
User-specified provisioning scripts will be still executed.
QEMU
“QEMU crashes with HV_ERROR
”
If you have installed QEMU v6.0.0 or later on macOS 11 via homebrew, your QEMU binary should have been already automatically signed to enable HVF acceleration.
However, if you see HV_ERROR
, you might need to sign the binary manually.
cat >entitlements.xml <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.security.hypervisor</key>
<true/>
</dict>
</plist>
EOF
codesign -s - --entitlements entitlements.xml --force /usr/local/bin/qemu-system-x86_64
Note: Only on macOS versions before 10.15.7 you might need to add this entitlement in addition:
<key>com.apple.vm.hypervisor</key>
<true/>
“QEMU is slow”
- Make sure that HVF is enabled with
com.apple.security.hypervisor
entitlement. See "QEMU crashes withHV_ERROR
". - Emulating non-native machines (ARM-on-Intel, Intel-on-ARM) is slow by design. See
docs/multi-arch.md
for a workaround.
error “killed -9”
- make sure qemu is codesigned, See “QEMU crashes with
HV_ERROR
”. - if you are on macOS 10.15.7 or 11.0 or later make sure the entitlement
com.apple.vm.hypervisor
is not added. It only works on older macOS versions. You can clear the codesigning withcodesign --remove-signature /usr/local/bin/qemu-system-x86_64
and start over.
“QEMU crashes with vmx_write_mem: mmu_gva_to_gpa XXXXXXXXXXXXXXXX failed
”
This error is known to happen when running an image of RHEL8-compatible distribution such as Rocky Linux 8.x on Intel Mac.
A workaround is to set environment variable QEMU_SYSTEM_X86_64="qemu-system-x86_64 -cpu Haswell-v4"
.
https://bugs.launchpad.net/qemu/+bug/1838390
VZ
“Lima gets stuck at Installing rosetta...
”
Try softwareupdate --install-rosetta
from a terminal.
Networking
“Cannot access the guest IP 192.168.5.15 from the host”
The default guest IP 192.168.5.15 is not accessible from the host and other guests.
To add another IP address that is accessible from the host and other virtual machines, enable socket_vmnet
(since Lima v0.12).
See ./docs/network.md
.
“Ping shows duplicate packets and massive response times”
Lima uses QEMU’s SLIRP networking which does not support ping
out of the box:
$ ping google.com
PING google.com (172.217.165.14): 56 data bytes
64 bytes from 172.217.165.14: seq=0 ttl=42 time=2395159.646 ms
64 bytes from 172.217.165.14: seq=0 ttl=42 time=2396160.798 ms (DUP!)
For more details, see Documentation/Networking.
“IP address is not assigned for vmnet networks”
Try the following commands:
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/libexec/bootpd
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblock /usr/libexec/bootpd
Filesystem sharing
“Filesystem is slow”
Try virtiofs. See docs/mount.md
“Filesystem is not writable”
The home directory is mounted as read-only by default.
To enable writing, specify writable: true
in the YAML:
mounts:
- location: "~"
writable: true
Run limactl edit <INSTANCE>
to open the YAML editor for an existing instance.
“Filesystem is unmounted after upgrading Lima to v1.0 (pre-release)”
Lima v1.0 (pre-release) changed the default mount type for QEMU from reverse-sshfs
to 9p
.
The 9p
mount type is known to be incompatible with the following guest operating systems:
- AlmaLinux, CentOS Stream, Oracle Linux, and RockyLinux
- Debian GNU/Linux
- openSUSE
A new instance of these OS still use reverse-sshfs
by default.
However, an existing instance created with a previous version of Lima may potentially need
running the following command (usually not needed):
limactl edit --mount-type=reverse-sshfs <NAME>
Ubuntu users are not affected by this issue.
External projects
“I am using Rancher Desktop. How to deal with the underlying Lima?”
Rancher Desktop includes the rdctl
tool (installed in ~/.rd/bin/rdctl
) that provides shell access via rdctl shell
.
It is not recommended to directly interact with the Rancher Desktop VM via limactl
.
If you need to create an override.yaml
file, its location should be:
- macOS:
$HOME/Library/Application Support/rancher-desktop/lima/_config/override.yaml
- Linux:
$HOME/.local/share/rancher-desktop/lima/_config/override.yaml
“Hints for debugging other problems?”
- Inspect logs:
limactl --debug start
$HOME/.lima/<INSTANCE>/serial.log
/var/log/cloud-init-output.log
(inside the guest)/var/log/cloud-init.log
(inside the guest)
- Make sure that you aren’t mixing up tabs and spaces in the YAML.