vagrant_utm 0.0.1

data/docs/configuration.md

@@ -0,0 +1,51 @@
+---
+title: Configuration
+nav_order: 3
+---
+
+# Configuration
+
+The UTM provider exposes some additional configuration options that allow you to more finely control your UTM-powered Vagrant environments.
+
+## Virtual Machine Name
+
+You can customize the name that appears in the UTM GUI by setting the name property. By default, Vagrant sets it to the containing folder of the Vagrantfile plus a timestamp of when the machine was created. By setting another name, your VM can be more easily identified.
+
+```ruby
+config.vm.provider "utm" do |u|
+  u.name = "my_vm"
+end
+```
+
+## Other customization
+
+```ruby
+Vagrant.configure("2") do |config|
+  # Hostname inside the VM
+  config.vm.hostname = "debian"
+  # Ports to forward
+  config.vm.network "forwarded_port", guest: 80, host: 8989
+  # Provider specific configs
+  config.vm.provider "utm" do |u|
+    # Name in UTM UI
+    u.name = "debian"
+    # UTM VM file to import
+    u.utm_file_url = "http://localhost:8000/debian_vagrant_utm.zip"
+    # CPU in cores
+    u.cpus = 1
+    # Memory in MB
+    u.memory = 1024
+    # Notes for UTM VM (Appears in UI)
+    u.notes = "Vagrant: For testing plugin development"
+    # QEMU Directoy Share mode for the VM. 
+    # Takes none, webDAV or virtFS
+    u.directory_share_mode = "webDAV"
+  end
+  # Provisioner config, supports all built provisioners
+  # shell, ansible
+  config.vm.provision "shell", inline: <<-SHELL
+  apt-get update
+  apt-get install -y apache2
+  SHELL
+end
+```

data/docs/features/index.md

@@ -0,0 +1,5 @@
+---
+title: Features
+nav_order: 4
+has_children: true
+---

data/docs/features/synced_folders.md

@@ -0,0 +1,28 @@
+---
+layout: default
+title: Synced Folders
+parent: Features
+nav_order: 1
+---
+
+# Synced Folders
+
+UTM Vagrant plugin currently gives rudimentary support for syncing folders between host and guest machine.
+The plugin provides option to configure the Qemu directory share mode. 
+After which the the host directory can be selected from UTM UI, and the guest directory can be mounted in guest OS. Both of these steps are now manual until UTM exposes API to configure Host/Guest directory.
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.provider :utm do |u|
+    u.utm_file_url = "http://localhost:8000/vm_utm.zip"
+    # QEMU Directoy Share mode for the VM. 
+    # Takes none, webDAV or virtFS
+    u.directory_share_mode = "webDAV"
+  end
+end
+```
+
+## Other Vagrant options
+
+{: .important}
+Apart from the provider specific Sync options, Vagrant has components to provide sync folders feature using NFS and RSync. These features are not yet supported in UTM plugin.

data/docs/index.md

@@ -0,0 +1,103 @@
+---
+title: Home
+layout: home
+nav_order: 1
+description: "Vagrant UTM plugin enables you to manage UTM VMs using Vagrant"
+permalink: /
+---
+
+# Automate your VM setup on Mac
+{: .fs-7 }
+
+vagrant_utm is a [Vagrant][Vagrant] plugin which adds [UTM][UTM] provider to Vagrant, 
+allowing Vagrant to control and provision machines via UTM's API.
+
+
+[Get started now](#getting-started){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 }
+[View it on GitHub][Vagrant UTM repo]{: .btn .fs-5 .mb-4 .mb-md-0 }
+
+---
+
+[UTM] is a free, full featured system emulator and virtual machine host for iOS and macOS.
+The UTM provider currently supports UTM versions 4.5.x (except 4.5.0).
+
+[Vagrant] enables the creation and configuration of lightweight, reproducible, and portable development environments using Vagrantfile. The UTM provider plugin works with Vagrant version 2.4.1 .
+
+
+Both UTM and Vagrant must be installed prior to using this plugin.
+* [Download UTM for Mac](https://mac.getutm.app)
+* [Install Vagrant ](https://developer.hashicorp.com/vagrant/install?product_intent=vagrant)
+
+Browse the docs to learn more about how to use this plugin.
+
+
+## Getting started
+
+Get started with Vagrant UTM plugin in 3 simple steps.  
+Make sure both [Vagrant] and [UTM] are installed before your proceed.
+
+{: .warning}
+UTM Vagrant plugin is built around the existing UTM API. Some steps like Import, Snapshot are not straightforward. Please check [Known Issues](/known_issues.md) before using this plugin.
+
+
+### Install
+
+Install vagrant_utm plugin.
+```bash
+vagrant plugin install vagrant_utm
+```
+
+### Use
+
+Save the below config in your Vagrantfile. 
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.provider :utm do |u|
+    u.utm_file_url = "https://github.com/naveenrajm7/utm-box/releases/download/debian-11/debian_vagrant_utm.zip"
+  end
+end
+```
+
+### Run
+
+Bring up vagrant environment.
+```bash
+vagrant up
+```
+
+
+
+Check [Commands](commands.md) for all supported Vagrant commands.
+Check [Configuration](configuration.md) for more provider config options.
+
+
+## About the project
+
+Vagrant UTM is © {{ "now" | date: "%Y" }} by [Naveenraj Muthuraj](https://naveenrajm7.github.io).
+
+### License
+
+The Vagrant UTM plugin is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT). However, it uses vagrant library and parts of the code from virtualbox plugin both of which are BSL.
+Please be aware of this if you intend on redistributing this plugin. 
+
+### Contributing
+
+Bug reports and pull requests are welcome on GitHub at [Vagrant UTM repo]. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/naveenrajm7/vagrant_utm/blob/main/CODE_OF_CONDUCT.md).
+
+#### Thank you to the contributors of Vagrant UTM Plugin!
+
+<ul class="list-style-none">
+{% for contributor in site.github.contributors %}
+  <li class="d-inline-block mr-1">
+     <a href="{{ contributor.html_url }}"><img src="{{ contributor.avatar_url }}" width="32" height="32" alt="{{ contributor.login }}"></a>
+  </li>
+{% endfor %}
+</ul>
+
+### Code of Conduct
+
+Everyone interacting in the Vagrant UTM project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/naveenrajm7/vagrant_utm/blob/main/CODE_OF_CONDUCT.md).
+
+[Vagrant UTM repo]: https://github.com/naveenrajm7/vagrant_utm
+[UTM]: https://mac.getutm.app
+[Vagrant]: https://www.vagrantup.com

data/docs/internals/actions.md

@@ -0,0 +1,20 @@
+---
+layout: default
+title: Actions
+parent: Internals
+nav_order: 1
+---
+
+The Table below maps the vagrant commands to the corresponding UTM commands that are executed.
+
+| Vagrant               | utmctl / AppleScript |
+| ---                   | ------------------ | 
+| `vagrant up`          | `utmctl start` | 
+| `vagrant halt`        | `utmctl stop` |
+| `vagrant suspend`     | `utmctl suspend` | 
+| `vagrant resume`      | `utmctl start` | 
+| `vagrant reload`      |  update configuration of vm with config |
+| `vagrant destroy`     | `utmctl delete` | 
+| `vagrant status`      | `utmctl status` | 
+| `vagrant disposable`  | `utmctl start --disposable` | 
+| `vagrant snapshot`    | `qemu-img snapshot`         |

data/docs/internals/index.md

@@ -0,0 +1,5 @@
+---
+title: Internals
+nav_order: 5
+has_children: true
+---

data/docs/internals/status.md

@@ -0,0 +1,25 @@
+---
+layout: default
+title: Status
+parent: Internals
+nav_order: 2
+---
+
+The Table below maps the vagrant (virtualbox) status to UTM status.
+
+
+
+| Vagrant/VirtualBox | UTM |
+| --- | --- |
+| poweroff | stopped |
+|  | starting |
+| running | started |
+|  | pausing |
+| paused/saved | paused |
+|  | resuming |
+| stopping | stopping |
+|  | unknown |
+
+{: .warning } 
+UTM does not report the state `running`, which usally means the VM is ready to accept commands.
+Hence, wherever the state `running` is required by Vagrant, we cautiously use the state `started`.

data/docs/internals/utm_api.md

@@ -0,0 +1,31 @@
+---
+layout: default
+title: UTM API
+parent: Internals
+nav_order: 3
+---
+
+The plugin invokes UTM API inorder to implement Vagrant required actions.
+As there are several ways to control UTM, we use the following order
+
+1. UTM Command Line (`utmctl`) 
+2. Apple Scripting Bridge (`osascript`)   
+  2.a Applescript  
+  2.b JavaScript
+3. Shell command
+
+
+**1. UTM Command Line** : Just like virtualbox plugin uses VBoxManage, the goal of this plugin is to use UTM command line tool `utmctl` as single point of control.
+
+**2. Apple Scripting Bridge** :
+However, not all capabilities are currently exposed via `utmctl`.
+So we rely on Apple Scripting Bridge scripts which can be executed using `osascript` binary. 
+When it comes to writing the OSA scripts, our first choice is applescript language due to its simplicity and support.
+But, if we need to exchange complex data like json from UTM to plugin we use Javascript (Note: Some APIs are difficult to get it working in JS, hence our first choice is applescript).
+
+**3. Shell command** : 
+All interactions with UTM should be possible with `utmctl` or `osascript`. But, due to the unavailablity of certain commands or features, we work around the issue by using direct shell command.  
+For Example:
+
+* Import `open -g utm://downloadVM?url=...` 
+* Snapshot `qemu-img snapshot ...`

data/docs/known_issues.md

@@ -0,0 +1,24 @@
+---
+title: Known Issues
+nav_order: 7
+---
+
+# Known Issues
+
+This plugin was built built around the existing UTM API.
+Hence there are things which are not ideal.
+
+1. vagrant up : Loads new VM by downloading zip file every time, and manually asks the user to confirm the download completion.   
+Draw back -  UTM does not support import API.
+
+2. UUID : After importing VM , considers last VM in the list as the VM that was imported . So, if the intended VM is not last in the list , the plugin might customize other VM according to the Vagrantfile. 
+Draw back -  UTM import API should return UUID when imported.
+
+3. vagrant package: plugin just prints message to manually export the VM.
+Draw back -  UTM does not expose export API. (UTM already has 'Share')
+
+4. Hide: Any plugin action will bring up the main UTM window. However, a properly built UTM box with no display will run headless.
+
+5. vagrant snapshot: Even though UTM does not have snapshot feature, this plugin has a experimental support for offline VM snapshots using qemu-img. 
+The VM must be stopped, for any snapshot commands to work.
+The snapshot only works for **single** qcow2 based VM images

data/lib/vagrant_utm/action/boot.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module VagrantPlugins
+  module Utm
+    module Action
+      # Action to start the virtual machine.
+      class Boot
+        def initialize(app, _env)
+          @app = app
+        end
+
+        def call(env)
+          # Start up the VM and wait for it to boot.
+          env[:ui].info I18n.t("vagrant.actions.vm.boot.booting")
+          env[:machine].provider.driver.start
+
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/vagrant_utm/action/boot_disposable.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module VagrantPlugins
+  module Utm
+    module Action
+      # Action to start the virtual machine in disposable mode.
+      class BootDisposable
+        def initialize(app, _env)
+          @app = app
+        end
+
+        def call(env)
+          # Start up the VM in disposable mode.
+          env[:ui].warn I18n.t("vagrant_utm.actions.vm.boot.disposable")
+          env[:machine].provider.driver.start_disposable
+
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/vagrant_utm/action/check_accessible.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+module VagrantPlugins
+  module Utm
+    module Action
+      # This middleware checks that the VM is accessible, and raises an exception
+      # TODO: Define what is inaccessible in UTM and set the state accordingly
+      # Currently, UTM does not report inaccessible state,
+      # So this plugin will set the state to inaccessible
+      # Hence, this action will never raise an exception
+      class CheckAccessible
+        def initialize(app, _env)
+          @app = app
+        end
+
+        def call(env)
+          if env[:machine].state.id == :inaccessible
+            # The VM we are attempting to manipulate is inaccessible. This
+            # is a very bad situation and can only be fixed by the user. It
+            # also prohibits us from actually doing anything with the virtual
+            # machine, so we raise an error.
+            raise Vagrant::Errors::VMInaccessible
+          end
+
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/vagrant_utm/action/check_created.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+module VagrantPlugins
+  module Utm
+    module Action
+      # This middleware checks that the VM is created, and raises an exception
+      # if it is not, notifying the user that creation is required.
+      class CheckCreated
+        def initialize(app, _env)
+          @app = app
+        end
+
+        def call(env)
+          raise Vagrant::Errors::VMNotCreatedError if env[:machine].state.id == :not_created
+
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/vagrant_utm/action/check_guest_additions.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "log4r"
+
+module VagrantPlugins
+  module Utm
+    module Action
+      # This action checks if the guest additions are installed.
+      # Currently only check's if qemu-guest-agent is installed and running.
+      # TODO: Add other checks, Drivers(eg Virt), SPICE Agent, SPICE WebDAV, VirtFS
+      class CheckGuestAdditions
+        def initialize(app, _env)
+          @app    = app
+          @logger = Log4r::Logger.new("vagrant_utm::action::check_guest_additions")
+        end
+
+        def call(env) # rubocop:disable Metrics/AbcSize
+          unless env[:machine].provider_config.check_guest_additions
+            @logger.info("Not checking guest additions because configuration")
+            return @app.call(env)
+          end
+
+          env[:ui].output(I18n.t("vagrant_utm.utm.checking_guest_additions"))
+
+          if env[:machine].provider.driver.check_qemu_guest_agent
+            env[:ui].detail(I18n.t("vagrant_utm.actions.vm.check_guest_additions.detected"))
+          else
+            env[:ui].detail(I18n.t("vagrant_utm.actions.vm.check_guest_additions.not_detected"))
+          end
+
+          # Continue
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/vagrant_utm/action/check_qemu_img.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module VagrantPlugins
+  module Utm
+    module Action
+      # This action checks if qemu-img is installed.
+      class CheckQemuImg
+        def initialize(app, _env)
+          @app = app
+        end
+
+        def call(env)
+          qemu_img_present = Vagrant::Util::Which.which("qemu-img")
+          raise Errors::QemuImgRequired unless qemu_img_present
+
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/vagrant_utm/action/check_running.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+module VagrantPlugins
+  module Utm
+    module Action
+      # This middleware checks that the VM is running, and raises an exception
+      # if it is not, notifying the user that the VM must be running.
+      # UTM equivalent status is "started"
+      class CheckRunning
+        def initialize(app, _env)
+          @app = app
+        end
+
+        def call(env)
+          raise Vagrant::Errors::VMNotRunningError if env[:machine].state.id != :started
+
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/vagrant_utm/action/check_utm.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+require "vagrant/util/platform"
+
+module VagrantPlugins
+  module Utm
+    module Action
+      # Checks that UTM is installed and ready to be used.
+      class CheckUtm
+        def initialize(app, _env)
+          @app = app
+          @logger = Log4r::Logger.new("vagrant::provider::utm")
+        end
+
+        def call(env)
+          # This verifies that UTM is installed and the driver is
+          # ready to function. If not, then an exception will be raised
+          # which will break us out of execution of the middleware sequence.
+          Driver::Meta.new.verify!
+
+          # Carry on.
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/vagrant_utm/action/clear_forwarded_ports.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+module VagrantPlugins
+  module Utm
+    module Action
+      # This action clears forwarded ports on the UTM VM.
+      class ClearForwardedPorts
+        def initialize(app, _env)
+          @app = app
+        end
+
+        def call(env)
+          unless env[:machine].provider.driver.read_forwarded_ports.empty?
+            env[:ui].info I18n.t("vagrant.actions.vm.clear_forward_ports.deleting")
+            env[:machine].provider.driver.clear_forwarded_ports
+          end
+
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/vagrant_utm/action/created.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+module VagrantPlugins
+  module Utm
+    module Action
+      # This class will set the result to be true if the machine is created.
+      class Created
+        def initialize(app, _env)
+          @app = app
+        end
+
+        def call(env)
+          # Set the result to be true if the machine is created.
+          env[:result] = env[:machine].state.id != :not_created
+
+          # Call the next if we have one (but we shouldn't, since this
+          # middleware is built to run with the Call-type middlewares)
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/vagrant_utm/action/customize.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+module VagrantPlugins
+  module Utm
+    module Action
+      # This middleware class runs the customizations for the VM.
+      class Customize
+        def initialize(app, _env, event)
+          @app = app
+          @event = event
+        end
+
+        def call(env) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity
+          customizations = []
+          env[:machine].provider_config.customizations.each do |event, command|
+            customizations << command if event == @event
+          end
+
+          unless customizations.empty?
+            env[:ui].info I18n.t("vagrant.actions.vm.customize.running", event: @event)
+
+            # Execute each customization command.
+            customizations.each do |command|
+              processed_command = command.collect do |arg|
+                arg = env[:machine].id if arg == :id
+                arg.to_s
+              end
+
+              begin
+                env[:machine].provider.driver.execute_osa_script(
+                  processed_command
+                )
+              rescue VagrantPlugins::Utm::Errors::CommandError => e
+                raise Vagrant::Errors::VMCustomizationFailed, {
+                  command: command,
+                  error: e.inspect
+                }
+              end
+            end
+          end
+
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/vagrant_utm/action/destroy.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+module VagrantPlugins
+  module Utm
+    module Action
+      # This action destroys the running machine.
+      class Destroy
+        def initialize(app, _env)
+          @app = app
+        end
+
+        def call(env)
+          env[:ui].info I18n.t("vagrant.actions.vm.destroy.destroying")
+          env[:machine].provider.driver.delete
+          env[:machine].id = nil
+
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/vagrant_utm/action/download_confirm.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "vagrant/action/builtin/confirm"
+
+module VagrantPlugins
+  module Utm
+    module Action
+      # Action to confirm download of UTM.
+      class DownloadConfirm < Vagrant::Action::Builtin::Confirm
+        def initialize(app, env)
+          force_key = nil # No force key, user must confirm the download
+          message = I18n.t("vagrant_utm.messages.download_confirmation",
+                           name: env[:machine].provider_config.utm_file_url)
+          super(app, env, message, force_key, allowed: %w[y n Y N])
+        end
+      end
+    end
+  end
+end