feat: Add limactl vz-vmnet

It provides `VmnetNetwork` serialization to VMs.
`limactl vz-vmnet` takes flags:
- `--enable-mach-service[=true,false]`: register/unregister Mach service to `launchd`
  - It creates a launchd plist under ~/Library/LaunchAgents and bootstraps it.
  - The Mach service "io.lima-vm.vz.vmnet" is registered.
  - The working directory is $LIMA_HOME/_networks/vz-vmnet.
  - It also creates a shell script named "io.lima-vm.vz.vmnet.sh" that runs
    "limactl vz-vmnet" to avoid launching "limactl" directly from launchd.
    macOS System Settings (General > Login Items & Extensions) shows the first
    element of `ProgramArguments` as the login item name; using a shell script with
    a fixed filename makes the item easier to identify.
  - There is no need to register manually because the VZ driver is registered as appropriate.

- `--mach-service=<service name>`: launched as Mach server by `launchd` via `io.lima-vm.vz.vmnet.plist`
  - Launched on demand to connection from VZ driver by `launchd`.
  - Receives a request payload from VZ driver with fields:
    - `Network`: name of the network ("shared", "host", etc)
    - `Configuration`: `[]bytes@ representing `VzNetworkConfig` in JSON.
  - Validates clients are the same executable (cdhash) by using xpc_peer_requirement API.
  - Create `VmnetNetwork` from provided `Configuration` if cached one does not exist.
  - Replies to VZ driver with fields:
    - `Configuration`: If `VmnetNetwork` is cached, it may be created by different configuration.
    - `Serialization`: newly created or cached.
  - Monitors changes of networks
    - When the interface created by `VmnetNetwork` disappears from host, remove them from cache.
    - If all `VmnetNetwork` are removed, `limactl vz-vmnet` exits.

VZ driver (hostagent) does:
- Read `.vz` VzVmnetConfig from `networks.yaml`
- Use them on `- vz: <network>` fields; "shared" and "host" network are predefined.
- Register `limactl vz-vmnet` to `launchd` if not registered.
- Request serialization to the Mach service "io.lima-vm.vz.vmnet".
- Create `VmnetNetwork` by provided serialization, then use them.

Additional changes:
- Because shutdown takes longer on using `VmnetNetwork`:
  - Extend VZ driver's shutdown timeout from 5 seconds to 15 seconds
  - Add `ExitTimeOut` key with 20 seconds to autostart `io.lima-vm.autostart.INSTANCE.plist`
- `lima.yaml`: `- vzShared` and `- vzHost` are renamed to `- vz: shared` and `- vz: host`

Signed-off-by: Norio Nomura <[email protected]>

Author: norio-nomura

cmd/limactl/main.go

@@ -208,6 +208,7 @@ func newApp() *cobra.Command {
 		newNetworkCommand(),
 		newCloneCommand(),
 		newRenameCommand(),
+		newvzvmnetCommand(),
 	)
 	addPluginCommands(rootCmd)
 

cmd/limactl/vz-vmnet.go

@@ -0,0 +1,27 @@
+// SPDX-FileCopyrightText: Copyright The Lima Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package main
+
+import (
+	"github.com/spf13/cobra"
+)
+
+func newvzvmnetCommand() *cobra.Command {
+	newCommand := &cobra.Command{
+		Use:               "vz-vmnet",
+		Short:             "Run vz-vmnet",
+		Args:              cobra.ExactArgs(0),
+		RunE:              newvzvmnetAction,
+		ValidArgsFunction: newvzvmnetComplete,
+		Hidden:            true,
+	}
+	newCommand.Flags().Bool("enable-mach-service", false, "Enable Mach service")
+	newCommand.Flags().String("mach-service", "", "Run as Mach service")
+	_ = newCommand.Flags().MarkHidden("mach-service")
+	return newCommand
+}
+
+func newvzvmnetComplete(cmd *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	return bashCompleteInstanceNames(cmd)
+}

cmd/limactl/vz-vmnet_darwin.go

@@ -0,0 +1,41 @@
+// SPDX-FileCopyrightText: Copyright The Lima Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package main
+
+import (
+	"errors"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"github.com/coreos/go-semver/semver"
+	"github.com/spf13/cobra"
+
+	"github.com/lima-vm/lima/v2/pkg/osutil"
+	"github.com/lima-vm/lima/v2/pkg/vzvmnet"
+)
+
+func newvzvmnetAction(cmd *cobra.Command, _ []string) error {
+	macOSProductVersion, err := osutil.ProductVersion()
+	if err != nil {
+		return err
+	}
+	if macOSProductVersion.LessThan(*semver.New("26.0.0")) {
+		return errors.New("vz-vmnet requires macOS 26 or higher to run")
+	}
+
+	if !cmd.HasLocalFlags() {
+		return cmd.Help()
+	}
+
+	ctx, cancel := signal.NotifyContext(cmd.Context(), os.Interrupt, syscall.SIGTERM)
+	defer cancel()
+
+	if machServiceName, _ := cmd.Flags().GetString("mach-service"); machServiceName != "" {
+		return vzvmnet.RunMachService(ctx, machServiceName)
+	} else if enableMachService, _ := cmd.Flags().GetBool("enable-mach-service"); enableMachService {
+		return vzvmnet.RegisterMachService(ctx)
+	}
+	return vzvmnet.UnregisterMachService(ctx)
+}

cmd/limactl/vz-vmnet_nodarwin.go

@@ -0,0 +1,16 @@
+//go:build !darwin
+
+// SPDX-FileCopyrightText: Copyright The Lima Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package main
+
+import (
+	"errors"
+
+	"github.com/spf13/cobra"
+)
+
+func newvzvmnetAction(_ *cobra.Command, _ []string) error {
+	return errors.New("vz-vmnet command is only supported on macOS")
+}

go.mod

@@ -148,4 +148,4 @@ require (
 	sigs.k8s.io/structured-merge-diff/v6 v6.3.0 // indirect
 )
 
-replace github.com/Code-Hex/vz/v3 => github.com/norio-nomura/vz/v3 v3.7.2-0.20251122122159-6617c8faa123
+replace github.com/Code-Hex/vz/v3 => github.com/norio-nomura/vz/v3 v3.7.2-0.20251216141401-33858c083cdd

go.sum

@@ -207,8 +207,8 @@ github.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee h1:W5t00kpgFd
 github.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
 github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
 github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
-github.com/norio-nomura/vz/v3 v3.7.2-0.20251122122159-6617c8faa123 h1:3Xzg1W5gel17So2d2NSA+flx6yoyknx5nG9Pb6eZU6s=
-github.com/norio-nomura/vz/v3 v3.7.2-0.20251122122159-6617c8faa123/go.mod h1:+0IVfZY7N/7Vv5KpZWbEgTRK6jMg4s7DVM+op2hdyrs=
+github.com/norio-nomura/vz/v3 v3.7.2-0.20251216141401-33858c083cdd h1:X9tGAA8K75F8IALhl+1frY2sLpbdp1bzxOaKEaOakj0=
+github.com/norio-nomura/vz/v3 v3.7.2-0.20251216141401-33858c083cdd/go.mod h1:+0IVfZY7N/7Vv5KpZWbEgTRK6jMg4s7DVM+op2hdyrs=
 github.com/nxadm/tail v1.4.11 h1:8feyoE3OzPrcshW5/MJ4sGESc5cqmGkGCWlco4l0bqY=
 github.com/nxadm/tail v1.4.11/go.mod h1:OTaG3NK980DZzxbRq6lEuzgU+mug70nY11sMd4JXXHc=
 github.com/onsi/ginkgo v1.16.5 h1:8xi0RTUf59SOSfEtZMvwTvXYMzG4gV23XVHOZiXNtnE=

pkg/autostart/launchd/io.lima-vm.autostart.INSTANCE.plist

@@ -13,6 +13,8 @@
 	</array>
 	<key>RunAtLoad</key>
 	<true/>
+	<key>ExitTimeOut</key>
+	<integer>20</integer>
 	<key>StandardErrorPath</key>
 	<string>launchd.stderr.log</string>
 	<key>StandardOutPath</key>

pkg/driver/vz/vm_darwin.go

@@ -37,6 +37,7 @@ import (
 	"github.com/lima-vm/lima/v2/pkg/networks/usernet"
 	"github.com/lima-vm/lima/v2/pkg/osutil"
 	"github.com/lima-vm/lima/v2/pkg/store"
+	"github.com/lima-vm/lima/v2/pkg/vzvmnet"
 )
 
 // diskImageCachingMode is set to DiskImageCachingModeCached so as to avoid disk corruption on ARM:
@@ -363,7 +364,8 @@ func attachNetwork(ctx context.Context, inst *limatype.Instance, vmConfig *vz.Vi
 	}
 
 	for i, nw := range inst.Networks {
-		if nw.VZNAT != nil && *nw.VZNAT {
+		switch {
+		case nw.VZNAT != nil && *nw.VZNAT:
 			attachment, err := vz.NewNATNetworkDeviceAttachment()
 			if err != nil {
 				return err
@@ -373,30 +375,16 @@ func attachNetwork(ctx context.Context, inst *limatype.Instance, vmConfig *vz.Vi
 				return err
 			}
 			configurations = append(configurations, networkConfig)
-		} else if nw.VZShared != nil && *nw.VZShared {
-			config, err := vz.NewVmnetNetworkConfiguration(vz.SharedMode)
-			if err != nil {
-				return err
-			}
-			network, err := vz.NewVmnetNetwork(config)
-			if err != nil {
-				return err
-			}
-			attachment, err := vz.NewVmnetNetworkDeviceAttachment(network)
-			if err != nil {
-				return err
-			}
-			networkConfig, err := newVirtioNetworkDeviceConfiguration(attachment, nw.MACAddress)
+		case nw.Vz != "":
+			nwCfg, err := networks.LoadConfig()
 			if err != nil {
 				return err
 			}
-			configurations = append(configurations, networkConfig)
-		} else if nw.VZHost != nil && *nw.VZHost {
-			config, err := vz.NewVmnetNetworkConfiguration(vz.HostMode)
-			if err != nil {
-				return err
+			vzCfg, ok := nwCfg.Vz[nw.Vz]
+			if !ok {
+				return fmt.Errorf("networks.yaml: 'vz: %s' is not defined", nw.Vz)
 			}
-			network, err := vz.NewVmnetNetwork(config)
+			network, err := vzvmnet.RequestVmnetNetwork(ctx, nw.Vz, vzCfg)
 			if err != nil {
 				return err
 			}
@@ -409,7 +397,7 @@ func attachNetwork(ctx context.Context, inst *limatype.Instance, vmConfig *vz.Vi
 				return err
 			}
 			configurations = append(configurations, networkConfig)
-		} else if nw.Lima != "" {
+		case nw.Lima != "":
 			nwCfg, err := networks.LoadConfig()
 			if err != nil {
 				return err
@@ -461,7 +449,7 @@ func attachNetwork(ctx context.Context, inst *limatype.Instance, vmConfig *vz.Vi
 					configurations = append(configurations, networkConfig)
 				}
 			}
-		} else if nw.Socket != "" {
+		case nw.Socket != "":
 			clientFile, err := DialQemu(ctx, nw.Socket)
 			if err != nil {
 				return err

pkg/driver/vz/vz_driver_darwin.go

@@ -280,8 +280,7 @@ func validateConfig(_ context.Context, cfg *limatype.LimaYAML) error {
 
 	for i, nw := range cfg.Networks {
 		if unknown := reflectutil.UnknownNonEmptyFields(nw, "VZNAT",
-			"VZShared",
-			"VZHost",
+			"Vz",
 			"Lima",
 			"Socket",
 			"MACAddress",
@@ -290,9 +289,9 @@ func validateConfig(_ context.Context, cfg *limatype.LimaYAML) error {
 		); len(unknown) > 0 {
 			logrus.Warnf("vmType %s: ignoring networks[%d]: %+v", *cfg.VMType, i, unknown)
 		}
-		if (nw.VZShared != nil && *nw.VZShared) || (nw.VZHost != nil && *nw.VZHost) {
+		if nw.Vz != "" {
 			if macOSProductVersion.LessThan(*semver.New("26.0.0")) {
-				return fmt.Errorf("networks[%d]: VZShared and VZHost require macOS 26.0 or later", i)
+				return fmt.Errorf("networks[%d]: 'vz: %s' require macOS 26.0 or later", i, nw.Vz)
 			}
 		}
 	}
@@ -375,9 +374,10 @@ func (l *LimaVzDriver) Stop(_ context.Context) error {
 			return err
 		}
 
-		timeout := time.After(5 * time.Second)
+		timeout := time.After(15 * time.Second)
 		ticker := time.NewTicker(500 * time.Millisecond)
 		for {
+			logrus.Debug("Waiting for VZ to stop...")
 			select {
 			case <-timeout:
 				return errors.New("vz timeout while waiting for stop status")

pkg/limatmpl/embed.go

@@ -543,13 +543,9 @@ func (tmpl *Template) combineNetworks() {
 				tmpl.copyListEntryField(networks, dst, src, "vzNAT")
 				dest.VZNAT = nw.VZNAT
 			}
-			if dest.VZShared == nil && nw.VZShared != nil {
-				tmpl.copyListEntryField(networks, dst, src, "vzShared")
-				dest.VZShared = nw.VZShared
-			}
-			if dest.VZHost == nil && nw.VZHost != nil {
-				tmpl.copyListEntryField(networks, dst, src, "vzHost")
-				dest.VZHost = nw.VZHost
+			if dest.Vz == "" && nw.Vz != "" {
+				tmpl.copyListEntryField(networks, dst, src, "vz")
+				dest.Vz = nw.Vz
 			}
 			if dest.Metric == nil && nw.Metric != nil {
 				tmpl.copyListEntryField(networks, dst, src, "metric")