Add environment variables documentation

.github/workflows/test.yml

@@ -46,6 +46,8 @@ jobs:
       run: |
         sudo apt-get update
         sudo apt-get install -y shellcheck
+    - name: Run file and directory name linter
+      uses: ls-lint/[email protected]
     - name: Run shellcheck
       run: find . -name '*.sh' | xargs shellcheck
     - name: Install shfmt

.golangci.yml

@@ -96,12 +96,42 @@ linters-settings:
     - rangeValCopy
     - hugeParam
     - importShadow
-    - ifElseChain
     - sprintfQuotedString
     - builtinShadow
     - filepathJoin
+    settings:
+      ifElseChain:
+        # Min number of if-else blocks that makes the warning trigger.
+        minThreshold: 3
   errorlint:
     asserts: false
+  revive:
+    # https://github.com/mgechev/revive/blob/master/RULES_DESCRIPTIONS.md
+    rules:
+    - name: blank-imports
+    - name: context-as-argument
+    - name: context-keys-type
+    - name: deep-exit
+    - name: dot-imports
+    - name: empty-block
+    - name: error-naming
+    - name: error-return
+    - name: error-strings
+    - name: errorf
+    - name: exported
+    - name: increment-decrement
+    - name: indent-error-flow
+    - name: package-comments
+    - name: range
+    - name: receiver-naming
+    - name: redefines-builtin-id
+    - name: superfluous-else
+    - name: time-naming
+    - name: unexported-return
+    - name: unreachable-code
+    - name: unused-parameter
+    - name: var-declaration
+    - name: var-naming
 issues:
   # Maximum issues count per one linter.
   max-issues-per-linter: 0

.ls-lint.yml

@@ -0,0 +1,34 @@
+# ls-lint configuration file.
+# https://ls-lint.org/2.2/configuration/the-basics.html
+ls:
+  .dir: kebab-case
+  .go: snake_case
+  .lima: snake_case
+  .sh: kebab-case
+  .TEMPLATE.yaml: kebab-case
+  .yaml: kebab-case
+  .yml: kebab-case
+
+  .github:
+    .yaml: snake_case
+
+  cmd/limactl:
+    # valid names are `show-ssh.go` or `show-ssh_test.go`
+    .go: kebab-case | regex:[a-z0-9-]+_test
+
+  docs:
+    .md: kebab-case
+
+  website/content:
+    .dir: lowercase
+
+ignore:
+- .git
+- .golangci.yml
+- .ls-lint.yml
+- '_output'
+- '**/*.pb\.go'
+- hack/common.inc.sh
+- pkg/cidata/cidata.TEMPLATE.d
+- pkg/cidata/cidata.TEMPLATE.d/util/compare_version.sh
+- website

Kconfig

@@ -30,3 +30,9 @@ config GUESTAGENT_ARCH_RISCV64
 	help
 		Build lima-guestagent for "riscv64" Arch
 	default y
+
+config GUESTAGENT_COMPRESS
+	bool "guestagent compress"
+	help
+		Compress lima-guestagent
+	default n

Makefile

@@ -86,22 +86,26 @@ HELPERS = \
 	_output/bin/podman.lima \
 	_output/bin/kubectl.lima
 
+ifeq ($(CONFIG_GUESTAGENT_COMPRESS),y)
+gz = .gz
+endif
+
 ifeq ($(CONFIG_GUESTAGENT_OS_LINUX),y)
 ifeq ($(CONFIG_GUESTAGENT_ARCH_X8664),y)
 GUESTAGENT += \
-	_output/share/lima/lima-guestagent.Linux-x86_64
+	_output/share/lima/lima-guestagent.Linux-x86_64$(gz)
 endif
 ifeq ($(CONFIG_GUESTAGENT_ARCH_AARCH64),y)
 GUESTAGENT += \
-	_output/share/lima/lima-guestagent.Linux-aarch64
+	_output/share/lima/lima-guestagent.Linux-aarch64$(gz)
 endif
 ifeq ($(CONFIG_GUESTAGENT_ARCH_ARMV7L),y)
 GUESTAGENT += \
-	_output/share/lima/lima-guestagent.Linux-armv7l
+	_output/share/lima/lima-guestagent.Linux-armv7l$(gz)
 endif
 ifeq ($(CONFIG_GUESTAGENT_ARCH_RISCV64),y)
 GUESTAGENT += \
-	_output/share/lima/lima-guestagent.Linux-riscv64
+	_output/share/lima/lima-guestagent.Linux-riscv64$(gz)
 endif
 endif
 
@@ -188,6 +192,9 @@ _output/share/lima/lima-guestagent.Linux-riscv64:
 	GOOS=linux GOARCH=riscv64 CGO_ENABLED=0 $(GO_BUILD) -o $@ ./cmd/lima-guestagent
 	chmod 644 $@
 
+_output/share/lima/lima-guestagent.%.gz: _output/share/lima/lima-guestagent.%
+	gzip $<
+
 .PHONY: manpages
 manpages: _output/bin/limactl$(exe)
 	@mkdir -p _output/share/man/man1

README.md

@@ -74,6 +74,9 @@ GUI:
 ### Code of Conduct
 Lima follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).
 
+### Environment Variables
+For more information on environment variables, see the [Environment Variables](https://lima-vm.io/docs/config/environment-variables/) page.
+
 - - -
 **We are a [Cloud Native Computing Foundation](https://cncf.io/) sandbox project.**
 
@@ -82,4 +85,4 @@ Lima follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/
   <img src="https://www.cncf.io/wp-content/uploads/2022/07/cncf-color-bg.svg" width=300 />
 </picture>
 
-The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see [Trademark Usage](https://www.linuxfoundation.org/trademark-usage/).
+The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see [Trademark Usage](https://www.linuxfoundation.org/trademark-usage/].

cmd/docker.lima

@@ -1,13 +1,17 @@
 #!/bin/sh
 set -eu
+
+# Environment Variables
+# LIMA_INSTANCE: Specifies the name of the Lima instance to use. Default is "docker".
+
 : "${LIMA_INSTANCE:=docker}"
 : "${DOCKER:=docker}"
 
 if [ "$(limactl ls -q "$LIMA_INSTANCE" 2>/dev/null)" != "$LIMA_INSTANCE" ]; then
   echo "instance \"$LIMA_INSTANCE\" does not exist, run \`limactl create --name=$LIMA_INSTANCE template://docker\` to create a new instance" >&2
   exit 1
 elif [ "$(limactl ls -f '{{ .Status }}' "$LIMA_INSTANCE" 2>/dev/null)" != "Running" ]; then
-  echo "instance \"$LIMA_INSTANCE\" is not running, run \`limactl start $LIMA_INSTANCE\` to start the existing instance" >&2
+  echo "instance \"$LIMA_INSTANCE\"" is not running, run \`limactl start $LIMA_INSTANCE\` to start the existing instance" >&2
   exit 1
 fi
 DOCKER=$(command -v "$DOCKER" || true)

cmd/kubectl.lima

@@ -1,5 +1,9 @@
 #!/bin/sh
 set -eu
+
+# Environment Variables
+# LIMA_INSTANCE: Specifies the name of the Lima instance to use. Default is empty.
+
 : "${LIMA_INSTANCE:=}"
 : "${KUBECTL:=kubectl}"
 

cmd/lima

@@ -1,5 +1,12 @@
 #!/bin/sh
 set -eu
+
+# Environment Variables
+# LIMA_INSTANCE: Specifies the name of the Lima instance to use. Default is "default".
+# LIMA_SHELL: Specifies the shell interpreter to use inside the Lima instance. Default is the user's shell configured inside the instance.
+# LIMA_WORKDIR: Specifies the initial working directory inside the Lima instance. Default is the current directory from the host.
+# LIMACTL: Specifies the path to the limactl binary. Default is "limactl" in $PATH.
+
 : "${LIMA_INSTANCE:=default}"
 : "${LIMA_SHELL:=}"
 : "${LIMA_WORKDIR:=}"

cmd/lima.bat

@@ -1,4 +1,8 @@
-@echo off
-IF NOT DEFINED LIMACTL (SET LIMACTL=limactl)
-IF NOT DEFINED LIMA_INSTANCE (SET LIMA_INSTANCE=default)
-%LIMACTL% shell %LIMA_INSTANCE% %*
+@echo off
+REM Environment Variables
+REM LIMA_INSTANCE: Specifies the name of the Lima instance to use. Default is "default".
+REM LIMACTL: Specifies the path to the limactl binary. Default is "limactl" in %PATH%.
+
+IF NOT DEFINED LIMACTL (SET LIMACTL=limactl)
+IF NOT DEFINED LIMA_INSTANCE (SET LIMA_INSTANCE=default)
+%LIMACTL% shell %LIMA_INSTANCE% %*

cmd/limactl/list.go

@@ -73,6 +73,19 @@ func instanceMatches(arg string, instances []string) []string {
 	return matches
 }
 
+// unmatchedInstancesError is created when unmatched instance names found.
+type unmatchedInstancesError struct{}
+
+// Error implements error.
+func (unmatchedInstancesError) Error() string {
+	return "unmatched instances"
+}
+
+// ExitCode implements ExitCoder.
+func (unmatchedInstancesError) ExitCode() int {
+	return 1
+}
+
 func listAction(cmd *cobra.Command, args []string) error {
 	quiet, err := cmd.Flags().GetBool("quiet")
 	if err != nil {
@@ -148,7 +161,7 @@ func listAction(cmd *cobra.Command, args []string) error {
 			fmt.Fprintln(cmd.OutOrStdout(), instName)
 		}
 		if unmatchedInstances {
-			os.Exit(1)
+			return unmatchedInstancesError{}
 		}
 		return nil
 	}
@@ -186,7 +199,7 @@ func listAction(cmd *cobra.Command, args []string) error {
 
 	err = store.PrintInstances(out, instances, format, &options)
 	if err == nil && unmatchedInstances {
-		os.Exit(1)
+		return unmatchedInstancesError{}
 	}
 	return err
 }

cmd/limactl/main.go

@@ -156,7 +156,7 @@ func handleExitCoder(err error) {
 	}
 
 	if exitErr, ok := err.(ExitCoder); ok {
-		os.Exit(exitErr.ExitCode())
+		os.Exit(exitErr.ExitCode()) //nolint:revive // it's intentional to call os.Exit in this function
 		return
 	}
 }

cmd/limactl/start.go

@@ -128,9 +128,11 @@ func loadOrCreateInstance(cmd *cobra.Command, args []string, createOnly bool) (*
 
 	const yBytesLimit = 4 * 1024 * 1024 // 4MiB
 
-	if ok, u := guessarg.SeemsTemplateURL(arg); ok {
+	isTemplateURL, templateURL := guessarg.SeemsTemplateURL(arg)
+	switch {
+	case isTemplateURL:
 		// No need to use SecureJoin here. https://github.com/lima-vm/lima/pull/805#discussion_r853411702
-		templateName := filepath.Join(u.Host, u.Path)
+		templateName := filepath.Join(templateURL.Host, templateURL.Path)
 		logrus.Debugf("interpreting argument %q as a template name %q", arg, templateName)
 		if st.instName == "" {
 			// e.g., templateName = "deprecated/centos-7" , st.instName = "centos-7"
@@ -140,7 +142,7 @@ func loadOrCreateInstance(cmd *cobra.Command, args []string, createOnly bool) (*
 		if err != nil {
 			return nil, err
 		}
-	} else if guessarg.SeemsHTTPURL(arg) {
+	case guessarg.SeemsHTTPURL(arg):
 		if st.instName == "" {
 			st.instName, err = guessarg.InstNameFromURL(arg)
 			if err != nil {
@@ -161,7 +163,7 @@ func loadOrCreateInstance(cmd *cobra.Command, args []string, createOnly bool) (*
 		if err != nil {
 			return nil, err
 		}
-	} else if guessarg.SeemsFileURL(arg) {
+	case guessarg.SeemsFileURL(arg):
 		if st.instName == "" {
 			st.instName, err = guessarg.InstNameFromURL(arg)
 			if err != nil {
@@ -178,7 +180,7 @@ func loadOrCreateInstance(cmd *cobra.Command, args []string, createOnly bool) (*
 		if err != nil {
 			return nil, err
 		}
-	} else if guessarg.SeemsYAMLPath(arg) {
+	case guessarg.SeemsYAMLPath(arg):
 		if st.instName == "" {
 			st.instName, err = guessarg.InstNameFromYAMLPath(arg)
 			if err != nil {
@@ -195,7 +197,7 @@ func loadOrCreateInstance(cmd *cobra.Command, args []string, createOnly bool) (*
 		if err != nil {
 			return nil, err
 		}
-	} else if arg == "-" {
+	case arg == "-":
 		if st.instName == "" {
 			return nil, errors.New("must pass instance name with --name when reading template from stdin")
 		}
@@ -209,7 +211,7 @@ func loadOrCreateInstance(cmd *cobra.Command, args []string, createOnly bool) (*
 			return nil, errors.New("cannot use --tty=true and read template from stdin together")
 		}
 		tty = false
-	} else {
+	default:
 		if arg == "" {
 			if st.instName == "" {
 				st.instName = DefaultInstanceName
@@ -292,6 +294,18 @@ func applyYQExpressionToExistingInstance(inst *store.Instance, yq string) (*stor
 	if err != nil {
 		return nil, err
 	}
+	y, err := limayaml.Load(yBytes, filePath)
+	if err != nil {
+		return nil, err
+	}
+	if err := limayaml.Validate(y, true); err != nil {
+		rejectedYAML := "lima.REJECTED.yaml"
+		if writeErr := os.WriteFile(rejectedYAML, yBytes, 0o644); writeErr != nil {
+			return nil, fmt.Errorf("the YAML is invalid, attempted to save the buffer as %q but failed: %w: %w", rejectedYAML, writeErr, err)
+		}
+		// TODO: may need to support editing the rejected YAML
+		return nil, fmt.Errorf("the YAML is invalid, saved the buffer as %q: %w", rejectedYAML, err)
+	}
 	if err := os.WriteFile(filePath, yBytes, 0o644); err != nil {
 		return nil, err
 	}
@@ -373,6 +387,21 @@ func modifyInPlace(st *creatorState, yq string) error {
 	return nil
 }
 
+// exitSuccessError is an error that indicates a successful exit.
+type exitSuccessError struct {
+	Msg string
+}
+
+// Error implements error.
+func (e exitSuccessError) Error() string {
+	return e.Msg
+}
+
+// ExitCode implements ExitCoder.
+func (exitSuccessError) ExitCode() int {
+	return 0
+}
+
 func chooseNextCreatorState(st *creatorState, yq string) (*creatorState, error) {
 	for {
 		if err := modifyInPlace(st, yq); err != nil {
@@ -411,9 +440,9 @@ func chooseNextCreatorState(st *creatorState, yq string) (*creatorState, error)
 				return st, err
 			}
 			if len(st.yBytes) == 0 {
-				logrus.Info("Aborting, as requested by saving the file with empty content")
-				os.Exit(0)
-				return st, errors.New("should not reach here")
+				const msg = "Aborting, as requested by saving the file with empty content"
+				logrus.Info(msg)
+				return nil, exitSuccessError{Msg: msg}
 			}
 			return st, nil
 		case 2: // "Choose another template..."
@@ -446,8 +475,7 @@ func chooseNextCreatorState(st *creatorState, yq string) (*creatorState, error)
 			}
 			continue
 		case 3: // "Exit"
-			os.Exit(0)
-			return st, errors.New("should not reach here")
+			return nil, exitSuccessError{Msg: "Choosing to exit"}
 		default:
 			return st, fmt.Errorf("unexpected answer %q", ans)
 		}

cmd/limactl/stop.go

@@ -75,7 +75,7 @@ func stopInstanceGracefully(inst *store.Instance) error {
 }
 
 func waitForHostAgentTermination(ctx context.Context, inst *store.Instance, begin time.Time) error {
-	ctx2, cancel := context.WithTimeout(ctx, 3*time.Minute)
+	ctx2, cancel := context.WithTimeout(ctx, 3*time.Minute+10*time.Second)
 	defer cancel()
 
 	var receivedExitingEvent bool

cmd/limactl/usernet.go

@@ -73,6 +73,9 @@ func usernetAction(cmd *cobra.Command, _ []string) error {
 	os.RemoveAll(qemuSocket)
 	os.RemoveAll(fdSocket)
 
+	// Environment Variables
+	// LIMA_USERNET_RESOLVE_IP_ADDRESS_TIMEOUT: Specifies the timeout duration for resolving IP addresses in minutes. Default is 2 minutes.
+
 	return usernet.StartGVisorNetstack(cmd.Context(), &usernet.GVisorNetstackOpts{
 		MTU:           mtu,
 		Endpoint:      endpoint,