Implement limactl clone

AkihiroSuda · AkihiroSuda · commit b209d0da9f39 · 2025-07-01T17:47:08.000+09:00
`limactl clone OLDINST NEWINST` clones an instance.

Not to be confused with `limactl copy SRC DST` (copy files).

Fix issue 3658

Signed-off-by: Akihiro Suda &lt;akihiro.suda.cz@hco.ntt.co.jp&gt;
diff --git a/cmd/limactl/clone.go b/cmd/limactl/clone.go
@@ -0,0 +1,124 @@
+// SPDX-FileCopyrightText: Copyright The Lima Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package main
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/spf13/cobra"
+
+	"github.com/lima-vm/lima/cmd/limactl/editflags"
+	"github.com/lima-vm/lima/pkg/instance"
+	"github.com/lima-vm/lima/pkg/limayaml"
+	networks "github.com/lima-vm/lima/pkg/networks/reconcile"
+	"github.com/lima-vm/lima/pkg/store"
+	"github.com/lima-vm/lima/pkg/store/filenames"
+	"github.com/lima-vm/lima/pkg/yqutil"
+)
+
+func newCloneCommand() *cobra.Command {
+	cloneCommand := &cobra.Command{
+		Use:   "clone OLDINST NEWINST",
+		Short: "Clone an instance of Lima",
+		Long: `Clone an instance of Lima.
+
+Not to be confused with 'limactl copy' ('limactl cp').
+`,
+		Args:              WrapArgsError(cobra.ExactArgs(2)),
+		RunE:              cloneAction,
+		ValidArgsFunction: cloneBashComplete,
+		GroupID:           advancedCommand,
+	}
+	editflags.RegisterEdit(cloneCommand)
+	return cloneCommand
+}
+
+func cloneAction(cmd *cobra.Command, args []string) error {
+	ctx := cmd.Context()
+	flags := cmd.Flags()
+	tty, err := flags.GetBool("tty")
+	if err != nil {
+		return err
+	}
+
+	oldInstName, newInstName := args[0], args[1]
+	oldInst, err := store.Inspect(oldInstName)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return fmt.Errorf("instance %q not found", oldInstName)
+		}
+		return err
+	}
+	if oldInst.Status == store.StatusRunning {
+		return errors.New("cannot clone a running instance")
+	}
+
+	if err = instance.Clone(ctx, oldInstName, newInstName); err != nil {
+		return err
+	}
+
+	newInst, err := store.Inspect(newInstName)
+	if err != nil {
+		return err
+	}
+
+	yqExprs, err := editflags.YQExpressions(flags, false)
+	if err != nil {
+		return err
+	}
+	if len(yqExprs) > 0 {
+		// TODO: reduce duplicated codes across cloneAction and editAction
+		yq := yqutil.Join(yqExprs)
+		filePath := filepath.Join(newInst.Dir, filenames.LimaYAML)
+		yContent, err := os.ReadFile(filePath)
+		if err != nil {
+			return err
+		}
+		yBytes, err := yqutil.EvaluateExpression(yq, yContent)
+		if err != nil {
+			return err
+		}
+		y, err := limayaml.LoadWithWarnings(yBytes, filePath)
+		if err != nil {
+			return err
+		}
+		if err := limayaml.Validate(y, true); err != nil {
+			return saveRejectedYAML(yBytes, err)
+		}
+		if err := limayaml.ValidateAgainstLatestConfig(yBytes, yContent); err != nil {
+			return saveRejectedYAML(yBytes, err)
+		}
+		if err := os.WriteFile(filePath, yBytes, 0o644); err != nil {
+			return err
+		}
+		newInst, err = store.Inspect(newInst.Name)
+		if err != nil {
+			return err
+		}
+	}
+
+	if !tty {
+		// use "start" to start it
+		return nil
+	}
+	startNow, err := askWhetherToStart()
+	if err != nil {
+		return err
+	}
+	if !startNow {
+		return nil
+	}
+	err = networks.Reconcile(ctx, newInst.Name)
+	if err != nil {
+		return err
+	}
+	return instance.Start(ctx, newInst, "", false)
+}
+
+func cloneBashComplete(cmd *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	return bashCompleteInstanceNames(cmd)
+}
diff --git a/cmd/limactl/copy.go b/cmd/limactl/copy.go
@@ -26,6 +26,8 @@ const copyHelp = `Copy files between host and guest
 Prefix guest filenames with the instance name and a colon.
 
 Example: limactl copy default:/etc/os-release .
+
+Not to be confused with 'limactl clone'.
 `
 
 func newCopyCommand() *cobra.Command {
diff --git a/cmd/limactl/main.go b/cmd/limactl/main.go
@@ -189,6 +189,7 @@ func newApp() *cobra.Command {
 		newRestartCommand(),
 		newSudoersCommand(),
 		newStartAtLoginCommand(),
+		newCloneCommand(),
 	)
 
 	return rootCmd
diff --git a/hack/test-templates.sh b/hack/test-templates.sh
@@ -49,6 +49,7 @@ declare -A CHECKS=(
 	# snapshot tests are too flaky (especially with archlinux)
 	["snapshot-online"]=""
 	["snapshot-offline"]=""
+	["clone"]=""
 	["port-forwards"]="1"
 	["vmnet"]=""
 	["disk"]=""
@@ -85,6 +86,7 @@ case "$NAME" in
 	CHECKS["disk"]=1
 	CHECKS["snapshot-online"]="1"
 	CHECKS["snapshot-offline"]="1"
+	CHECKS["clone"]="1"
 	CHECKS["mount-path-with-spaces"]="1"
 	CHECKS["provision-data"]="1"
 	CHECKS["param-env-variables"]="1"
@@ -527,6 +529,15 @@ if [[ -n ${CHECKS["snapshot-offline"]} ]]; then
 	limactl snapshot delete "$NAME" --tag snap2
 	limactl start "$NAME"
 fi
+if [[ -n ${CHECKS["clone"]} ]]; then
+	INFO "Testing cloning"
+	limactl stop "$NAME"
+	sleep 3
+	limactl clone "$NAME" "${NAME}-clone"
+	limactl start "${NAME}-clone"
+	[ "$(limactl shell "${NAME}-clone" hostname)" = "lima-${NAME}-clone" ]
+	limactl start "$NAME"
+fi
 
 if [[ $NAME == "fedora" && "$(limactl ls --json "$NAME" | jq -r .vmType)" == "vz" ]]; then
 	"${scriptdir}"/test-selinux.sh "$NAME"
diff --git a/pkg/instance/clone.go b/pkg/instance/clone.go
@@ -0,0 +1,82 @@
+// SPDX-FileCopyrightText: Copyright The Lima Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package instance
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+
+	continuityfs "github.com/containerd/continuity/fs"
+
+	"github.com/lima-vm/lima/pkg/osutil"
+	"github.com/lima-vm/lima/pkg/store"
+	"github.com/lima-vm/lima/pkg/store/filenames"
+)
+
+func Clone(_ context.Context, oldInstName, newInstName string) error {
+	if oldInstName == "" || newInstName == "" {
+		return errors.New("got empty instName")
+	}
+	if oldInstName == newInstName {
+		return fmt.Errorf("new instance name %q must be different from %q", newInstName, oldInstName)
+	}
+
+	oldInstDir, err := store.InstanceDir(oldInstName)
+	if err != nil {
+		return err
+	}
+
+	newInstDir, err := store.InstanceDir(newInstName)
+	if err != nil {
+		return err
+	}
+
+	// the full path of the socket name must be less than UNIX_PATH_MAX chars.
+	maxSockName := filepath.Join(newInstDir, filenames.LongestSock)
+	if len(maxSockName) >= osutil.UnixPathMax {
+		return fmt.Errorf("instance name %q too long: %q must be less than UNIX_PATH_MAX=%d characters, but is %d",
+			newInstName, maxSockName, osutil.UnixPathMax, len(maxSockName))
+	}
+
+	if err = os.Mkdir(newInstDir, 0o700); err != nil {
+		return err
+	}
+
+	walkDirFn := func(path string, d fs.DirEntry, err error) error {
+		// TODO: recreate VzIdentifier with the new UUID.
+		//
+		// VzIdentifier file must not be just removed here, as pkg/limayaml depends on VzIdentifier
+		// for resolving the VM type.
+
+		if slices.Contains(filenames.SkipOnClone, filepath.Base(path)) {
+			return nil
+		}
+		for _, ext := range filenames.TmpFileSuffixes {
+			if strings.HasSuffix(path, ext) {
+				return nil
+			}
+		}
+		if err != nil {
+			return err
+		}
+		pathRel, err := filepath.Rel(oldInstDir, path)
+		if err != nil {
+			return err
+		}
+		dst := filepath.Join(newInstDir, pathRel)
+		if d.IsDir() {
+			return os.MkdirAll(dst, d.Type().Perm())
+		}
+		// CopyFile attempts copy-on-write when supported by the filesystem
+		return continuityfs.CopyFile(dst, path)
+	}
+
+	return filepath.WalkDir(oldInstDir, walkDirFn)
+}
diff --git a/pkg/instance/stop.go b/pkg/instance/stop.go
@@ -131,8 +131,7 @@ func StopForcibly(inst *store.Instance) {
 		logrus.Info("The host agent process seems already stopped")
 	}
 
-	suffixesToBeRemoved := []string{".pid", ".sock", ".tmp"}
-	globPatterns := strings.ReplaceAll(strings.Join(suffixesToBeRemoved, " "), ".", "*.")
+	globPatterns := strings.ReplaceAll(strings.Join(filenames.TmpFileSuffixes, " "), ".", "*.")
 	logrus.Infof("Removing %s under %q", globPatterns, inst.Dir)
 
 	fi, err := os.ReadDir(inst.Dir)
@@ -142,7 +141,7 @@ func StopForcibly(inst *store.Instance) {
 	}
 	for _, f := range fi {
 		path := filepath.Join(inst.Dir, f.Name())
-		for _, suffix := range suffixesToBeRemoved {
+		for _, suffix := range filenames.TmpFileSuffixes {
 			if strings.HasSuffix(path, suffix) {
 				logrus.Infof("Removing %q", path)
 				if err := os.Remove(path); err != nil {
diff --git a/pkg/store/filenames/filenames.go b/pkg/store/filenames/filenames.go
@@ -91,3 +91,11 @@ const LongestSock = SSHSock + ".1234567890123456"
 func PIDFile(name string) string {
 	return name + ".pid"
 }
+
+// SkipOnClone files should be skipped on cloning an instance.
+var SkipOnClone = []string{
+	Protected,
+}
+
+// TmpFileSuffixes is the list of the tmp file suffixes.
+var TmpFileSuffixes = []string{".pid", ".sock", ".tmp"}

Original file line number	Diff line number	Diff line change
@@ -26,6 +26,8 @@ const copyHelp = `Copy files between host and guest
`26`	`26`	`Prefix guest filenames with the instance name and a colon.`
`27`	`27`
`28`	`28`	`Example: limactl copy default:/etc/os-release .`
	`29`	`+`
	`30`	`+Not to be confused with 'limactl clone'.`
`29`	`31`	`
`30`	`32`
`31`	`33`	`func newCopyCommand() *cobra.Command {`
Original file line number	Diff line number	Diff line change
`@@ -189,6 +189,7 @@ func newApp() *cobra.Command {`
`189`	`189`	`newRestartCommand(),`
`190`	`190`	`newSudoersCommand(),`
`191`	`191`	`newStartAtLoginCommand(),`
	`192`	`+ newCloneCommand(),`
`192`	`193`	`)`
`193`	`194`
`194`	`195`	`return rootCmd`