vagrant_utm 0.0.1 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +43 -3
- data/README.md +1 -3
- data/docs/_config.yml +5 -6
- data/docs/assets/images/screens/debian-10.4-i3-arm64.png +0 -0
- data/docs/boxes/creating_utm_box.md +46 -19
- data/docs/boxes/utm_box_gallery.md +17 -93
- data/docs/commands.md +12 -8
- data/docs/configuration.md +13 -3
- data/docs/features/synced_folders.md +1 -1
- data/docs/index.md +28 -14
- data/docs/internals/utm_api.md +0 -1
- data/docs/known_issues.md +6 -6
- data/lib/vagrant_utm/action/export.rb +26 -5
- data/lib/vagrant_utm/action/import.rb +24 -14
- data/lib/vagrant_utm/action/ip_address.rb +33 -0
- data/lib/vagrant_utm/action/match_mac_address.rb +37 -0
- data/lib/vagrant_utm/action/package.rb +22 -0
- data/lib/vagrant_utm/action/package_setup_files.rb +22 -0
- data/lib/vagrant_utm/action/package_setup_folders.rb +24 -0
- data/lib/vagrant_utm/action/package_vagrantfile.rb +39 -0
- data/lib/vagrant_utm/action/set_id.rb +1 -1
- data/lib/vagrant_utm/action.rb +45 -19
- data/lib/vagrant_utm/commands/disposable.rb +29 -0
- data/lib/vagrant_utm/commands/ip_address.rb +28 -0
- data/lib/vagrant_utm/config.rb +1 -10
- data/lib/vagrant_utm/driver/base.rb +26 -6
- data/lib/vagrant_utm/driver/meta.rb +5 -3
- data/lib/vagrant_utm/driver/version_4_5.rb +16 -4
- data/lib/vagrant_utm/driver/version_4_6.rb +42 -0
- data/lib/vagrant_utm/model/forwarded_port.rb +3 -1
- data/lib/vagrant_utm/plugin.rb +11 -8
- data/lib/vagrant_utm/provider.rb +2 -1
- data/lib/vagrant_utm/scripts/export_vm.applescript +13 -0
- data/lib/vagrant_utm/scripts/import_vm.applescript +14 -0
- data/lib/vagrant_utm/scripts/read_forwarded_ports.applescript +1 -1
- data/lib/vagrant_utm/scripts/read_network_interfaces.applescript +2 -1
- data/lib/vagrant_utm/scripts/set_mac_address.applescript +25 -0
- data/lib/vagrant_utm/version.rb +1 -1
- data/lib/vagrant_utm.rb +1 -0
- data/locales/en.yml +9 -0
- data/notes/README.md +30 -0
- data/vagrantfile_examples/Vagrantfile +3 -2
- metadata +16 -5
- data/lib/vagrant_utm/action/download_confirm.rb +0 -19
- data/lib/vagrant_utm/disposable.rb +0 -16
- data/lib/vagrant_utm/scripts/read_guest_ip.applescript +0 -9
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: e58e1f0313976a35281a3233fe67d4150f84c8ec51ed41c2ca55256ba9cae05e
|
4
|
+
data.tar.gz: b5b234e460ef8517720492d3b5695cf771cd52efdd0a60c172ec3d644931b535
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: fb95231d43a7f9731d7b36823ff7e991b5e11c9113a60590120b21fcd0d6b420116fe7d39e3465e579e5c1548071d562b50b94142c5f4bb689d13c24a671271b
|
7
|
+
data.tar.gz: b3a7b1655c81f270c6aa8399668fcfd5862201f9d00e9532ba00b7e9609e2d6dc7b5a986b502fd447b39dd303bb92ce1b9f513b7c09e2fa2ccf4a801de5878c4
|
data/CHANGELOG.md
CHANGED
@@ -1,5 +1,45 @@
|
|
1
|
-
## [
|
1
|
+
## [0.1.1] - 2024-12-03
|
2
2
|
|
3
|
-
|
3
|
+
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.
|
4
4
|
|
5
|
-
|
5
|
+
### Added
|
6
|
+
|
7
|
+
- command: add new vagrant command `vagrant ip-address` (9252020)
|
8
|
+
- command: add help messages to custom plugin commands (a35466f)
|
9
|
+
- action: Set mac address when bringing up new machine (0efe15b)
|
10
|
+
|
11
|
+
### Changed
|
12
|
+
|
13
|
+
- plugin: Make config.vm.box mandatory for this plugin (b5be5e8)
|
14
|
+
|
15
|
+
### Fixed
|
16
|
+
|
17
|
+
- disposable: allow disposable start only for machines already created (cbf591e)
|
18
|
+
- up: Set given mac address or random mac address for first interface of a machine to get different IPs of a same base box.
|
19
|
+
|
20
|
+
### Removed
|
21
|
+
|
22
|
+
- Driver: Removed support for UTM version 4.5.x (9aea46e)
|
23
|
+
|
24
|
+
## [0.1.0] (Beta) - 2024-11-30
|
25
|
+
|
26
|
+
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.
|
27
|
+
|
28
|
+
### Added
|
29
|
+
|
30
|
+
- driver: add new driver for UTM version 4.6.x (13d0ca0)
|
31
|
+
- vagrant: add vagrant box support (f7accad)
|
32
|
+
- command: support `vagrant package` command (39fb5a5)
|
33
|
+
|
34
|
+
|
35
|
+
### Removed
|
36
|
+
|
37
|
+
- Drop support for `utm_file_url` from provider config (4fb0ac0)
|
38
|
+
- Remove support for importing utm files in zip format (c988671)
|
39
|
+
|
40
|
+
|
41
|
+
|
42
|
+
## [0.0.1] (Pilot release) - 2024-08-08
|
43
|
+
|
44
|
+
* Initial release with all basic vagrant commands
|
45
|
+
* Uses UTM file in zip format from a url as VM box to import
|
data/README.md
CHANGED
@@ -15,9 +15,7 @@ vagrant plugin install vagrant_utm
|
|
15
15
|
|
16
16
|
```ruby
|
17
17
|
Vagrant.configure("2") do |config|
|
18
|
-
config.vm.
|
19
|
-
utm.utm_file_url = "https://github.com/naveenrajm7/utm-box/releases/download/debian-11/debian_vagrant_utm.zip"
|
20
|
-
end
|
18
|
+
config.vm.box = "utm/debian11"
|
21
19
|
end
|
22
20
|
```
|
23
21
|
|
data/docs/_config.yml
CHANGED
@@ -2,12 +2,11 @@ title: Vagrant UTM
|
|
2
2
|
description: >-
|
3
3
|
vagrant_utm is a Vagrant plugin which adds UTM provider to Vagrant,
|
4
4
|
allowing Vagrant to control and provision machines via UTM's API
|
5
|
-
baseurl: "/
|
6
|
-
#
|
7
|
-
|
8
|
-
url: "https://naveenrajm7.github.io/vagrant_utm"
|
5
|
+
baseurl: "/vagrant_utm" # the subpath of your site, e.g. /blog
|
6
|
+
url: "https://naveenrajm7.github.io" # the base hostname & protocol for your site, e.g. http://example.com
|
7
|
+
repository: naveenrajm7/vagrant_utm # for github-metadata
|
9
8
|
github_username: naveenrajm7
|
10
|
-
|
9
|
+
|
11
10
|
|
12
11
|
# Build settings
|
13
12
|
remote_theme: just-the-docs/just-the-docs@v0.8.2
|
@@ -73,4 +72,4 @@ back_to_top: true
|
|
73
72
|
back_to_top_text: "Back to top"
|
74
73
|
|
75
74
|
# Footer
|
76
|
-
footer_content: "Copyright © 2024 Naveenraj Muthuraj. Distributed by an <a href=\"https://github.com/naveenrajm7/vagrant_utm/tree/main/LICENSE.txt\">MIT license.</a>"
|
75
|
+
footer_content: "Copyright © 2024 Naveenraj Muthuraj. Distributed by an <a href=\"https://github.com/naveenrajm7/vagrant_utm/tree/main/LICENSE.txt\">MIT license.</a>"
|
Binary file
|
@@ -8,15 +8,23 @@ nav_order: 2
|
|
8
8
|
|
9
9
|
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.
|
10
10
|
|
11
|
-
|
12
|
-
The UTM bundle (.utm file) is the box format for Vagrant UTM provider.
|
13
|
-
Because the current UTM API does not support importing utm file, we do not use vagrant box format (.box file).
|
14
|
-
We currently use `utm://downloadVM?url=` to import VM to UTM.
|
11
|
+
## UTM Vagrant box format
|
15
12
|
|
13
|
+
UTM file (in macOS) is a directory containing Data/qcow2 (s), Data/efi_vars.fd and config.plist.
|
14
|
+
Vagrant Box format will require additional metadata.json file.
|
16
15
|
|
17
|
-
|
18
|
-
However, once UTM supports import, we should be able to package UTM files into box format and use the benefits of Vagrant boxes . For example, downloading the box once to spin up multiple VMs and using vagrant cloud to publish custom UTM boxes.
|
16
|
+
Vagrant .box is a tar file
|
19
17
|
|
18
|
+
The contents of a `utm/ubuntu-24.04` vagrant box.
|
19
|
+
```bash
|
20
|
+
$tar -tf ubuntu-24.04.box
|
21
|
+
Vagrantfile
|
22
|
+
box.utm/Data/7FB247A3-DC9F-4A61-A123-0AEE1BEEC636.qcow2
|
23
|
+
box.utm/Data/efi_vars.fd
|
24
|
+
box.utm/config.plist
|
25
|
+
box.utm/screenshot.png
|
26
|
+
metadata.json
|
27
|
+
```
|
20
28
|
|
21
29
|
{: .warning }
|
22
30
|
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.
|
@@ -25,9 +33,16 @@ This is a reasonably advanced topic that a beginning user of Vagrant does not ne
|
|
25
33
|
|
26
34
|
The virtual machine created in UTM can use any configuration you would like, but Vagrant has some hard requirements:
|
27
35
|
|
28
|
-
* The
|
36
|
+
* The first network interface (adapter 1 or index 0) must be `Shared Network`, which is recommended for new virtual machines.
|
37
|
+
|
38
|
+
We use 'Shared Network' as a NAT equivalent in Vagrant.
|
39
|
+
|
40
|
+
* 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.
|
41
|
+
|
42
|
+
We use 'Emulated VLAN' to achieve port forwarding.
|
43
|
+
|
44
|
+
|
29
45
|
|
30
|
-
* Use can use the first network interface (adapter 0 or index 0) to be `Shared Network`, which is recommended for new virtual machines.
|
31
46
|
|
32
47
|
Other than the above, you are free to customize the base virtual machine as you see fit.
|
33
48
|
|
@@ -46,25 +61,37 @@ Check the [UTM Guide on Guest Support](https://docs.getutm.app/guest-support/gue
|
|
46
61
|
By satisfying the [general guidance on creating vagrant boxes](https://developer.hashicorp.com/vagrant/docs/boxes/base) and the above [Virtual Machine](#virtual-machine) requirements you can use your VM with Vagrant UTM plugin.
|
47
62
|
|
48
63
|
Apart from manually building the boxes, you can also use the semi-automated way of building these boxes using [packer plugin for UTM](https://github.com/naveenrajm7/packer-plugin-utm).
|
49
|
-
The packer plugin has
|
64
|
+
The packer plugin has the following components:
|
65
|
+
1. Builder
|
66
|
+
1. UTM - Use existing utm file
|
67
|
+
2. ISO - Start from scratch using ISO files
|
68
|
+
2. Post-processor
|
69
|
+
1. ZIP - Package UTM VM into zip file
|
70
|
+
2. Vagrant - Package UTM VM into vagrant box.
|
71
|
+
|
50
72
|
|
51
73
|
Checkout [UTM Box Guide](https://github.com/naveenrajm7/utm-box/blob/main/HowToBuild/DebianUTM.md) to know how to build Box using packer.
|
52
74
|
|
53
|
-
## Using your own UTM
|
75
|
+
## Using your own UTM VMs
|
76
|
+
|
77
|
+
Do you have your own UTM VM that you would like to use with Vagrant
|
54
78
|
|
55
|
-
|
56
|
-
So, you can use a local python server to host your UTM bundle in zip file
|
79
|
+
1. Convert your utm file to box format
|
57
80
|
|
81
|
+
a. Make a directory
|
82
|
+
b. Put utm vm file in it
|
83
|
+
c. Tar the folder with .box extension
|
84
|
+
|
85
|
+
2. Import the vagrant box
|
58
86
|
```bash
|
59
|
-
|
60
|
-
Serving HTTP on :: port 8000 (http://[::]:8000/) ...
|
87
|
+
vagrant box add --name custom/debian debian.box
|
61
88
|
```
|
62
89
|
|
63
|
-
Use in Vagrantfile
|
90
|
+
3. Use in Vagrantfile
|
64
91
|
```ruby
|
65
92
|
Vagrant.configure("2") do |config|
|
66
|
-
config.vm.
|
67
|
-
utm.utm_file_url = "http://localhost:8000/debian_vagrant_utm.zip"
|
68
|
-
end
|
93
|
+
config.vm.box = "custom/debian11"
|
69
94
|
end
|
70
|
-
```
|
95
|
+
```
|
96
|
+
|
97
|
+
You can also use [packer plugin for UTM](https://github.com/naveenrajm7/packer-plugin-utm) to build, package and publish your UTM VMs to HCP Vagrant registry and share it your teams or with the world.
|
@@ -1,117 +1,41 @@
|
|
1
1
|
---
|
2
|
-
title: UTM box gallery
|
2
|
+
title: UTM Vagrant box gallery
|
3
3
|
# layout: default
|
4
4
|
parent: UTM Box
|
5
5
|
nav_order: 1
|
6
6
|
---
|
7
7
|
|
8
|
-
# UTM Box Gallery
|
8
|
+
# UTM Vagrant Box Gallery
|
9
9
|
|
10
10
|
To work with Vagrant, a base VM (box) must have
|
11
|
-
[certain features](https://developer.hashicorp.com/vagrant/docs/boxes/base), like
|
11
|
+
[certain features](https://developer.hashicorp.com/vagrant/docs/boxes/base), like an ssh user for vagrant to connect.
|
12
12
|
|
13
|
-
To help you get started with Vagrant UTM provider, couple of pre-built VMs
|
13
|
+
To help you get started with Vagrant UTM provider, a couple of pre-built VMs that work with Vagrant and are published in [HCP Vagrant registry](https://portal.cloud.hashicorp.com/vagrant/discover/utm).
|
14
14
|
|
15
|
+
{: .important}
|
16
|
+
All the VMs provided are built from [UTM Gallery VMs](https://mac.getutm.app/gallery/) or ISO in an (semi) automated way using [packer plugin for UTM][packer plugin for UTM]. Please see the [UTM Box Guide][UTM Box Guide] on how these UTM Vagrant boxes were built using packer.
|
15
17
|
|
16
18
|
* Debian 11 (Xfce):
|
17
19
|
```ruby
|
18
|
-
|
20
|
+
config.vm.box = "utm/debian11"
|
19
21
|
```
|
20
22
|
|
23
|
+
* Ubuntu 24.04 :
|
24
|
+
```ruby
|
25
|
+
config.vm.box = "utm/ubuntu-24.04"
|
26
|
+
```
|
27
|
+
|
28
|
+
* Help build more boxes using [packer plugin for UTM][packer plugin for UTM]
|
21
29
|
<!-- * ArchLinux ARM -->
|
22
30
|
|
23
31
|
|
24
32
|
{: .new}
|
25
|
-
To enable building reproducible and easily sharable UTM VM bundle a [packer plugin for UTM]
|
26
|
-
Please see the [UTM Box Guide](https://github.com/naveenrajm7/utm-box/blob/main/HowToBuild/DebianUTM.md) on how these UTM Vagrant boxes were built using packer.
|
27
|
-
|
28
|
-
|
29
|
-
Check out [Creating UTM Box](/boxes/creating_utm_box.md) to build your own Vagrant compatible UTM box.
|
30
|
-
|
31
|
-
## Corresponding VMs from UTM Gallery
|
32
|
-
|
33
|
-
<div class="content">
|
34
|
-
<section class="gallery">
|
35
|
-
<!-- <div class="gallery-item">
|
36
|
-
<a href="{{ vm.url }}">
|
37
|
-
<h3>ArchLinux ARM</h3>
|
38
|
-
<h4><i class="fas fa-microchip"></i> ARM64 </h4>
|
39
|
-
<img src="{{ site.baseurl }}/assets/images/screens/archlinux-logo.png" alt="Screenshot" class="screenshot" />
|
40
|
-
</a>
|
41
|
-
</div> -->
|
42
|
-
<div class="gallery-item">
|
43
|
-
<a href="">
|
44
|
-
<h3>Debian 11 (Xfce)</h3>
|
45
|
-
<h4><i class="fas fa-microchip"></i> ARM64 </h4>
|
46
|
-
<img src="{{ site.baseurl }}/assets/images/screens/debian-11-xfce-arm64.png" alt="Screenshot" class="screenshot" />
|
47
|
-
</a>
|
48
|
-
</div>
|
49
|
-
</section>
|
50
|
-
</div>
|
51
|
-
|
52
|
-
<style>
|
53
|
-
.gallery {
|
54
|
-
display: flex;
|
55
|
-
flex-flow: row wrap;
|
56
|
-
justify-content: center;
|
57
|
-
align-items: center;
|
58
|
-
}
|
59
|
-
|
60
|
-
.gallery .gallery-item {
|
61
|
-
padding: 5px;
|
62
|
-
width: 20em;
|
63
|
-
}
|
64
|
-
|
65
|
-
.gallery-item a {
|
66
|
-
text-decoration: none;
|
67
|
-
color: black;
|
68
|
-
}
|
69
|
-
|
70
|
-
.gallery h3, .gallery h4 {
|
71
|
-
text-align: center;
|
72
|
-
overflow: hidden;
|
73
|
-
text-overflow: ellipsis;
|
74
|
-
white-space: nowrap;
|
75
|
-
}
|
76
|
-
|
77
|
-
.gallery h3 {
|
78
|
-
font-size: 1.2em;
|
79
|
-
}
|
80
|
-
|
81
|
-
.gallery h4 {
|
82
|
-
margin: 10px 0 10px 0;
|
83
|
-
font-size: 0.8em;
|
84
|
-
font-weight: normal;
|
85
|
-
}
|
33
|
+
To enable building reproducible and easily sharable UTM VM bundle a [packer plugin for UTM][packer plugin for UTM] has been developed and open-sourced.
|
86
34
|
|
87
|
-
.gallery .image {
|
88
|
-
width: 20em;
|
89
|
-
}
|
90
35
|
|
91
|
-
.gallery .screenshot {
|
92
|
-
max-width: 100%;
|
93
|
-
height: auto;
|
94
|
-
display: block;
|
95
|
-
box-shadow: 0 1px 0 #ccc, 0 1px 0 1px #eee;
|
96
|
-
border-radius: 2px;
|
97
|
-
margin-left: auto;
|
98
|
-
margin-right: auto;
|
99
|
-
background: #DDD url('data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%2244%22%20height%3D%2212%22%20viewBox%3D%220%200%2044%2012%22%3E%3Ccircle%20cx%3D%226%22%20cy%3D%226%22%20r%3D%224%22%20fill%3D%22%23eee%22%20%2F%3E%3Ccircle%20cx%3D%2222%22%20cy%3D%226%22%20r%3D%224%22%20fill%3D%22%23eee%22%20%2F%3E%3Ccircle%20cx%3D%2238%22%20cy%3D%226%22%20r%3D%224%22%20fill%3D%22%23eee%22%20%2F%3E%3C%2Fsvg%3E') 4px 4px no-repeat;
|
100
|
-
padding: 20px 0 0 0;
|
101
|
-
position: relative;
|
102
|
-
}
|
103
36
|
|
104
|
-
.
|
105
|
-
padding-top: 75%;
|
106
|
-
}
|
37
|
+
Check out [Creating UTM Box](/creating_utm_box.md) to build your own compatible UTM Vagrant box.
|
107
38
|
|
108
|
-
.gallery li {
|
109
|
-
padding: 5px 0 5px 0;
|
110
|
-
}
|
111
39
|
|
112
|
-
|
113
|
-
|
114
|
-
margin: 20px 0 20px 0;
|
115
|
-
font-size: 1.5em;
|
116
|
-
}
|
117
|
-
</style>
|
40
|
+
[packer plugin for UTM]: https://github.com/naveenrajm7/packer-plugin-utm
|
41
|
+
[UTM Box Guide]: https://github.com/naveenrajm7/utm-box/blob/main/HowToBuild/DebianUTM.md
|
data/docs/commands.md
CHANGED
@@ -9,7 +9,7 @@ nav_order: 2
|
|
9
9
|
|
10
10
|
This page lists all the supported Vagrant commands which depend on the UTM provider. Eg. `up`, `suspend`, `resume`, `halt`.
|
11
11
|
|
12
|
-
Adds note to the command which are
|
12
|
+
Adds note to the command which are have some limitations. Eg. `snapshot`.
|
13
13
|
|
14
14
|
The Vagrant commands that do not depend on provider are not listed and will continue to work. Eg. `global-status`
|
15
15
|
|
@@ -26,9 +26,7 @@ The Vagrant commands that do not depend on provider are not listed and will cont
|
|
26
26
|
|
27
27
|
**Command: `vagrant box`**
|
28
28
|
|
29
|
-
UTM provider uses .utm file as VM bundle .
|
30
|
-
|
31
|
-
Box support is not yet available.
|
29
|
+
UTM provider uses .utm file as VM bundle and supports box operations.
|
32
30
|
|
33
31
|
## **Destroy**
|
34
32
|
|
@@ -46,9 +44,7 @@ Box support is not yet available.
|
|
46
44
|
|
47
45
|
**Command: `vagrant package [name|id]`**
|
48
46
|
|
49
|
-
|
50
|
-
|
51
|
-
|
47
|
+
UTM 'Share' / export
|
52
48
|
|
53
49
|
## **Port**
|
54
50
|
|
@@ -70,7 +66,7 @@ Runs any configured [provisioners](https://developer.hashicorp.com/vagrant/docs
|
|
70
66
|
|
71
67
|
**Command: `vagrant reload [name|id]`**
|
72
68
|
|
73
|
-
The equivalent of running a [halt](https://developer.hashicorp.com/vagrant/docs/cli/halt) followed by an[up](https://developer.hashicorp.com/vagrant/docs/cli/up).
|
69
|
+
The equivalent of running a [halt](https://developer.hashicorp.com/vagrant/docs/cli/halt) followed by an [up](https://developer.hashicorp.com/vagrant/docs/cli/up).
|
74
70
|
|
75
71
|
|
76
72
|
|
@@ -145,6 +141,14 @@ Import VM (if not created)
|
|
145
141
|
|
146
142
|
These are the commands not available in vagrant but specific to UTM provider.
|
147
143
|
|
144
|
+
## IP Address
|
145
|
+
|
146
|
+
**Command: `vagrant ip-address [name|id]`**
|
147
|
+
|
148
|
+
`utmctl ip-address`
|
149
|
+
|
150
|
+
List all IP addresses associated with network interfaces on the guest.
|
151
|
+
|
148
152
|
## Disposable
|
149
153
|
|
150
154
|
**Command: `vagrant disposable [name|id]`**
|
data/docs/configuration.md
CHANGED
@@ -17,10 +17,22 @@ config.vm.provider "utm" do |u|
|
|
17
17
|
end
|
18
18
|
```
|
19
19
|
|
20
|
+
## Checking for Guest Additions
|
21
|
+
|
22
|
+
By default UTM plugin will check for the `qemu-guest-agent` when starting a machine, and will output a warning if the guest additions are not detected. You can skip the guest additions check by setting the check_guest_additions option:
|
23
|
+
|
24
|
+
```ruby
|
25
|
+
config.vm.provider "utm" do |u|
|
26
|
+
u.check_guest_additions = false
|
27
|
+
end
|
28
|
+
```
|
29
|
+
|
20
30
|
## Other customization
|
21
31
|
|
22
32
|
```ruby
|
23
33
|
Vagrant.configure("2") do |config|
|
34
|
+
# Vagrant box
|
35
|
+
config.vm.box = "utm/debian11"
|
24
36
|
# Hostname inside the VM
|
25
37
|
config.vm.hostname = "debian"
|
26
38
|
# Ports to forward
|
@@ -29,13 +41,11 @@ Vagrant.configure("2") do |config|
|
|
29
41
|
config.vm.provider "utm" do |u|
|
30
42
|
# Name in UTM UI
|
31
43
|
u.name = "debian"
|
32
|
-
# UTM VM file to import
|
33
|
-
u.utm_file_url = "http://localhost:8000/debian_vagrant_utm.zip"
|
34
44
|
# CPU in cores
|
35
45
|
u.cpus = 1
|
36
46
|
# Memory in MB
|
37
47
|
u.memory = 1024
|
38
|
-
# Notes for UTM VM (Appears in UI)
|
48
|
+
# Notes for UTM VM (Appears in UTM UI)
|
39
49
|
u.notes = "Vagrant: For testing plugin development"
|
40
50
|
# QEMU Directoy Share mode for the VM.
|
41
51
|
# Takes none, webDAV or virtFS
|
@@ -13,8 +13,8 @@ After which the the host directory can be selected from UTM UI, and the guest di
|
|
13
13
|
|
14
14
|
```ruby
|
15
15
|
Vagrant.configure("2") do |config|
|
16
|
+
config.vm.box = "utm/debian11"
|
16
17
|
config.vm.provider :utm do |u|
|
17
|
-
u.utm_file_url = "http://localhost:8000/vm_utm.zip"
|
18
18
|
# QEMU Directoy Share mode for the VM.
|
19
19
|
# Takes none, webDAV or virtFS
|
20
20
|
u.directory_share_mode = "webDAV"
|
data/docs/index.md
CHANGED
@@ -18,10 +18,16 @@ allowing Vagrant to control and provision machines via UTM's API.
|
|
18
18
|
|
19
19
|
---
|
20
20
|
|
21
|
-
|
22
|
-
|
21
|
+
{: .new}
|
22
|
+
> UTM Vagrant plugin now supports [Vagrant boxes](https://developer.hashicorp.com/vagrant/docs/boxes)!
|
23
|
+
> Find UTM boxes at [HCP Vagrant registry](https://portal.cloud.hashicorp.com/vagrant/discover/utm).
|
23
24
|
|
24
|
-
[
|
25
|
+
[UTM] is a free, full-featured system emulator and virtual machine host for iOS and macOS.
|
26
|
+
The UTM provider currently supports UTM versions
|
27
|
+
* 4.6.x
|
28
|
+
* 4.5.x (Obsolete, use plugin version 0.0.1)
|
29
|
+
|
30
|
+
[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.
|
25
31
|
|
26
32
|
|
27
33
|
Both UTM and Vagrant must be installed prior to using this plugin.
|
@@ -33,11 +39,11 @@ Browse the docs to learn more about how to use this plugin.
|
|
33
39
|
|
34
40
|
## Getting started
|
35
41
|
|
36
|
-
Get started with Vagrant UTM plugin in
|
42
|
+
Get started with Vagrant UTM plugin in 2 simple steps.
|
37
43
|
Make sure both [Vagrant] and [UTM] are installed before your proceed.
|
38
44
|
|
39
|
-
{: .
|
40
|
-
UTM Vagrant plugin is built around the existing UTM API. Some
|
45
|
+
{: .note}
|
46
|
+
UTM Vagrant plugin is built around the existing UTM API. Some action like Snapshot are not straightforward. Please check [Known Issues](/known_issues.md) before using this plugin.
|
41
47
|
|
42
48
|
|
43
49
|
### Install
|
@@ -49,26 +55,34 @@ vagrant plugin install vagrant_utm
|
|
49
55
|
|
50
56
|
### Use
|
51
57
|
|
52
|
-
|
58
|
+
#### Step 1
|
59
|
+
Option 1: Create a Vagrantfile and initiate the box (OR)
|
60
|
+
|
61
|
+
```
|
62
|
+
vagrant init utm/debian11
|
63
|
+
```
|
64
|
+
|
65
|
+
Option 2: Open the Vagrantfile and replace the contents with the following
|
66
|
+
|
53
67
|
```ruby
|
54
68
|
Vagrant.configure("2") do |config|
|
55
|
-
config.vm.
|
56
|
-
u.utm_file_url = "https://github.com/naveenrajm7/utm-box/releases/download/debian-11/debian_vagrant_utm.zip"
|
57
|
-
end
|
69
|
+
config.vm.box = "utm/debian11"
|
58
70
|
end
|
59
71
|
```
|
60
72
|
|
61
|
-
|
73
|
+
#### Step 2
|
74
|
+
Bring up your virtual machine
|
62
75
|
|
63
|
-
|
64
|
-
```bash
|
76
|
+
```
|
65
77
|
vagrant up
|
66
78
|
```
|
67
79
|
|
80
|
+
Now start using your machine!
|
68
81
|
|
82
|
+
`vagrant ssh` to log into machine or forward ports to check your website or share folders and start developing.
|
69
83
|
|
70
84
|
Check [Commands](commands.md) for all supported Vagrant commands.
|
71
|
-
Check [Configuration](configuration.md) for more provider config options.
|
85
|
+
Check [Configuration](configuration.md) for more UTM provider config options.
|
72
86
|
|
73
87
|
|
74
88
|
## About the project
|
data/docs/internals/utm_api.md
CHANGED
@@ -27,5 +27,4 @@ But, if we need to exchange complex data like json from UTM to plugin we use Jav
|
|
27
27
|
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.
|
28
28
|
For Example:
|
29
29
|
|
30
|
-
* Import `open -g utm://downloadVM?url=...`
|
31
30
|
* Snapshot `qemu-img snapshot ...`
|
data/docs/known_issues.md
CHANGED
@@ -8,14 +8,14 @@ nav_order: 7
|
|
8
8
|
This plugin was built built around the existing UTM API.
|
9
9
|
Hence there are things which are not ideal.
|
10
10
|
|
11
|
-
1. vagrant up : Loads new VM by downloading zip file every time, and manually asks the user to confirm the download completion
|
12
|
-
Draw back - UTM does not support import API
|
11
|
+
1. ~~vagrant up : Loads new VM by downloading zip file every time, and manually asks the user to confirm the download completion.~~
|
12
|
+
~~Draw back - UTM does not support import API.~~
|
13
13
|
|
14
|
-
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
|
15
|
-
Draw back - UTM import API should return UUID when imported
|
14
|
+
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.~~
|
15
|
+
~~Draw back - UTM import API should return UUID when imported.~~
|
16
16
|
|
17
|
-
3. vagrant package: plugin just prints message to manually export the VM.
|
18
|
-
Draw back - UTM does not expose export API. (UTM already has 'Share')
|
17
|
+
3. ~~vagrant package: plugin just prints message to manually export the VM.
|
18
|
+
Draw back - UTM does not expose export API. (UTM already has 'Share')~~
|
19
19
|
|
20
20
|
4. Hide: Any plugin action will bring up the main UTM window. However, a properly built UTM box with no display will run headless.
|
21
21
|
|
@@ -3,19 +3,40 @@
|
|
3
3
|
module VagrantPlugins
|
4
4
|
module Utm
|
5
5
|
module Action
|
6
|
-
# This action
|
6
|
+
# This action exports the virtual machine.
|
7
7
|
class Export
|
8
8
|
def initialize(app, _env)
|
9
9
|
@app = app
|
10
10
|
end
|
11
11
|
|
12
12
|
def call(env)
|
13
|
-
|
14
|
-
|
15
|
-
|
16
|
-
|
13
|
+
@env = env
|
14
|
+
|
15
|
+
raise Vagrant::Errors::VMPowerOffToPackage if \
|
16
|
+
@env[:machine].state.id != :stopped
|
17
|
+
|
18
|
+
export
|
19
|
+
|
17
20
|
@app.call(env)
|
18
21
|
end
|
22
|
+
|
23
|
+
def export
|
24
|
+
@env[:ui].info I18n.t("vagrant.actions.vm.export.exporting")
|
25
|
+
@env[:machine].provider.driver.export(utm_path) do |progress|
|
26
|
+
@env[:ui].rewriting do |ui|
|
27
|
+
ui.clear_line
|
28
|
+
ui.report_progress(progress.percent, 100, false)
|
29
|
+
end
|
30
|
+
end
|
31
|
+
|
32
|
+
# Clear the line a final time so the next data can appear
|
33
|
+
# alone on the line.
|
34
|
+
@env[:ui].clear_line
|
35
|
+
end
|
36
|
+
|
37
|
+
def utm_path
|
38
|
+
File.join(@env["export.temp_dir"], "box.utm")
|
39
|
+
end
|
19
40
|
end
|
20
41
|
end
|
21
42
|
end
|
@@ -13,25 +13,35 @@ module VagrantPlugins
|
|
13
13
|
import(env)
|
14
14
|
end
|
15
15
|
|
16
|
-
def import(env)
|
17
|
-
|
18
|
-
|
19
|
-
driver = machine.provider.driver
|
20
|
-
utm_file_url = config.utm_file_url
|
16
|
+
def import(env) # rubocop:disable Metrics/AbcSize
|
17
|
+
env[:ui].info I18n.t("vagrant.actions.vm.import.importing",
|
18
|
+
name: env[:machine].box.name)
|
21
19
|
|
22
|
-
|
20
|
+
# Import the virtual machine
|
21
|
+
utm_file = env[:machine].box.directory.join("box.utm").to_s
|
22
|
+
id = env[:machine].provider.driver.import(utm_file) do |progress|
|
23
|
+
env[:ui].rewriting do |ui|
|
24
|
+
ui.clear_line
|
25
|
+
ui.report_progress(progress, 100, false)
|
26
|
+
end
|
27
|
+
end
|
23
28
|
|
24
|
-
#
|
25
|
-
|
29
|
+
# Set the machine ID
|
30
|
+
env[:machine_id] = id
|
31
|
+
env[:machine].id = id unless env[:skip_machine]
|
26
32
|
|
27
|
-
#
|
28
|
-
#
|
29
|
-
|
33
|
+
# Clear the line one last time since the progress meter doesn't disappear
|
34
|
+
# immediately.
|
35
|
+
env[:ui].clear_line
|
30
36
|
|
31
|
-
#
|
32
|
-
#
|
33
|
-
|
37
|
+
# If we got interrupted, then the import could have been
|
38
|
+
# interrupted and its not a big deal. Just return out.
|
39
|
+
return if env[:interrupted]
|
34
40
|
|
41
|
+
# Flag as erroneous and return if import failed
|
42
|
+
raise Vagrant::Errors::VMImportFailure unless id
|
43
|
+
|
44
|
+
# Import completed successfully. Continue the chain
|
35
45
|
@app.call(env)
|
36
46
|
end
|
37
47
|
|