vagrant_utm 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c22d83ed499aea91dd64bc9cdfa9f161a690e510e1e8c28fa9d912a2a0478606
-  data.tar.gz: c4f0be1c3eefa6d8412e60d7f193e00426462a34b90e34016539a75b34195da1
+  metadata.gz: e58e1f0313976a35281a3233fe67d4150f84c8ec51ed41c2ca55256ba9cae05e
+  data.tar.gz: b5b234e460ef8517720492d3b5695cf771cd52efdd0a60c172ec3d644931b535
 SHA512:
-  metadata.gz: 4539bf98ad765bb41946fc1b825e24161ad05e1e56b0b63416521c17c60ec182a78b6a5b6115fc8eea75879ba863c04468fe9881bd7996e928902fe7150198f1
-  data.tar.gz: 430329351ee74c943093194d6d64ce3e230bc8677153337e0f342a3f5c448f4b76bb390d51c6fe817f7cd09d1197185421bd7a97027b9f2869efff04cdada695
+  metadata.gz: fb95231d43a7f9731d7b36823ff7e991b5e11c9113a60590120b21fcd0d6b420116fe7d39e3465e579e5c1548071d562b50b94142c5f4bb689d13c24a671271b
+  data.tar.gz: b3a7b1655c81f270c6aa8399668fcfd5862201f9d00e9532ba00b7e9609e2d6dc7b5a986b502fd447b39dd303bb92ce1b9f513b7c09e2fa2ccf4a801de5878c4

data/CHANGELOG.md

@@ -1,5 +1,45 @@
-## [Unreleased]
+## [0.1.1] - 2024-12-03 
 
-## [0.1.0] - 2024-07-13
+IMPORTANT: This version of the plugin only works with UTM version 4.5.1 and above, and is incompatible with 0.0.1 version of the plugin.
 
-- Initial release
+### Added
+
+- command: add new vagrant command `vagrant ip-address` (9252020)
+- command: add help messages to custom plugin commands (a35466f)
+- action: Set mac address when bringing up new machine (0efe15b) 
+
+### Changed
+
+- plugin: Make config.vm.box mandatory for this plugin (b5be5e8)
+
+### Fixed
+
+- disposable: allow disposable start only for machines already created (cbf591e)
+- up: Set given mac address or random mac address for first interface of a machine to get different IPs of a same base box. 
+
+### Removed
+
+- Driver: Removed support for UTM version 4.5.x (9aea46e)
+
+## [0.1.0] (Beta) - 2024-11-30
+
+IMPORTANT: This version of the plugin only works with UTM version 4.5.1 and above, and is incompatible with previous versions of the plugin.
+
+### Added
+
+- driver: add new driver for UTM version 4.6.x (13d0ca0)
+- vagrant: add vagrant box support (f7accad)
+- command: support `vagrant package` command (39fb5a5)
+
+
+### Removed
+
+- Drop support for `utm_file_url` from provider config (4fb0ac0)
+- Remove support for importing utm files in zip format (c988671)
+
+
+
+## [0.0.1] (Pilot release) - 2024-08-08 
+
+* Initial release with all basic vagrant commands
+* Uses UTM file in zip format from a url as VM box to import

data/docs/boxes/creating_utm_box.md

@@ -8,6 +8,23 @@ nav_order: 2
 
 As with [every Vagrant Provider](https://developer.hashicorp.com/vagrant/docs/providers/basic_usage), the Vagrant UTM provider has a custom box format that is required to work with Vagrant and the UTM plugin.
 
+## UTM Vagrant box format
+
+UTM file (in macOS) is a directory containing Data/qcow2 (s), Data/efi_vars.fd and config.plist.
+Vagrant Box format will require additional metadata.json file. 
+
+Vagrant .box is a tar file
+
+The contents of a `utm/ubuntu-24.04` vagrant box.
+```bash
+$tar -tf ubuntu-24.04.box 
+Vagrantfile
+box.utm/Data/7FB247A3-DC9F-4A61-A123-0AEE1BEEC636.qcow2
+box.utm/Data/efi_vars.fd
+box.utm/config.plist
+box.utm/screenshot.png
+metadata.json
+```
 
 {: .warning } 
 This is a reasonably advanced topic that a beginning user of Vagrant does not need to understand. If you are just getting started with Vagrant, skip this and use an [available box](/utm_box_gallery.md). If you are an experienced user of Vagrant and want to create your own custom boxes, this is for you.
@@ -16,9 +33,16 @@ This is a reasonably advanced topic that a beginning user of Vagrant does not ne
 
 The virtual machine created in UTM can use any configuration you would like, but Vagrant has some hard requirements:
 
-* The second network interface (adapter 1 or index 1) must be a `Emulated VLAN` adapter. Vagrant uses this to connect the first time.
+* The first network interface (adapter 1 or index 0) must be `Shared Network`, which is recommended for new virtual machines. 
+
+We use 'Shared Network' as a NAT equivalent in Vagrant.
+
+* The second network interface (adapter 2 or index 1) must be a `Emulated VLAN` adapter. Vagrant uses this to connect the first time via forwarded ports.
+
+We use 'Emulated VLAN' to achieve port forwarding.
+
+
 
-* Use can use the first network interface (adapter 0 or index 0) to be `Shared Network`, which is recommended for new virtual machines. 
 
 Other than the above, you are free to customize the base virtual machine as you see fit.
 

data/docs/commands.md

@@ -141,6 +141,14 @@ Import VM (if not created)
 
 These are the commands not available in vagrant but specific to UTM provider.
 
+## IP Address
+
+**Command: `vagrant ip-address [name|id]`**
+
+`utmctl ip-address`
+
+List all IP addresses associated with network interfaces on the guest.
+
 ## Disposable
 
 **Command: `vagrant disposable [name|id]`**

data/lib/vagrant_utm/action/ip_address.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module VagrantPlugins
+  module Utm
+    module Action
+      # Action to get IP address of machine.
+      class IpAddress
+        def initialize(app, _env)
+          @app = app
+        end
+
+        def call(env) # rubocop:disable Metrics/AbcSize
+          # Get IP address of the machine.
+          env[:ui].warn I18n.t("vagrant_utm.actions.vm.ip_address.reading")
+          guest_ips = env[:machine].provider.driver.read_guest_ip
+
+          if guest_ips.empty?
+            # Inform user that no IP address was found.
+            env[:ui].warn I18n.t("vagrant_utm.actions.vm.ip_address.not_found")
+          else
+            # Show IP address of the machine.
+            env[:ui].info I18n.t("vagrant_utm.actions.vm.ip_address.show")
+            guest_ips.each do |ip|
+              env[:ui].info "  #{ip}"
+            end
+          end
+
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/vagrant_utm/action/match_mac_address.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+module VagrantPlugins
+  module Utm
+    module Action
+      # This action matches the MAC address of the virtual machine to the
+      # configured MAC address in the Vagrantfile.
+      # OR generates a new MAC address if none is set.
+      # This is useful to make sure that different virtual machines
+      # have different MAC addresses.
+      class MatchMACAddress
+        def initialize(app, _env)
+          @app = app
+        end
+
+        def call(env) # rubocop:disable Metrics/AbcSize
+          base_mac = env[:machine].config.vm.base_mac
+          # If we have a base MAC address and not is empty (empty in some default Vagranfile)
+          # then we use that to match
+          if base_mac && !base_mac.empty?
+            # Create the proc which we want to use to modify the virtual machine
+            env[:ui].info I18n.t("vagrant.actions.vm.match_mac.matching")
+            env[:machine].provider.driver.set_mac_address(env[:machine].config.vm.base_mac)
+          else
+            env[:ui].info I18n.t("vagrant.actions.vm.match_mac.generating")
+            env[:machine].provider.driver.set_mac_address(nil)
+          end
+
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/vagrant_utm/action.rb

@@ -25,9 +25,11 @@ module VagrantPlugins
       autoload :ForcedHalt, action_root.join("forced_halt")
       autoload :ForwardPorts, action_root.join("forward_ports")
       autoload :Import, action_root.join("import")
+      autoload :IpAddress, action_root.join("ip_address")
       autoload :IsPaused, action_root.join("is_paused")
       autoload :IsRunning, action_root.join("is_running")
       autoload :IsStopped, action_root.join("is_stopped")
+      autoload :MatchMACAddress, action_root.join("match_mac_address")
       autoload :MessageAlreadyRunning, action_root.join("message_already_running")
       autoload :MessageNotCreated, action_root.join("message_not_created")
       autoload :MessageNotRunning, action_root.join("message_not_running")
@@ -140,6 +142,23 @@ module VagrantPlugins
         end
       end
 
+      # This action returns ip address of the machine.
+      # UTM equivalent of `utmctl ip-address <uuid>`
+      def self.action_ip_address
+        Vagrant::Action::Builder.new.tap do |b|
+          b.use CheckUtm
+          b.use ConfigValidate
+          b.use Call, IsRunning do |env1, b2|
+            unless env1[:result]
+              b2.use MessageNotRunning
+              next
+            end
+            # If the VM is running, then get the IP address.
+            b2.use IpAddress
+          end
+        end
+      end
+
       # This action packages the virtual machine into a single box file.
       def self.action_package
         Vagrant::Action::Builder.new.tap do |b|
@@ -351,12 +370,14 @@ module VagrantPlugins
         end
       end
 
-      # This action start VM in disposable mode.
+      # This action starts VM in disposable mode.
       # UTM equivalent of `utmctl start <uuid> --disposable`
       def self.action_start_disposable
         Vagrant::Action::Builder.new.tap do |b|
           b.use CheckUtm
           b.use ConfigValidate
+          b.use CheckCreated
+
           b.use Call, IsRunning do |env1, b2|
             if env1[:result]
               b2.use MessageAlreadyRunning
@@ -405,6 +426,7 @@ module VagrantPlugins
               b2.use Customize, "pre-import"
 
               b2.use Import
+              b2.use MatchMACAddress
             end
           end
 

data/lib/vagrant_utm/commands/disposable.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module VagrantPlugins
+  module Utm
+    # Run VM as a snapshot and do not save changes to disk.
+    class CommandDisposable < Vagrant.plugin(2, :command)
+      def self.synopsis
+        "UTM: boots machine in UTM disposable mode"
+      end
+
+      def execute
+        opts = OptionParser.new do |o|
+          o.banner = "Usage: vagrant disposable [name|id]"
+        end
+
+        # Parse the options
+        argv = parse_options(opts)
+        return unless argv
+
+        with_target_vms do |machine|
+          machine.action(:start_disposable)
+        end
+
+        # Success, exit status 0
+        0
+      end
+    end
+  end
+end

data/lib/vagrant_utm/commands/ip_address.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module VagrantPlugins
+  module Utm
+    # Get All IP Adress of a machine.
+    class CommandIpAddress < Vagrant.plugin(2, :command)
+      def self.synopsis
+        "UTM: outputs ip address of the vagrant machine"
+      end
+
+      def execute
+        opts = OptionParser.new do |o|
+          o.banner = "Usage: vagrant ip-address [name|id]"
+        end
+
+        # Parse the options
+        argv = parse_options(opts)
+        return unless argv
+
+        with_target_vms do |machine|
+          machine.action(:ip_address)
+        end
+
+        0
+      end
+    end
+  end
+end

data/lib/vagrant_utm/driver/base.rb

@@ -86,9 +86,10 @@ module VagrantPlugins
         # @return [Array]
         def read_used_ports(active_only: true); end
 
-        # Returns the IP address of the guest machine.
+        # Returns the  IP addresses of the guest machine.
+        # Only supported for VMs with qemu-guest-agent installed.
         #
-        # @return [String] The IP address of the guest machine.
+        # @return [Array<String>] The IP addresses of the guest machine.
         def read_guest_ip; end
 
         # Returns a list of network interfaces of the VM.
@@ -96,6 +97,11 @@ module VagrantPlugins
         # @return [Hash]
         def read_network_interfaces; end
 
+        # Sets the MAC address of the first network adapter.
+        #
+        # @param [String] mac MAC address without any spaces/hyphens.
+        def set_mac_address(mac); end # rubocop:disable Naming/AccessorMethodName
+
         # Execute the 'list' command and returns the list of machines.
         # @return [ListResult] The list of machines.
         def list; end
@@ -142,6 +148,21 @@ module VagrantPlugins
         # This should raise a VagrantError if things are not ready.
         def verify!; end
 
+        # Generate a random MAC address.
+        #
+        # This method generates a random MAC address because it is difficult
+        # to get UTM to generate one through scripting.
+        #
+        # @return [String] The MAC address.
+        def random_mac_address
+          # Generate 6 random bytes
+          bytes = Array.new(6) { rand(256) }
+          # Ensure the first byte is local
+          bytes[0] = (bytes[0] & 0xFC) | 0x02
+          # Convert bytes to MAC address string
+          bytes.map { |byte| format("%02X", byte) }.join(":")
+        end
+
         # Execute a script using the OSA interface.
         def execute_osa_script(command); end
 

data/lib/vagrant_utm/driver/meta.rb

@@ -55,13 +55,12 @@ module VagrantPlugins
           # Instantiate the proper version driver for UTM
           @logger.debug("Finding driver for UTM version: #{@version}")
           driver_map = {
-            "4.5" => Version_4_5,
             "4.6" => Version_4_6
           }
 
-          # UTM 4.5.0 just doesn't work with Vagrant (https://github.com/utmapp/UTM/issues/5963),
+          # UTM 4.6.0  doesn't have import support to work with Vagrant box,
           # so show error
-          raise Errors::UtmInvalidVersion if @version.start_with?("4.5.0")
+          raise Errors::UtmInvalidVersion if @version.start_with?("4.6.0")
 
           driver_klass = nil
           driver_map.each do |key, klass|
@@ -106,6 +105,7 @@ module VagrantPlugins
                        :read_state,
                        :read_used_ports,
                        :restore_snapshot,
+                       :set_mac_address,
                        :set_name,
                        :ssh_port,
                        :start,

data/lib/vagrant_utm/driver/version_4_5.rb

@@ -174,9 +174,8 @@ module VagrantPlugins
         end
 
         def read_guest_ip
-          command = ["read_guest_ip.applescript", @uuid]
-          output = execute_osa_script(command)
-          output.strip
+          output = execute("ip-address", @uuid)
+          output.strip.split("\n")
         end
 
         def read_network_interfaces
@@ -195,6 +194,14 @@ module VagrantPlugins
           nics
         end
 
+        def set_mac_address(mac) # rubocop:disable Naming/AccessorMethodName
+          # Set the MAC address of the first NIC (index 0)
+          # Set MAC address to given value or randomize it if nil
+          mac = random_mac_address if mac.nil?
+          command = ["set_mac_address.applescript", @uuid, "0", mac]
+          execute_osa_script(command)
+        end
+
         def ssh_port(expected_port)
           @logger.debug("Searching for SSH port: #{expected_port.inspect}")
 

data/lib/vagrant_utm/model/forwarded_port.rb

@@ -57,7 +57,9 @@ module VagrantPlugins
           options ||= {}
           @auto_correct = false
           @auto_correct = options[:auto_correct] if options.key?(:auto_correct)
-          @adapter  = (options[:adapter] || 1).to_i # if adapter is not set, use 1. index 0 is the default adapter
+          # if adapter is not set, use index 1 (Emulated VLAN).
+          # index 0 is the default adapter (Shared Network)
+          @adapter  = (options[:adapter] || 1).to_i
           @guest_ip = options[:guest_ip] || nil
           @host_ip = options[:host_ip] || nil
           @protocol = options[:protocol] || "tcp" # default to TCP

data/lib/vagrant_utm/plugin.rb

@@ -21,12 +21,7 @@ module VagrantPlugins
       DESCRIPTION
 
       # Register the provider
-      # TODO: Define box format for UTM
-      # IDEA: UTM file comes as a zip file containing
-      # directory with Data/qcow2, Data/efi_vars.fd and config.plist
-      # Box format will only require additional metadata.json file
-      # Till then use UTM file directly and so box_optional: true
-      provider(:utm, box_optional: true, parallel: false) do
+      provider(:utm, box_optional: false, parallel: false) do
         setup_i18n
         require_relative "provider"
         Provider
@@ -50,9 +45,17 @@ module VagrantPlugins
       end
 
       # Register the command
+      ## Start machine as a snapshot and do not save changes to disk
       command "disposable" do
-        require_relative "disposable"
-        Disposable
+        require_relative "commands/disposable"
+        CommandDisposable
+      end
+
+      ## Get the IP address of the machine
+      ## Only supported if machine as qemu-guest-additions
+      command "ip-address" do
+        require_relative "commands/ip_address"
+        CommandIpAddress
       end
 
       # Load the translation files

data/lib/vagrant_utm/provider.rb

@@ -94,6 +94,8 @@ module VagrantPlugins
         # If we have multiple network adapters, we need to pick the right one, read_guest_ip returns just first IP
         # Also, since Vagrant by default adds port forwarding for ssh port 22,
         # we might aswell use the forwarded ports to connect to the VM using the localhost.
+        # and the forwarded port.
+        # So we use 127.0.0.1 and the forwarded port to connect to the VM.
         {
           host: "127.0.0.1",
           port: @driver.ssh_port(@machine.config.ssh.guest_port)
@@ -124,7 +126,6 @@ module VagrantPlugins
         Vagrant::MachineState.new(state_id, short, long)
       end
 
-      # TODO: Get UUID of the VM from UTM
       # Returns a human-friendly string version of this provider which
       # includes the machine's ID that this provider represents, if it
       # has one.

data/lib/vagrant_utm/scripts/read_network_interfaces.applescript

@@ -5,7 +5,8 @@ on run argv
         set config to configuration of vm
         set networkInterfaces to network interfaces of config
         repeat with anInterface in networkInterfaces
-            # if you start log with variable you'll get "," at the end of the log if '&' is used to concatenate
+            # if you start log with variable you'll get "," at the end of the log so '&' is used to concatenate
+            # Example output: nic0,shared
             log "nic" & index of anInterface & "," & mode of anInterface 
         end repeat
     end tell

data/lib/vagrant_utm/scripts/set_mac_address.applescript

@@ -0,0 +1,25 @@
+# This script sets the MAC address of a network interface in a specified UTM virtual machine.
+# Usage: osascript set_mac_address.applescript <VM_UUID> <NIC_INDEX> <MAC_ADDRESS>
+# Example: osascript set_mac_address.applescript A123 1 XX:XX:XX:XX:XX:XX
+on run argv
+  set vmID to item 1 of argv
+  set nicIndex to item 2 of argv
+  set macAddress to item 3 of argv
+
+  tell application "UTM"
+    set vm to virtual machine id vmID
+    set config to configuration of vm
+    set networkInterfaces to network interfaces of config
+
+    repeat with anInterface in networkInterfaces
+      if nicIndex as integer is index of anInterface then
+        -- Set the provided MAC address
+        set address of anInterface to macAddress
+      end if
+    end repeat
+
+    -- Update the VM configuration
+    update configuration of vm with config
+  end tell
+  
+end run

data/lib/vagrant_utm/version.rb

@@ -4,6 +4,6 @@ module VagrantPlugins
   # Top level module for the Utm provider plugin.
   module Utm
     # Current version of the Utm provider plugin.
-    VERSION = "0.1.0"
+    VERSION = "0.1.1"
   end
 end

data/locales/en.yml

@@ -149,7 +149,15 @@ en:
             WARNING: The UTM virtual machine is booting in disposable mode. 
             Changes made to the VM will be lost when the VM is powered off.
             Learn more at https://docs.getutm.app/advanced/disposable/
+        ip_address:
+          reading: |-
+            Getting IP address of UTM virtual machine...
+          show: |-
+            Guest IP address(es):
+          not_found: |-
+            IP address not found. The VM may not have guest tools or may not have an IP address.
         snapshot:
           list: |-
             Listing snapshots for UTM virtual machine...
+        
             

data/notes/README.md

@@ -19,4 +19,12 @@ bundle exec jekyll serve
 To release 
 
 To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`
-GitHub action upon tag push with "v*" will publish gem to GHR and rubygems
+GitHub action upon tag push with "v*" will publish gem to GHR and rubygems
+
+1. Update the version number in `version.rb`
+2. Run `bundle exec rake release`
+3. Commit version and Gemlock file
+4. Run `bundle exec rake release` again
+5. Cancel push to rubygems.org 
+
+GHA will publish gems to GHR and rubygems

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vagrant_utm
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Naveenraj M
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-11-30 00:00:00.000000000 Z
+date: 2024-12-03 00:00:00.000000000 Z
 dependencies: []
 description: Vagrant UTM provider that allows you to manage UTM virtual machines.
 email:
@@ -68,9 +68,11 @@ files:
 - lib/vagrant_utm/action/forced_halt.rb
 - lib/vagrant_utm/action/forward_ports.rb
 - lib/vagrant_utm/action/import.rb
+- lib/vagrant_utm/action/ip_address.rb
 - lib/vagrant_utm/action/is_paused.rb
 - lib/vagrant_utm/action/is_running.rb
 - lib/vagrant_utm/action/is_stopped.rb
+- lib/vagrant_utm/action/match_mac_address.rb
 - lib/vagrant_utm/action/message_already_running.rb
 - lib/vagrant_utm/action/message_not_created.rb
 - lib/vagrant_utm/action/message_not_running.rb
@@ -91,8 +93,9 @@ files:
 - lib/vagrant_utm/action/suspend.rb
 - lib/vagrant_utm/action/wait_for_running.rb
 - lib/vagrant_utm/cap.rb
+- lib/vagrant_utm/commands/disposable.rb
+- lib/vagrant_utm/commands/ip_address.rb
 - lib/vagrant_utm/config.rb
-- lib/vagrant_utm/disposable.rb
 - lib/vagrant_utm/driver/base.rb
 - lib/vagrant_utm/driver/meta.rb
 - lib/vagrant_utm/driver/version_4_5.rb
@@ -111,8 +114,8 @@ files:
 - lib/vagrant_utm/scripts/list_vm.js
 - lib/vagrant_utm/scripts/open_with_utm.js
 - lib/vagrant_utm/scripts/read_forwarded_ports.applescript
-- lib/vagrant_utm/scripts/read_guest_ip.applescript
 - lib/vagrant_utm/scripts/read_network_interfaces.applescript
+- lib/vagrant_utm/scripts/set_mac_address.applescript
 - lib/vagrant_utm/util/compile_forwarded_ports.rb
 - lib/vagrant_utm/version.rb
 - locales/en.yml

data/lib/vagrant_utm/disposable.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-module VagrantPlugins
-  module Utm
-    # Run VM as a snapshot and do not save changes to disk.
-    class Disposable < Vagrant.plugin(2, :command)
-      def execute
-        with_target_vms do |machine|
-          machine.action(:start_disposable)
-        end
-
-        0
-      end
-    end
-  end
-end

data/lib/vagrant_utm/scripts/read_guest_ip.applescript

@@ -1,9 +0,0 @@
-on run argv
-  set vmID to item 1 of argv
-  tell application "UTM"
-      set vm to virtual machine id vmID
-      --- get IP address (QEMU Guest Agent must be installed) of first interface
-      get item 1 of (query ip of vm) -- Result: "192.168.64.9"
-  end tell
-end run
-