pkg/hostagent: Add the _LIMA_DIRECT_IP_PORT_FORWARDER environment variable to enable direct IP port forwarding to the VM.

### Direct IP Port Forwarding

To enable direct IP port forwarding, set the `_LIMA_DIRECT_IP_PORT_FORWARDER` environment variable to `true`:

```bash
export _LIMA_DIRECT_IP_PORT_FORWARDER=true
```
This feature makes Lima to use direct IP port forwarding instead of gRPC port forwarding.
When this feature is enabled, Lima tries to connect to the guest's IP address directly for port forwarding.

#### Fallback to gRPC Port Forwarding
Lima may fall back to gRPC port forwarding in the following cases:
- If the guest's IP address is not available, Lima falls back to gRPC port forwarding.
- If the guest's IP address is available but the connection to the guest's IP address fails, Lima also falls back to gRPC port forwarding.
- If the guest's IP address is not accessible from the host (e.g. localhost on guest), Lima falls back to gRPC port forwarding as well.

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

Author: norio-nomura

.github/workflows/test.yml

@@ -524,6 +524,11 @@ jobs:
         create_arg:
         - ""
         - "--network=vzNAT"
+        include:
+        - template: default.yaml
+          create_arg: "--network=vzNAT"
+          additional_env: |
+            _LIMA_DIRECT_IP_PORT_FORWARDER=true
     steps:
     - name: "Adjust LIMACTL_CREATE_ARGS"
       # --cpus=1 is needed for running vz on GHA: https://github.com/lima-vm/lima/pull/1511#issuecomment-1574937888
@@ -544,6 +549,9 @@ jobs:
       run: brew install bash coreutils w3m socat
     - name: Uninstall qemu
       run: brew uninstall --ignore-dependencies --force qemu
+    - name: Set additional environment variables
+      if: matrix.additional_env != null
+      run: echo "${{ matrix.additional_env }}" >>$GITHUB_ENV
     - name: Test
       run: ./hack/test-templates.sh templates/${{ matrix.template }}
     - if: failure()

pkg/hostagent/hostagent.go

@@ -894,37 +894,52 @@ func (a *HostAgent) processGuestAgentEvents(ctx context.Context, client *guestag
 		if useSSHFwd {
 			a.portForwarder.OnEvent(ctx, ev)
 		} else {
-			dialContext := func(ctx context.Context, network, guestAddress string) (net.Conn, error) {
-				guestIPv4, guestIPv6 := a.GuestIPs()
-				if guestIPv4 == nil && guestIPv6 == nil {
-					return portfwd.DialContextToGRPCTunnel(client)(ctx, network, guestAddress)
+			useDirectIPPortForwarding := false
+			if envVar := os.Getenv("_LIMA_DIRECT_IP_PORT_FORWARDER"); envVar != "" {
+				b, err := strconv.ParseBool(envVar)
+				if err != nil {
+					logrus.WithError(err).Warnf("invalid _LIMA_DIRECT_IP_PORT_FORWARDER value %q", envVar)
+				} else {
+					useDirectIPPortForwarding = b
 				}
-				// Check if the host part of guestAddress is either unspecified address or matches the known guest IP.
-				// If so, replace it with the known guest IP to avoid issues with dual-stack setups and DNS resolution.
-				// Otherwise, fall back to the gRPC tunnel.
-				if host, _, err := net.SplitHostPort(guestAddress); err != nil {
-					return nil, err
-				} else if ip := net.ParseIP(host); ip.IsUnspecified() || ip.Equal(guestIPv4) || ip.Equal(guestIPv6) {
-					if ip.To4() != nil {
-						if guestIPv4 != nil {
-							conn, err := DialContextToGuestIP(guestIPv4)(ctx, network, guestAddress)
-							if err == nil {
-								return conn, nil
+			}
+			var dialContext func(ctx context.Context, network string, guestAddress string) (net.Conn, error)
+			if useDirectIPPortForwarding {
+				logrus.Warn("Direct IP Port forwarding is enabled. It may fall back to GRPC Port Forwarding in some cases.")
+				dialContext = func(ctx context.Context, network, guestAddress string) (net.Conn, error) {
+					guestIPv4, guestIPv6 := a.GuestIPs()
+					if guestIPv4 == nil && guestIPv6 == nil {
+						return portfwd.DialContextToGRPCTunnel(client)(ctx, network, guestAddress)
+					}
+					// Check if the host part of guestAddress is either unspecified address or matches the known guest IP.
+					// If so, replace it with the known guest IP to avoid issues with dual-stack setups and DNS resolution.
+					// Otherwise, fall back to the gRPC tunnel.
+					if host, _, err := net.SplitHostPort(guestAddress); err != nil {
+						return nil, err
+					} else if ip := net.ParseIP(host); ip.IsUnspecified() || ip.Equal(guestIPv4) || ip.Equal(guestIPv6) {
+						if ip.To4() != nil {
+							if guestIPv4 != nil {
+								conn, err := DialContextToGuestIP(guestIPv4)(ctx, network, guestAddress)
+								if err == nil {
+									return conn, nil
+								}
+								logrus.WithError(err).Warn("failed to connect to the guest IPv4 directly, falling back to gRPC tunnel")
 							}
-							logrus.WithError(err).Warn("failed to connect to the guest IPv4 directly, falling back to gRPC tunnel")
-						}
-					} else if ip.To16() != nil {
-						if guestIPv6 != nil {
-							conn, err := DialContextToGuestIP(guestIPv6)(ctx, network, guestAddress)
-							if err == nil {
-								return conn, nil
+						} else if ip.To16() != nil {
+							if guestIPv6 != nil {
+								conn, err := DialContextToGuestIP(guestIPv6)(ctx, network, guestAddress)
+								if err == nil {
+									return conn, nil
+								}
+								logrus.WithError(err).Warn("failed to connect to the guest IPv6 directly, falling back to gRPC tunnel")
 							}
-							logrus.WithError(err).Warn("failed to connect to the guest IPv6 directly, falling back to gRPC tunnel")
 						}
+						// If we reach here, it means we couldn't find a suitable guest IP
 					}
-					// If we reach here, it means we couldn't find a suitable guest IP
+					return portfwd.DialContextToGRPCTunnel(client)(ctx, network, guestAddress)
 				}
-				return portfwd.DialContextToGRPCTunnel(client)(ctx, network, guestAddress)
+			} else {
+				dialContext = portfwd.DialContextToGRPCTunnel(client)
 			}
 			a.grpcPortForwarder.OnEvent(ctx, dialContext, ev)
 		}

pkg/hostagent/requirements.go

@@ -150,6 +150,7 @@ If any private key under ~/.ssh is protected with a passphrase, you need to have
 			noMaster: true,
 		},
 	)
+
 	if runtime.GOOS == "darwin" {
 		// Limit the Guest IP address detection only to macOS for now.
 		req = append(req,

website/content/en/docs/config/environment-variables.md

@@ -140,6 +140,19 @@ This page documents the environment variables used in Lima.
   export LIMA_USERNET_RESOLVE_IP_ADDRESS_TIMEOUT=5
   ```
 
+### `_LIMA_DIRECT_IP_PORT_FORWARDER`
+
+- **Description**: Specifies to use direct IP port forwarding instead of gRPC.
+- **Default**: `false`
+- **Usage**: 
+  ```sh
+  export _LIMA_DIRECT_IP_PORT_FORWARDER=true
+  ```
+- **Note**: Direct IP port forwarding may fall back to gRPC port forwarding in some cases:
+  - If the guest's IP address is not available, Lima falls back to gRPC port forwarding.
+  - If the guest's IP address is available but the connection to the guest's IP address fails, Lima also falls back to gRPC port forwarding.
+  - If the guest's IP address is not accessible from the host (e.g. localhost on guest), Lima falls back to gRPC port forwarding as well.
+
 ### `_LIMA_QEMU_UEFI_IN_BIOS`
 
 - **Description**: Commands QEMU to load x86_64 UEFI images using `-bios` instead of `pflash` drives.

website/content/en/docs/config/port.md

@@ -88,6 +88,22 @@ lima ip addr show lima0
 
 See [Config » Network » VMNet networks](./network/vmnet.md) for the further information.
 
+### Direct IP Port Forwarding
+
+To enable direct IP port forwarding, set the `_LIMA_DIRECT_IP_PORT_FORWARDER` environment variable to `true`:
+
+```bash
+export _LIMA_DIRECT_IP_PORT_FORWARDER=true
+```
+This feature makes Lima to use direct IP port forwarding instead of gRPC port forwarding.
+When this feature is enabled, Lima tries to connect to the guest's IP address directly for port forwarding.
+
+#### Fallback to gRPC Port Forwarding
+Lima may fall back to gRPC port forwarding in the following cases:
+- If the guest's IP address is not available, Lima falls back to gRPC port forwarding.
+- If the guest's IP address is available but the connection to the guest's IP address fails, Lima also falls back to gRPC port forwarding.
+- If the guest's IP address is not accessible from the host (e.g. localhost on guest), Lima falls back to gRPC port forwarding as well.
+
 ## Benchmarks
 
 <!-- When updating the benchmark result, make sure to update the benchmarking environment too -->