Merge pull request #139 from AkihiroSuda/dev-machineid

AkihiroSuda · web-flow · commit 874786d080a5 · 2021-08-05T11:51:58.000+09:00
Put machineID to the MAC address hasher + update docs + misc
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -70,8 +70,8 @@ jobs:
         run: make
       - name: Install
         run: sudo make install
-      - name: Validate examples
-        run: limactl validate ./examples/*.yaml
+      - name: Validate examples (except vmnet.yaml)
+        run: find examples -name '*.yaml' | grep -v 'vmnet.yaml' | xargs limactl validate
       - name: Uninstall
         run: sudo make uninstall
 
@@ -81,9 +81,9 @@ jobs:
     timeout-minutes: 40
     strategy:
       matrix:
-        # GHA macOS is slow and flaky, so we only test "default.yaml" here.
+        # GHA macOS is slow and flaky, so we only test a few YAMLS here.
         # Other yamls are tested on Linux instances of Cirrus.
-        example: [default.yaml]
+        example: [default.yaml, vmnet.yaml]
     steps:
       - uses: actions/setup-go@v2
         with:
@@ -100,6 +100,16 @@ jobs:
         # bash:      required by test-example.sh (OS version of bash is too old)
         # coreutils: required by test-example.sh for the "timeout" command
         run: brew install qemu bash coreutils
+      - name: Install vde_vmnet
+        if: matrix.example == 'vmnet.yaml'
+        env:
+          VDE_VMNET_VERSION: v0.4.0
+        run: |
+          git clone https://github.com/lima-vm/vde_vmnet
+          cd vde_vmnet
+          git checkout $VDE_VMNET_VERSION
+          make
+          sudo make install
       - name: Prepare ssh
         run: |
           if [ -e ~/.ssh/id_rsa ]; then
diff --git a/README.md b/README.md
@@ -202,6 +202,8 @@ The current default spec:
   - ["Port forwarding does not work"](#port-forwarding-does-not-work)
   - [stuck on "Waiting for the essential requirement 1 of X: "ssh"](#stuck-on-waiting-for-the-essential-requirement-1-of-x-ssh)
   - ["permission denied" for `limactl cp` command](#permission-denied-for-limactl-cp-command)
+- [Networking](#networking)
+  - ["Cannot access the guest IP 192.168.5.15 from the host"](#cannot-access-the-guest-ip-192168515-from-the-host)
 - ["Hints for debugging other problems?"](#hints-for-debugging-other-problems)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -304,6 +306,15 @@ The `copy` command only works for instances that have been created by lima 0.5.0
 < ~/.lima/_config/user.pub limactl shell INSTANCE sh -c 'tee -a ~/.ssh/authorized_keys'
 ```
 
+### Networking
+#### "Cannot access the guest IP 192.168.5.15 from the host"
+
+The default guest IP 192.168.5.15 is not accessible from the host and other guests.
+
+To add another IP address that is accessible from the host and other virtual machines, enable [`vde_vmnet`](https://github.com/lima-vm/vde_vmnet).
+
+See [`./docs/network.md`](./docs/network.md).
+
 ### "Hints for debugging other problems?"
 - Inspect logs:
   - `limactl --debug start`
diff --git a/docs/internal.md b/docs/internal.md
@@ -85,6 +85,7 @@ The directory contains the following files:
 
 - `user-data`: [Cloud-init user-data](https://cloudinit.readthedocs.io/en/latest/topics/format.html)
 - `meta-data`: [Cloud-init meta-data](https://cloudinit.readthedocs.io/en/latest/topics/instancedata.html)
+- `network-config`: [Cloud-init Networking Config Version 2](https://cloudinit.readthedocs.io/en/latest/topics/network-config-format-v2.html)
 - `lima.env`: the environment variables
 - `lima-guestagent`: Lima guest agent binary
 - `nerdctl-full.tgz`: [`nerdctl-full-<VERSION>-linux-<ARCH>.tar.gz`](https://github.com/containerd/nerdctl/releases)
diff --git a/docs/network.md b/docs/network.md
@@ -0,0 +1,48 @@
+# Network
+
+## user-mode network (192.168.5.0/24)
+
+By default Lima only enables the user-mode networking aka "slirp".
+
+### Guest IP (192.168.5.15)
+
+The guest IP address is typically set to 192.168.5.15.
+
+This IP address is not accessible from the host by design.
+
+Use `vde_vmnet` to allow accessing the guest IP from the host and other guests.
+
+### Host IP (192.168.5.2)
+
+The loopback addresses of the host is accessible from the guest as 192.168.5.2.
+
+### DNS (192.168.5.3)
+
+The DNS.
+
+## `vde_vmnet` (192.168.105.0/24)
+
+[`vde_vmnet`](https://github.com/lima-vm/vde_vmnet) is required for adding another guest IP that is accessible from
+the host and other guests.
+
+To enable `vde_vmnet` (in addition the user-mode network), add the following lines to the YAML after installing `vde_vmnet`.
+
+```yaml
+network:
+  # The instance can get routable IP addresses from the vmnet framework using
+  # https://github.com/lima-vm/vde_vmnet. Both vde_switch and vde_vmnet
+  # daemons must be running before the instance is started. The interface type
+  # (host, shared, or bridged) is configured in vde_vmnet and not lima.
+  vde:
+    # vnl (virtual network locator) points to the vde_switch socket directory,
+    # optionally with vde:// prefix
+    - vnl: "vde:///var/run/vde.ctl"
+      # MAC address of the instance; lima will pick one based on the instance name,
+      # so DHCP assigned ip addresses should remain constant over instance restarts.
+      macAddress: ""
+      # Interface name, defaults to "vde0", "vde1", etc.
+      name: ""
+```
+
+The IP address range is typically `192.168.105.0/24`, but depends on the configuration of `vde_vmnet`.
+See [the documentation of `vde_vmnet`](https://github.com/lima-vm/vde_vmnet) for further information.
diff --git a/examples/vmnet.yaml b/examples/vmnet.yaml
@@ -0,0 +1,23 @@
+images:
+  # Hint: run `limactl prune` to invalidate the "current" cache
+  - location: "https://cloud-images.ubuntu.com/hirsute/current/hirsute-server-cloudimg-amd64.img"
+    arch: "x86_64"
+  - location: "https://cloud-images.ubuntu.com/hirsute/current/hirsute-server-cloudimg-arm64.img"
+    arch: "aarch64"
+mounts:
+  - location: "~"
+    writable: false
+  - location: "/tmp/lima"
+    writable: true
+ssh:
+  # localPort is changed from 60022 to avoid conflicting with the default.
+  # (TODO: assign localPort automatically)
+  localPort: 60105
+
+network:
+  # The instance can get routable IP addresses from the vmnet framework using
+  # https://github.com/lima-vm/vde_vmnet. Both vde_switch and vde_vmnet
+  # daemons must be running before the instance is started. The interface type
+  # (host, shared, or bridged) is configured in vde_vmnet and not lima.
+  vde:
+    - vnl: "vde:///var/run/vde.ctl"
diff --git a/pkg/limayaml/default.yaml b/pkg/limayaml/default.yaml
@@ -1,3 +1,7 @@
+# ===================================================================== #
+# BASIC CONFIGURATION
+# ===================================================================== #
+
 # Arch: "default", "x86_64", "aarch64".
 # "default" corresponds to the host architecture.
 arch: "default"
@@ -31,20 +35,6 @@ memory: "4GiB"
 # Default: "100GiB"
 disk: "100GiB"
 
-network:
-  # The instance can get routable IP addresses from the vmnet framework using
-  # https://github.com/AkihiroSuda/vde_vmnet. Both vde_switch and vde_vmnet
-  # daemons must be running before the instance is started. The interface type
-  # (host, shared, or bridged) is configured in vde_vmnet and not lima.
-  vde:
-    # url points to the vde_switch socket directory
-    # - url: "/var/run/vde.ctl"
-    #   # MAC address of the instance; lima will pick one based on the instance name,
-    #   # so DHCP assigned ip addresses should remain constant over instance restarts.
-    #   macAddress: ""
-    #   # Interface name, defaults to "vde0", "vde1", etc.
-    #   name: ""
-
 # Expose host directories to the guest
 # Default: none
 mounts:
@@ -67,17 +57,9 @@ ssh:
   # Default: true
   loadDotSSHPubKeys: true
 
-firmware:
-  # Use legacy BIOS instead of UEFI.
-  # Default: false
-  legacyBIOS: false
-
-video:
-  # QEMU display, e.g., "none", "cocoa", "sdl".
-  # As of QEMU v5.2, enabling this is known to have negative impact
-  # on performance on macOS hosts: https://gitlab.com/qemu-project/qemu/-/issues/334
-  # Default: "none"
-  display: "none"
+# ===================================================================== #
+# ADVANCED CONFIGURATION
+# ===================================================================== #
 
 containerd:
   # Enable system-wide (aka rootful)  containerd and its dependencies (BuildKit, Stargz Snapshotter)
@@ -87,32 +69,6 @@ containerd:
   # Default: true
   user: true
 
-# Port forwarding rules. Forwarding between ports 22 and ssh.localPort cannot be overridden.
-# Rules are checked sequentially until the first one matches.
-# portForwards:
-#   - guestPort: 443
-#     hostIP: "0.0.0.0" # overrides the default value "127.0.0.1"; allows privileged port forwarding
-#   # default: hostPort: 443 (same as guestPort)
-#   # default: guestIP: "127.0.0.1" (also matches bind addresses "0.0.0.0", "::", and "::1")
-#   # default: proto: "tcp" (only valid value right now)
-#   - guestPortRange: [4000, 4999]
-#     hostIP:  "0.0.0.0" # overrides the default value "127.0.0.1"
-#   # default: hostPortRange: [4000, 4999] (must specify same number of ports as guestPortRange)
-#   - guestPort: 80
-#     hostPort: 8080 # overrides the default value 80
-#   - guestIP: "127.0.0.2" # overrides the default value "127.0.0.1"
-#     hostIP: "127.0.0.2" # overrides the default value "127.0.0.1"
-#   # default: guestPortRange: [1024, 65535]
-#   # default: hostPortRange: [1024, 65535]
-#   - guestPort: 8888
-#     ignore: true (don't forward this port)
-#   # Lima internally appends this fallback rule at the end:
-#   - guestIP: "127.0.0.1"
-#     guestPortRange: [1024, 65535]
-#     hostIP: "127.0.0.1"
-#     hostPortRange: [1024, 65535]
-#   # Any port still not matched by a rule will not be forwarded (ignored)
-
 # Provisioning scripts need to be idempotent because they might be called
 # multiple times, e.g. when the host VM is being restarted.
 # provision:
@@ -146,3 +102,68 @@ containerd:
 #    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
+# ===================================================================== #
+
+firmware:
+  # Use legacy BIOS instead of UEFI.
+  # Default: false
+  legacyBIOS: false
+
+video:
+  # QEMU display, e.g., "none", "cocoa", "sdl".
+  # As of QEMU v5.2, enabling this is known to have negative impact
+  # on performance on macOS hosts: https://gitlab.com/qemu-project/qemu/-/issues/334
+  # Default: "none"
+  display: "none"
+
+network:
+  # The instance can get routable IP addresses from the vmnet framework using
+  # https://github.com/lima-vm/vde_vmnet. Both vde_switch and vde_vmnet
+  # daemons must be running before the instance is started. The interface type
+  # (host, shared, or bridged) is configured in vde_vmnet and not lima.
+  vde:
+    # vnl (virtual network locator) points to the vde_switch socket directory,
+    # optionally with vde:// prefix
+    # - vnl: "vde:///var/run/vde.ctl"
+    #   # VDE Switch port number (not TCP/UDP port number). Set to 65535 for PTP mode.
+    #   # Default: 0
+    #   switchPort: 0
+    #   # MAC address of the instance; lima will pick one based on the instance name,
+    #   # so DHCP assigned ip addresses should remain constant over instance restarts.
+    #   macAddress: ""
+    #   # Interface name, defaults to "vde0", "vde1", etc.
+    #   name: ""
+
+# Port forwarding rules. Forwarding between ports 22 and ssh.localPort cannot be overridden.
+# Rules are checked sequentially until the first one matches.
+# portForwards:
+#   - guestPort: 443
+#     hostIP: "0.0.0.0" # overrides the default value "127.0.0.1"; allows privileged port forwarding
+#   # default: hostPort: 443 (same as guestPort)
+#   # default: guestIP: "127.0.0.1" (also matches bind addresses "0.0.0.0", "::", and "::1")
+#   # default: proto: "tcp" (only valid value right now)
+#   - guestPortRange: [4000, 4999]
+#     hostIP:  "0.0.0.0" # overrides the default value "127.0.0.1"
+#   # default: hostPortRange: [4000, 4999] (must specify same number of ports as guestPortRange)
+#   - guestPort: 80
+#     hostPort: 8080 # overrides the default value 80
+#   - guestIP: "127.0.0.2" # overrides the default value "127.0.0.1"
+#     hostIP: "127.0.0.2" # overrides the default value "127.0.0.1"
+#   # default: guestPortRange: [1024, 65535]
+#   # default: hostPortRange: [1024, 65535]
+#   - guestPort: 8888
+#     ignore: true (don't forward this port)
+#   # Lima internally appends this fallback rule at the end:
+#   - guestIP: "127.0.0.1"
+#     guestPortRange: [1024, 65535]
+#     hostIP: "127.0.0.1"
+#     hostPortRange: [1024, 65535]
+#   # Any port still not matched by a rule will not be forwarded (ignored)
+
+# ===================================================================== #
+# END OF TEMPLATE
+# ===================================================================== #
+
diff --git a/pkg/limayaml/defaults.go b/pkg/limayaml/defaults.go
@@ -8,14 +8,19 @@ import (
 	"strconv"
 
 	"github.com/AkihiroSuda/lima/pkg/guestagent/api"
+	"github.com/AkihiroSuda/lima/pkg/osutil"
 )
 
 func MACAddress(uniqueID string) string {
-	// TODO: combine the uniqueID with the host machineID to create a globally unique hash
-	sha := sha256.Sum256([]byte(uniqueID))
-	// According to https://gitlab.com/wireshark/wireshark/-/blob/master/manuf
-	// no well-known MAC addresses start with 0x22.
-	hw := append(net.HardwareAddr{0x22}, sha[0:5]...)
+	sha := sha256.Sum256([]byte(osutil.MachineID() + uniqueID))
+	// "5" is the magic number in the Lima ecosystem.
+	// (Visit https://en.wiktionary.org/wiki/lima and Command-F "five")
+	//
+	// But the second hex number is changed to 2 to satisfy the convention for
+	// local MAC addresses (https://en.wikipedia.org/wiki/MAC_address#Ranges_of_group_and_locally_administered_addresses)
+	//
+	// See also https://gitlab.com/wireshark/wireshark/-/blob/master/manuf to confirm the uniqueness of this prefix.
+	hw := append(net.HardwareAddr{0x52, 0x55, 0x55}, sha[0:3]...)
 	return hw.String()
 }
 
diff --git a/pkg/limayaml/limayaml.go b/pkg/limayaml/limayaml.go
@@ -111,7 +111,10 @@ type Network struct {
 	VDE []VDE `yaml:"vde,omitempty"`
 }
 type VDE struct {
-	URL        string `yaml:"url,omitempty"`
+	// VNL is a Virtual Network Locator (https://github.com/rd235/vdeplug4/commit/089984200f447abb0e825eb45548b781ba1ebccd).
+	// On macOS, only VDE2-compatible form (optionally with vde:// prefix) is supported.
+	VNL        string `yaml:"vnl,omitempty"`
+	SwitchPort uint16 `yaml:"switchPort,omitempty"` // VDE Switch port, not TCP/UDP port
 	MACAddress string `yaml:"macAddress,omitempty"`
 	Name       string `yaml:"name,omitempty"`
 }
diff --git a/pkg/limayaml/validate.go b/pkg/limayaml/validate.go
diff --git a/pkg/osutil/machineid.go b/pkg/osutil/machineid.go
diff --git a/pkg/osutil/machineid_test.go b/pkg/osutil/machineid_test.go
diff --git a/pkg/qemu/qemu.go b/pkg/qemu/qemu.go

Original file line number	Diff line number	Diff line change
`@@ -111,7 +111,10 @@ type Network struct {`
`111`	`111`	VDE []VDE `yaml:"vde,omitempty"`
`112`	`112`	`}`
`113`	`113`	`type VDE struct {`
`114`		- URL string `yaml:"url,omitempty"`
	`114`	`+ // VNL is a Virtual Network Locator (https://github.com/rd235/vdeplug4/commit/089984200f447abb0e825eb45548b781ba1ebccd).`
	`115`	`+ // On macOS, only VDE2-compatible form (optionally with vde:// prefix) is supported.`
	`116`	+ VNL string `yaml:"vnl,omitempty"`
	`117`	+ SwitchPort uint16 `yaml:"switchPort,omitempty"` // VDE Switch port, not TCP/UDP port
`115`	`118`	MACAddress string `yaml:"macAddress,omitempty"`
`116`	`119`	Name string `yaml:"name,omitempty"`
`117`	`120`	`}`