finch.yaml

# ===================================================================== #
# BASIC CONFIGURATION
# ===================================================================== #

# Default values in this YAML file are specified by `null` instead of Lima's "builtin default" values,
# so they can be overridden by the $LIMA_HOME/_config/default.yaml mechanism documented at the end of this file.

#vmType: null

# Arch: "default", "x86_64", "aarch64".
# 🟢 Builtin default: "default" (corresponds to the host architecture)
arch: null

# OpenStack-compatible disk image.
# 🟢 Builtin default: null (must be specified)
# 🔵 This file: Ubuntu 22.04 Jammy Jellyfish images
images:
  - location: "<finch_image_location>"
    arch: "<finch_image_arch>"
    digest: "<finch_image_digest>"

# CPUs: if you see performance issues, try limiting cpus to 1.
# 🟢 Builtin default: 4
cpus: null

# Memory size
# 🟢 Builtin default: "4GiB"
memory: "4GiB"

# Disk size
# 🟢 Builtin default: "100GiB"
disk: null

# Expose host directories to the guest, the mount point might be accessible from all UIDs in the guest
# 🟢 Builtin default: null (Mount nothing)
# 🔵 This file: Mount the home as read-only, /tmp/lima as writable
mounts:
- location: "~"
  # Configure the mountPoint inside the guest.
  # 🟢 Builtin default: value of location
  mountPoint: null
  # CAUTION: `writable` SHOULD be false for the home directory.
  # Setting `writable` to true is safe for finch use case.
  # Reference: https://github.com/lima-vm/lima/discussions/550
  writable: true
  sshfs:
    # Enabling the SSHFS cache will increase performance of the mounted filesystem, at
    # the cost of potentially not reflecting changes made on the host in a timely manner.
    # Warning: It looks like PHP filesystem access does not work correctly when
    # the cache is disabled.
    # 🟢 Builtin default: true
    cache: null
    # SSHFS has an optional flag called 'follow_symlinks'. This allows mounts
    # to be properly resolved in the guest os and allow for access to the
    # contents of the symlink. As a result, symlinked files & folders on the Host
    # system will look and feel like regular files directories in the Guest OS.
    # 🟢 Builtin default: false
    followSymlinks: null
    # SFTP driver, "builtin" or "openssh-sftp-server". "openssh-sftp-server" is recommended.
    # 🟢 Builtin default: "openssh-sftp-server" if OpenSSH SFTP Server binary is found, otherwise "builtin"
    sftpDriver: null
  9p:
    # Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
    # 🟢 Builtin default: "mapped-xattr"
    securityModel: null
    # Select 9P protocol version. Valid options are: "9p2000" (legacy), "9p2000.u", "9p2000.L".
    # 🟢 Builtin default: "9p2000.L"
    protocolVersion: null
    # The number of bytes to use for 9p packet payload, where 4KiB is the absolute minimum.
    # 🟢 Builtin default: "128KiB"
    msize: null
    # Specifies a caching policy. Valid options are: "none", "loose", "fscache" and "mmap".
    # Try choosing "mmap" or "none" if you see a stability issue with the default "fscache".
    # See https://www.kernel.org/doc/Documentation/filesystems/9p.txt
    # 🟢 Builtin default: "fscache" for non-writable mounts, "mmap" for writable mounts
    cache: null
- location: "/tmp/lima"
  # 🟢 Builtin default: false
  # 🔵 This file: true (only for "/tmp/lima")
  writable: true
- location: "/var/folders"
  writable: true
# Because readlink /var => private/var
- location: "/private/var/folders"
  writable: true

# Lima disks to attach to the instance. The disks will be accessible from inside the
# instance, labeled by name. (e.g. if the disk is named "data", it will be labeled
# "lima-data" inside the instance). The disk will be mounted inside the instance at
# `/mnt/lima-${VOLUME}`.
# 🟢 Builtin default: null
# For Finch, this value should always be the same as the diskName in pkg/disk/disk.go

ssh:
  # A localhost port of the host. Forwarded to port 22 of the guest.
  # 🟢 Builtin default: 0 (automatically assigned to a free port)
  # NOTE: when the instance name is "default", the builtin default value is set to
  # 60022 for backward compatibility.
  localPort: 0
  # Load ~/.ssh/*.pub in addition to $LIMA_HOME/_config/user.pub .
  # This option is useful when you want to use other SSH-based
  # applications such as rsync with the Lima instance.
  # If you have an insecure key under ~/.ssh, do not use this option.
  # 🟢 Builtin default: true
  loadDotSSHPubKeys: false
  # Forward ssh agent into the instance.
  # 🟢 Builtin default: false
  forwardAgent: true
  # Forward X11 into the instance
  # 🟢 Builtin default: false
  forwardX11: null
  # Trust forwarded X11 clients
  # 🟢 Builtin default: false
  forwardX11Trusted: null

# ===================================================================== #
# ADVANCED CONFIGURATION
# ===================================================================== #

containerd:
  # Enable system-wide (aka rootful)  containerd and its dependencies (BuildKit, Stargz Snapshotter)
  # 🟢 Builtin default: false
  system: true
  # Enable user-scoped (aka rootless) containerd and its dependencies
  # 🟢 Builtin default: true
  user: false
  # Override containerd archive
  # 🟢 Builtin default: hard-coded URL with hard-coded digest (see the output of `limactl info | jq .defaultTemplate.containerd.archives`)
  #   archives:
  #   - location: "https://deps.runfinch.com/x86-64/nerdctl-full-1.7.2-1-linux-amd64.tar.gz"
  #     arch: "x86_64"
  #     digest: "sha256:90851068e58417551384dafb3fced8165cbfa2799b51849f85f44c0ebef2c37a"
  #   - location: "https://deps.runfinch.com/aarch64/nerdctl-full-1.7.2-1-linux-arm64.tar.gz"
  #     arch: "aarch64"
  #     digest: "sha256:f354541e6234235f2ea32d6ed64e9d59a7cc4e0b7f15e63deef9cd5e90a298ef"

# Provisioning scripts need to be idempotent because they might be called
# multiple times, e.g. when the host VM is being restarted.
# 🟢 Builtin default: null
provision:
- mode: boot
  script: |
    systemctl stop NetworkManager-wait-online.service
    systemctl reset-failed NetworkManager-wait-online.service
    systemctl mask NetworkManager-wait-online.service
- mode: boot
  script: |
    modprobe virtiofs
- mode: boot
  script: |
    modprobe br_netfilter
    cat <<EOF > /etc/sysctl.d/99-finch.conf
    net.bridge.bridge-nf-call-iptables = 1
    net.bridge.bridge-nf-call-ip6tables = 1
    net.ipv4.ip_forward = 1
    EOF
    sysctl --system
# # `user` is executed without the root privilege
- mode: user
  script: |
    #!/bin/bash

    # Enable SSHing into the VM as root (e.g., in `nerdctlConfigApplier.Apply`).
    sudo cp ~/.ssh/authorized_keys /root/.ssh/
    sudo chown $USER /mnt/lima-finch
    
    # This block of configuration facilitates the startup of rootless containers created prior to this change within the rootful vm configuration by mounting /mnt/lima-finch to both rootless and rootful dataroots.   
    
    # https://github.com/containerd/containerd/blob/main/docs/ops.md#base-configuration
    sudo mkdir -p /mnt/lima-finch/containerd /var/lib/containerd
    sudo mount --bind /mnt/lima-finch/containerd /var/lib/containerd
    
    # https://github.com/containerd/nerdctl/blob/cffdf87ff4d648a5344eea1406bb95ca3ad7eaa4/extras/rootless/containerd-rootless.sh#L144-L146
    # XDG_DATA_HOME & ~/.local/share: https://github.com/containerd/nerdctl/blob/cffdf87ff4d648a5344eea1406bb95ca3ad7eaa4/extras/rootless/containerd-rootless.sh#L51
    mkdir -p ~/.local/share/containerd
    sudo mount --bind /mnt/lima-finch/containerd ~/.local/share/containerd

    # https://github.com/containerd/nerdctl/blob/main/docs/dir.md#dataroot
    sudo mkdir -p /mnt/lima-finch/nerdctl /var/lib/nerdctl
    sudo mount --bind /mnt/lima-finch/nerdctl /var/lib/nerdctl
    mkdir -p ~/.local/share/nerdctl
    sudo mount --bind /mnt/lima-finch/nerdctl ~/.local/share/nerdctl

    # https://github.com/containerd/nerdctl/blob/main/docs/dir.md#netconfpath
    sudo mkdir -p /mnt/lima-finch/cni-config /etc/cni/
    sudo mount --bind /mnt/lima-finch/cni-config /etc/cni/
    mkdir -p ~/.config/cni
    sudo mount --bind /mnt/lima-finch/cni-config ~/.config/cni

    # https://github.com/containerd/nerdctl/blob/cffdf87ff4d648a5344eea1406bb95ca3ad7eaa4/extras/rootless/containerd-rootless.sh#L148-L150
    sudo mkdir -p /mnt/lima-finch/cni /var/lib/cni
    sudo mount --bind /mnt/lima-finch/cni /var/lib/cni
    mkdir -p  ~/.local/share/cni
    sudo mount --bind /mnt/lima-finch/cni  ~/.local/share/cni

    # https://github.com/containerd/stargz-snapshotter/blob/94b12086ace4119e86d2db0d6343d7c734b56671/cmd/containerd-stargz-grpc/main.go#L67C2-L67C2
    sudo mkdir -p /mnt/lima-finch/containerd-stargz-grpc/snapshotter/snapshots
    sudo mount --bind /mnt/lima-finch/containerd-stargz-grpc /var/lib/containerd-stargz-grpc
    
    # https://github.com/awslabs/soci-snapshotter/blob/335515f746f50c964ed48159257e1aeba04805b6/cmd/soci-snapshotter-grpc/main.go#L84
    sudo mkdir -p /mnt/lima-finch/soci-snapshotter-grpc/snapshotter/snapshots /var/lib/soci-snapshotter-grpc
    sudo mount --bind /mnt/lima-finch/soci-snapshotter-grpc /var/lib/soci-snapshotter-grpc

    # Make sure stargz and buildkit are restarted with containerd
    sudo mkdir -p /usr/local/lib/systemd/system/buildkit.service.d/
    printf '[Unit]\nPartOf=containerd.service\n' | sudo tee /usr/local/lib/systemd/system/buildkit.service.d/finch.conf
    sudo mkdir -p /usr/local/lib/systemd/system/stargz-snapshotter.service.d/
    printf '[Unit]\nPartOf=containerd.service\n\n[Service]\nKillSignal=SIGTERM\n' | sudo tee /usr/local/lib/systemd/system/stargz-snapshotter.service.d/finch.conf
    
    # Add a new services that syncs the filesystem before shutdown
    printf '[Unit]\nDescription=Sync containerd on shutdown\nDefaultDependencies=no\nBefore=shutdown.target reboot.target halt.target kexec.target\n\n[Service]\nType=oneshot\nExecStart=/bin/bash -c "sync /var/lib/containerd"\n\n[Install]\nWantedBy=halt.target reboot.target shutdown.target kexec.target\n' | sudo tee /usr/local/lib/systemd/system/finch-sync-on-shutdown.service
    sudo systemctl enable --now finch-sync-on-shutdown.service

    # Add a new service that cleans up lingering CNI networks on boot
    printf '[Unit]\nDescription=Delete hanging data on boot\nDefaultDependencies=no\nBefore=basic.target\n\n[Service]\nType=oneshot\nExecStart=/bin/bash -c "sudo rm -rf /var/lib/cni/networks/bridge/**; sudo rm -rf /var/lib/cni/results/bridge-finch-*"\n\n[Install]\nWantedBy=basic.target\n' | sudo tee /usr/local/lib/systemd/system/finch-cleanup-on-boot.service
    sudo systemctl enable --now finch-cleanup-on-boot.service
    
    sudo systemctl restart containerd.service

# Probe scripts to check readiness.
# 🟢 Builtin default: null
# probes:
# # Only `readiness` probes are supported right now.
# - mode: readiness
#   description: vim to be installed
#   script: |
#      #!/bin/bash
#      set -eux -o pipefail
#      if ! timeout 30s bash -c "until command -v vim; do sleep 3; done"; then
#        echo >&2 "vim is not installed yet"
#        exit 1
#      fi
#   hint: |
#     vim was not installed in the guest. Make sure the package system is working correctly.
#     Also see "/var/log/cloud-init-output.log" in the guest.

# ===================================================================== #
# FURTHER ADVANCED CONFIGURATION
# ===================================================================== #

# Specify desired QEMU CPU type for each arch.
# You can see what options are available for host emulation with: `qemu-system-$(arch) -cpu help`.
# Setting of instructions is supported like this: "qemu64,+ssse3".
cpuType:
  # 🟢 Builtin default: "cortex-a72" (or "host" when running on aarch64 host)
  aarch64: null
  # 🟢 Builtin default: "qemu64" (or "host" when running on x86_64 host)
  x86_64: null

firmware:
  # Use legacy BIOS instead of UEFI. Ignored for aarch64.
  # 🟢 Builtin default: false
  legacyBIOS: null

video:
  # QEMU display, e.g., "none", "cocoa", "sdl", "gtk".
  # As of QEMU v6.2, enabling this is known to have negative impact
  # on performance on macOS hosts: https://gitlab.com/qemu-project/qemu/-/issues/334
  # 🟢 Builtin default: "none"
  display: null

# Extra environment variables that will be loaded into the VM at start up.
# These variables are consumed by internal init scripts, and also added
# to /etc/environment.
# If you set any of "ftp_proxy", "http_proxy", "https_proxy", or "no_proxy", then
# Lima will automatically set an uppercase variant to the same value as well.
# 🟢 Builtin default: null
env:
  # Containerd namespace is used by the lima cidata script
  # 40-install-containerd.sh. Specifically this variable is defining the
  # Buildkit Workers Containerd namespace. 
  CONTAINERD_NAMESPACE: finch