vagrant-libvirt 0.1.2 → 0.5.0
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/README.md +530 -100
- data/lib/vagrant-libvirt/action.rb +7 -1
- data/lib/vagrant-libvirt/action/clean_machine_folder.rb +28 -0
- data/lib/vagrant-libvirt/action/create_domain.rb +78 -22
- data/lib/vagrant-libvirt/action/create_domain_volume.rb +57 -57
- data/lib/vagrant-libvirt/action/create_network_interfaces.rb +1 -3
- data/lib/vagrant-libvirt/action/create_networks.rb +11 -4
- data/lib/vagrant-libvirt/action/destroy_domain.rb +1 -1
- data/lib/vagrant-libvirt/action/forward_ports.rb +40 -40
- data/lib/vagrant-libvirt/action/halt_domain.rb +25 -9
- data/lib/vagrant-libvirt/action/handle_box_image.rb +163 -72
- data/lib/vagrant-libvirt/action/is_running.rb +1 -3
- data/lib/vagrant-libvirt/action/is_suspended.rb +4 -4
- data/lib/vagrant-libvirt/action/package_domain.rb +10 -4
- data/lib/vagrant-libvirt/action/start_domain.rb +86 -29
- data/lib/vagrant-libvirt/action/wait_till_up.rb +8 -52
- data/lib/vagrant-libvirt/cap/{mount_p9.rb → mount_9p.rb} +2 -2
- data/lib/vagrant-libvirt/cap/mount_virtiofs.rb +37 -0
- data/lib/vagrant-libvirt/cap/public_address.rb +16 -0
- data/lib/vagrant-libvirt/cap/{synced_folder.rb → synced_folder_9p.rb} +4 -5
- data/lib/vagrant-libvirt/cap/synced_folder_virtiofs.rb +109 -0
- data/lib/vagrant-libvirt/config.rb +257 -34
- data/lib/vagrant-libvirt/driver.rb +49 -32
- data/lib/vagrant-libvirt/errors.rb +24 -1
- data/lib/vagrant-libvirt/plugin.rb +19 -5
- data/lib/vagrant-libvirt/provider.rb +2 -9
- data/lib/vagrant-libvirt/templates/domain.xml.erb +40 -10
- data/lib/vagrant-libvirt/templates/private_network.xml.erb +1 -1
- data/lib/vagrant-libvirt/templates/public_interface.xml.erb +5 -1
- data/lib/vagrant-libvirt/util.rb +1 -0
- data/lib/vagrant-libvirt/util/erb_template.rb +6 -7
- data/lib/vagrant-libvirt/util/network_util.rb +21 -3
- data/lib/vagrant-libvirt/util/ui.rb +23 -0
- data/lib/vagrant-libvirt/version +1 -0
- data/lib/vagrant-libvirt/version.rb +72 -1
- data/locales/en.yml +12 -0
- data/spec/spec_helper.rb +37 -3
- data/spec/support/binding_proc.rb +24 -0
- data/spec/support/libvirt_context.rb +3 -1
- data/spec/support/matchers/have_file_content.rb +63 -0
- data/spec/support/sharedcontext.rb +7 -3
- data/spec/unit/action/clean_machine_folder_spec.rb +48 -0
- data/spec/unit/action/create_domain_spec.rb +166 -0
- data/spec/unit/action/create_domain_spec/default_system_storage_pool.xml +17 -0
- data/spec/unit/action/create_domain_spec/default_user_storage_pool.xml +17 -0
- data/spec/unit/action/create_domain_volume_spec.rb +102 -0
- data/spec/unit/action/create_domain_volume_spec/one_disk_in_storage.xml +21 -0
- data/spec/unit/action/create_domain_volume_spec/three_disks_in_storage_disk_0.xml +21 -0
- data/spec/unit/action/create_domain_volume_spec/three_disks_in_storage_disk_1.xml +21 -0
- data/spec/unit/action/create_domain_volume_spec/three_disks_in_storage_disk_2.xml +21 -0
- data/spec/unit/action/destroy_domain_spec.rb +3 -3
- data/spec/unit/action/forward_ports_spec.rb +202 -0
- data/spec/unit/action/halt_domain_spec.rb +90 -0
- data/spec/unit/action/handle_box_image_spec.rb +363 -0
- data/spec/unit/action/set_name_of_domain_spec.rb +2 -2
- data/spec/unit/action/start_domain_spec.rb +231 -0
- data/spec/unit/action/start_domain_spec/clock_timer_rtc.xml +50 -0
- data/spec/unit/action/start_domain_spec/default.xml +48 -0
- data/spec/unit/action/start_domain_spec/default_added_tpm_path.xml +48 -0
- data/spec/unit/action/start_domain_spec/default_added_tpm_version.xml +48 -0
- data/spec/unit/action/wait_till_up_spec.rb +22 -21
- data/spec/unit/config_spec.rb +438 -0
- data/spec/unit/provider_spec.rb +11 -0
- data/spec/unit/templates/domain_all_settings.xml +16 -3
- data/spec/unit/templates/domain_custom_cpu_model.xml +4 -1
- data/spec/unit/templates/domain_defaults.xml +4 -1
- data/spec/unit/templates/domain_spec.rb +102 -3
- data/spec/unit/templates/tpm/version_1.2.xml +54 -0
- data/spec/unit/templates/tpm/version_2.0.xml +53 -0
- metadata +108 -16
- data/lib/vagrant-libvirt/action/halt_confirm.rb +0 -20
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: af89387fcdeb6518bd31879ac2eaa00373c3af1c02613b389868eb6c656b5f2b
|
4
|
+
data.tar.gz: 82fa3560eb88abac51088e894d8e475bbf4dbcda4b10596b43e7fc41d158945a
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 53d1714279eaa3ed9c0434b891bad6bc03b4f52a0c2a5aed6e0736cefa89a3f66243ec3d04e2bf1bb707f76169e2f799ffa98e63f3cfdc3c91ee0d56e5332695
|
7
|
+
data.tar.gz: 15ea6d1ce672545f14f3886a6d945f2349c85cca61a63604abf30f5a716b9665c65ea181fd2dcb96c39321567725911b230d22d1c589c888a2b05ec9c7715b13
|
data/README.md
CHANGED
@@ -16,54 +16,61 @@ can help a lot :-)
|
|
16
16
|
<!-- note in vim set "let g:vmt_list_item_char='-'" to generate the correct output -->
|
17
17
|
<!-- vim-markdown-toc GFM -->
|
18
18
|
|
19
|
-
|
20
|
-
|
21
|
-
|
22
|
-
|
23
|
-
|
24
|
-
|
25
|
-
|
26
|
-
|
27
|
-
|
28
|
-
|
29
|
-
|
30
|
-
|
31
|
-
|
32
|
-
|
33
|
-
|
34
|
-
|
35
|
-
|
36
|
-
|
37
|
-
|
38
|
-
|
39
|
-
|
40
|
-
|
41
|
-
|
42
|
-
|
43
|
-
|
44
|
-
|
45
|
-
|
46
|
-
|
47
|
-
|
48
|
-
|
49
|
-
|
50
|
-
|
51
|
-
|
52
|
-
|
53
|
-
|
54
|
-
|
55
|
-
|
56
|
-
|
57
|
-
|
58
|
-
|
59
|
-
|
60
|
-
|
61
|
-
|
62
|
-
|
63
|
-
|
64
|
-
|
65
|
-
|
66
|
-
|
19
|
+
* [Features](#features)
|
20
|
+
* [Future work](#future-work)
|
21
|
+
* [Using Docker based Installation](#using-docker-based-installation)
|
22
|
+
* [Installation](#installation)
|
23
|
+
* [Possible problems with plugin installation on Linux](#possible-problems-with-plugin-installation-on-linux)
|
24
|
+
* [Additional Notes for Fedora and Similar Linux Distributions](#additional-notes-for-fedora-and-similar-linux-distributions)
|
25
|
+
* [Vagrant Project Preparation](#vagrant-project-preparation)
|
26
|
+
* [Add Box](#add-box)
|
27
|
+
* [Create Vagrantfile](#create-vagrantfile)
|
28
|
+
* [Start VM](#start-vm)
|
29
|
+
* [How Project Is Created](#how-project-is-created)
|
30
|
+
* [Libvirt Configuration](#libvirt-configuration)
|
31
|
+
* [Provider Options](#provider-options)
|
32
|
+
* [Domain Specific Options](#domain-specific-options)
|
33
|
+
* [Reload behavior](#reload-behavior)
|
34
|
+
* [Networks](#networks)
|
35
|
+
* [Private Network Options](#private-network-options)
|
36
|
+
* [Public Network Options](#public-network-options)
|
37
|
+
* [Management Network](#management-network)
|
38
|
+
* [Additional Disks](#additional-disks)
|
39
|
+
* [Reload behavior](#reload-behavior-1)
|
40
|
+
* [CDROMs](#cdroms)
|
41
|
+
* [Input](#input)
|
42
|
+
* [PCI device passthrough](#pci-device-passthrough)
|
43
|
+
* [Using USB Devices](#using-usb-devices)
|
44
|
+
* [USB Controller Configuration](#usb-controller-configuration)
|
45
|
+
* [USB Device Passthrough](#usb-device-passthrough)
|
46
|
+
* [USB Redirector Devices](#usb-redirector-devices)
|
47
|
+
* [Filter for USB Redirector Devices](#filter-for-usb-redirector-devices)
|
48
|
+
* [Random number generator passthrough](#random-number-generator-passthrough)
|
49
|
+
* [Watchdog device](#watchdog-device)
|
50
|
+
* [Smartcard device](#smartcard-device)
|
51
|
+
* [Hypervisor Features](#hypervisor-features)
|
52
|
+
* [Clock](#clock)
|
53
|
+
* [CPU features](#cpu-features)
|
54
|
+
* [Memory Backing](#memory-backing)
|
55
|
+
* [No box and PXE boot](#no-box-and-pxe-boot)
|
56
|
+
* [SSH Access To VM](#ssh-access-to-vm)
|
57
|
+
* [Forwarded Ports](#forwarded-ports)
|
58
|
+
* [Forwarding the ssh-port](#forwarding-the-ssh-port)
|
59
|
+
* [Synced Folders](#synced-folders)
|
60
|
+
* [QEMU Session Support](#qemu-session-support)
|
61
|
+
* [Customized Graphics](#customized-graphics)
|
62
|
+
* [TPM Devices](#tpm-devices)
|
63
|
+
* [Memory balloon](#memory-balloon)
|
64
|
+
* [Libvirt communication channels](#libvirt-communication-channels)
|
65
|
+
* [Custom command line arguments and environment variables](#custom-command-line-arguments-and-environment-variables)
|
66
|
+
* [Box Formats](#box-formats)
|
67
|
+
* [Version 1](#version-1)
|
68
|
+
* [Version 2 (Experimental)](#version-2-experimental)
|
69
|
+
* [Create Box](#create-box)
|
70
|
+
* [Package Box from VM](#package-box-from-vm)
|
71
|
+
* [Troubleshooting VMs](#troubleshooting-vms)
|
72
|
+
* [Development](#development)
|
73
|
+
* [Contributing](#contributing)
|
67
74
|
|
68
75
|
<!-- vim-markdown-toc -->
|
69
76
|
|
@@ -79,7 +86,7 @@ can help a lot :-)
|
|
79
86
|
* SSH into domains.
|
80
87
|
* Setup hostname and network interfaces.
|
81
88
|
* Provision domains with any built-in Vagrant provisioner.
|
82
|
-
* Synced folder support via `rsync`, `nfs` or `
|
89
|
+
* Synced folder support via `rsync`, `nfs`, `9p` or `virtiofs`.
|
83
90
|
* Snapshots via [sahara](https://github.com/jedi4ever/sahara).
|
84
91
|
* Package caching via
|
85
92
|
[vagrant-cachier](http://fgrehm.viewdocs.io/vagrant-cachier/).
|
@@ -92,6 +99,61 @@ can help a lot :-)
|
|
92
99
|
* Take a look at [open
|
93
100
|
issues](https://github.com/vagrant-libvirt/vagrant-libvirt/issues?state=open).
|
94
101
|
|
102
|
+
## Using Docker based Installation
|
103
|
+
|
104
|
+
Due to the number of issues encountered around compatibility between the ruby runtime environment
|
105
|
+
that is part of the upstream vagrant installation and the library dependencies of libvirt that
|
106
|
+
this project requires to communicate with libvirt, there is a docker image build and published.
|
107
|
+
|
108
|
+
This should allow users to execute vagrant with vagrant-libvirt without needing to deal with
|
109
|
+
the compatibility issues, though you may need to extend the image for your own needs should
|
110
|
+
you make use of additional plugins.
|
111
|
+
|
112
|
+
To get the image:
|
113
|
+
```bash
|
114
|
+
docker pull vagrantlibvirt/vagrant-libvirt:latest
|
115
|
+
```
|
116
|
+
|
117
|
+
Preparing the docker run, only once:
|
118
|
+
|
119
|
+
```bash
|
120
|
+
mkdir -p ~/.vagrant.d/{boxes,data,tmp}
|
121
|
+
```
|
122
|
+
|
123
|
+
Running the image:
|
124
|
+
```bash
|
125
|
+
docker run -it --rm \
|
126
|
+
-e LIBVIRT_DEFAULT_URI \
|
127
|
+
-v /var/run/libvirt/:/var/run/libvirt/ \
|
128
|
+
-v ~/.vagrant.d:/.vagrant.d \
|
129
|
+
-v $(pwd):$(pwd) \
|
130
|
+
-w $(pwd) \
|
131
|
+
--network host \
|
132
|
+
vagrantlibvirt/vagrant-libvirt:latest \
|
133
|
+
vagrant status
|
134
|
+
```
|
135
|
+
|
136
|
+
It's possible to define an alias in `~/.bashrc`, for example:
|
137
|
+
```bash
|
138
|
+
alias vagrant='
|
139
|
+
mkdir -p ~/.vagrant.d/{boxes,data,tmp}; \
|
140
|
+
docker run -it --rm \
|
141
|
+
-e LIBVIRT_DEFAULT_URI \
|
142
|
+
-v /var/run/libvirt/:/var/run/libvirt/ \
|
143
|
+
-v ~/.vagrant.d:/.vagrant.d \
|
144
|
+
-v $(pwd):$(pwd) \
|
145
|
+
-w $(pwd) \
|
146
|
+
--network host \
|
147
|
+
vagrantlibvirt/vagrant-libvirt:latest \
|
148
|
+
vagrant'
|
149
|
+
```
|
150
|
+
|
151
|
+
Note that if you are connecting to a remote system libvirt, you may omit the
|
152
|
+
`-v /var/run/libvirt/:/var/run/libvirt/` mount bind. Some distributions patch the local
|
153
|
+
vagrant environment to ensure vagrant-libvirt uses `qemu:///session`, which means you
|
154
|
+
may need to set the environment variable `LIBVIRT_DEFAULT_URI` to the same value if
|
155
|
+
looking to use this in place of your distribution provided installation.
|
156
|
+
|
95
157
|
## Installation
|
96
158
|
|
97
159
|
First, you should have both QEMU and Libvirt installed if you plan to run VMs
|
@@ -197,6 +259,69 @@ If you have issues building ruby-libvirt, try the following:
|
|
197
259
|
```shell
|
198
260
|
CONFIGURE_ARGS='with-ldflags=-L/opt/vagrant/embedded/lib with-libvirt-include=/usr/include/libvirt with-libvirt-lib=/usr/lib' GEM_HOME=~/.vagrant.d/gems GEM_PATH=$GEM_HOME:/opt/vagrant/embedded/gems PATH=/opt/vagrant/embedded/bin:$PATH vagrant plugin install vagrant-libvirt
|
199
261
|
```
|
262
|
+
### Additional Notes for Fedora and Similar Linux Distributions
|
263
|
+
|
264
|
+
If you encounter the following load error when using the vagrant-libvirt plugin (note the required by libssh):
|
265
|
+
|
266
|
+
```shell
|
267
|
+
/opt/vagrant/embedded/lib/ruby/2.4.0/rubygems/core_ext/kernel_require.rb:55:in `require': /opt/vagrant/embedded/lib64/libcrypto.so.1.1: version `OPENSSL_1_1_1b' not found (required by /lib64/libssh.so.4) - /home/xxx/.vagrant.d/gems/2.4.6/gems/ruby-libvirt-0.7.1/lib/_libvirt.so (LoadError)
|
268
|
+
```
|
269
|
+
then the following steps have been found to resolve the problem. Thanks to James Reynolds (see https://github.com/hashicorp/vagrant/issues/11020#issuecomment-540043472). The specific version of libssh will change over time so references to the rpm in the commands below will need to be adjusted accordingly.
|
270
|
+
|
271
|
+
```shell
|
272
|
+
# Fedora
|
273
|
+
dnf download --source libssh
|
274
|
+
|
275
|
+
# centos 8 stream, doesn't provide source RPMs, so you need to download like so
|
276
|
+
git clone https://git.centos.org/centos-git-common
|
277
|
+
# centos-git-common needs its tools in PATH
|
278
|
+
export PATH=$(readlink -f ./centos-git-common):$PATH
|
279
|
+
git clone https://git.centos.org/rpms/libssh
|
280
|
+
cd libssh
|
281
|
+
git checkout imports/c8s/libssh-0.9.4-1.el8
|
282
|
+
into_srpm.sh -d c8s
|
283
|
+
cd SRPMS
|
284
|
+
|
285
|
+
# common commands (make sure to adjust verison accordingly)
|
286
|
+
rpm2cpio libssh-0.9.0-5.fc30.src.rpm | cpio -imdV
|
287
|
+
tar xf libssh-0.9.0.tar.xz
|
288
|
+
mkdir build
|
289
|
+
cd build
|
290
|
+
cmake ../libssh-0.9.0 -DOPENSSL_ROOT_DIR=/opt/vagrant/embedded/
|
291
|
+
make
|
292
|
+
sudo cp lib/libssh* /opt/vagrant/embedded/lib64
|
293
|
+
```
|
294
|
+
|
295
|
+
If you encounter the following load error when using the vagrant-libvirt plugin (note the required by libk5crypto):
|
296
|
+
|
297
|
+
```shell
|
298
|
+
/opt/vagrant/embedded/lib/ruby/2.4.0/rubygems/core_ext/kernel_require.rb:55:in `require': /usr/lib64/libk5crypto.so.3: undefined symbol: EVP_KDF_ctrl, version OPENSSL_1_1_1b - /home/rbelgrave/.vagrant.d/gems/2.4.9/gems/ruby-libvirt-0.7.1/lib/_libvirt.so (LoadError)
|
299
|
+
```
|
300
|
+
|
301
|
+
then the following steps have been found to resolve the problem. After the steps below are complete, then reinstall the vagrant-libvirt plugin without setting the `CONFIGURE_ARGS`. Thanks to Marco Bevc (see https://github.com/hashicorp/vagrant/issues/11020#issuecomment-625801983):
|
302
|
+
|
303
|
+
```shell
|
304
|
+
# Fedora
|
305
|
+
dnf download --source krb5-libs
|
306
|
+
|
307
|
+
# centos 8 stream, doesn't provide source RPMs, so you need to download like so
|
308
|
+
git clone https://git.centos.org/centos-git-common
|
309
|
+
# centos-git-common needs its tools in PATH
|
310
|
+
export PATH=$(readlink -f ./centos-git-common):$PATH
|
311
|
+
git clone https://git.centos.org/rpms/krb5
|
312
|
+
cd krb5
|
313
|
+
git checkout imports/c8s/krb5-1.18.2-8.el8
|
314
|
+
into_srpm.sh -d c8s
|
315
|
+
cd SRPMS
|
316
|
+
|
317
|
+
# common commands (make sure to adjust verison accordingly)
|
318
|
+
rpm2cpio krb5-1.18-1.fc32.src.rpm | cpio -imdV
|
319
|
+
tar xf krb5-1.18.tar.gz
|
320
|
+
cd krb5-1.18/src
|
321
|
+
./configure
|
322
|
+
make
|
323
|
+
sudo cp -P lib/crypto/libk5crypto.* /opt/vagrant/embedded/lib64/
|
324
|
+
```
|
200
325
|
|
201
326
|
## Vagrant Project Preparation
|
202
327
|
|
@@ -210,7 +335,7 @@ You can find more Libvirt-ready boxes at
|
|
210
335
|
example:
|
211
336
|
|
212
337
|
```shell
|
213
|
-
vagrant init fedora/
|
338
|
+
vagrant init fedora/32-cloud-base
|
214
339
|
```
|
215
340
|
|
216
341
|
### Create Vagrantfile
|
@@ -221,7 +346,7 @@ information where necessary. For example:
|
|
221
346
|
```ruby
|
222
347
|
Vagrant.configure("2") do |config|
|
223
348
|
config.vm.define :test_vm do |test_vm|
|
224
|
-
test_vm.vm.box = "fedora/
|
349
|
+
test_vm.vm.box = "fedora/32-cloud-base"
|
225
350
|
end
|
226
351
|
end
|
227
352
|
```
|
@@ -278,14 +403,32 @@ URI](http://libvirt.org/uri.html):
|
|
278
403
|
Default is `$HOME/.ssh/id_rsa`. Prepends `$HOME/.ssh/` if no directory
|
279
404
|
* `socket` - Path to the Libvirt unix socket (e.g.
|
280
405
|
`/var/run/libvirt/libvirt-sock`)
|
406
|
+
* `proxy_command` - For advanced usage. When connecting to remote libvirt
|
407
|
+
instances, if the default constructed proxy\_command which uses `-W %h:%p`
|
408
|
+
does not work, set this as needed. It performs interpolation using `{key}`
|
409
|
+
and supports only `{host}`, `{username}`, and `{id_ssh_key_file}`. This is
|
410
|
+
to try and avoid issues with escaping `%` and `$` which might be necessary
|
411
|
+
to the ssh command itself. e.g.:
|
412
|
+
`libvirt.proxy_command = "ssh {host} -l {username} -i {id_ssh_key_file} nc %h %p"`
|
281
413
|
* `uri` - For advanced usage. Directly specifies what Libvirt connection URI
|
282
414
|
vagrant-libvirt should use. Overrides all other connection configuration
|
283
415
|
options
|
284
416
|
|
417
|
+
In the event that none of these are set (excluding the `driver` option) the
|
418
|
+
provider will attempt to retrieve the uri from the environment variable
|
419
|
+
`LIBVIRT_DEFAULT_URI` similar to how virsh works. If any of them are set, it
|
420
|
+
will ignore the environment variable. The reason the driver option is ignored
|
421
|
+
is that it is not uncommon for this to be explicitly set on the box itself
|
422
|
+
and there is no easily to determine whether it is being set by the user or
|
423
|
+
the box packager.
|
424
|
+
|
285
425
|
Connection-independent options:
|
286
426
|
|
287
427
|
* `storage_pool_name` - Libvirt storage pool name, where box image and instance
|
288
|
-
snapshots will be stored.
|
428
|
+
snapshots (if `snapshot_pool_name` is not set) will be stored.
|
429
|
+
* `snapshot_pool_name` - Libvirt storage pool name. If set, the created
|
430
|
+
snapshot of the instance will be stored at this location instead of
|
431
|
+
`storage_pool_name`.
|
289
432
|
|
290
433
|
For example:
|
291
434
|
|
@@ -299,6 +442,8 @@ end
|
|
299
442
|
|
300
443
|
### Domain Specific Options
|
301
444
|
|
445
|
+
* `title` - A short description of the domain.
|
446
|
+
* `description` - A human readable description of the virtual machine.
|
302
447
|
* `disk_bus` - The type of disk device to emulate. Defaults to virtio if not
|
303
448
|
set. Possible values are documented in Libvirt's [description for
|
304
449
|
_target_](http://libvirt.org/formatdomain.html#elementsDisks). NOTE: this
|
@@ -308,6 +453,14 @@ end
|
|
308
453
|
set, which should be fine for paravirtualized guests, but some fully
|
309
454
|
virtualized guests may require hda. NOTE: this option also applies only to
|
310
455
|
disks associated with a box image.
|
456
|
+
* `disk_driver` - Extra options for the main disk driver ([see Libvirt documentation](http://libvirt.org/formatdomain.html#elementsDisks)).
|
457
|
+
NOTE: this option also applies only to disks associated with a box image. In all cases, the value `nil` can be used to force the hypervisor default behaviour (e.g. to override settings defined in top-level Vagrantfiles). Supported options include:
|
458
|
+
* `:cache` - Controls the cache mechanism. Possible values are "default", "none", "writethrough", "writeback", "directsync" and "unsafe".
|
459
|
+
* `:io` - Controls specific policies on I/O. Possible values are "threads" and "native".
|
460
|
+
* `:copy_on_read` - Controls whether to copy read backing file into the image file. The value can be either "on" or "off".
|
461
|
+
* `:discard` - Controls whether discard requests (also known as "trim" or "unmap") are ignored or passed to the filesystem. Possible values are "unmap" or "ignore".
|
462
|
+
Note: for discard to work, you will likely also need to set `disk_bus = 'scsi'`
|
463
|
+
* `:detect_zeroes` - Controls whether to detect zero write requests. The value can be "off", "on" or "unmap".
|
311
464
|
* `nic_model_type` - parameter specifies the model of the network adapter when
|
312
465
|
you create a domain value by default virtio KVM believe possible values, see
|
313
466
|
the [documentation for
|
@@ -353,10 +506,6 @@ end
|
|
353
506
|
]
|
354
507
|
```
|
355
508
|
* `loader` - Sets path to custom UEFI loader.
|
356
|
-
* `volume_cache` - Controls the cache mechanism. Possible values are "default",
|
357
|
-
"none", "writethrough", "writeback", "directsync" and "unsafe". [See
|
358
|
-
driver->cache in Libvirt
|
359
|
-
documentation](http://libvirt.org/formatdomain.html#elementsDisks).
|
360
509
|
* `kernel` - To launch the guest with a kernel residing on host filesystems.
|
361
510
|
Equivalent to qemu `-kernel`.
|
362
511
|
* `initrd` - To specify the initramfs/initrd to use for the guest. Equivalent
|
@@ -428,6 +577,7 @@ end
|
|
428
577
|
* `tpm_model` - The model of the TPM to which you wish to connect.
|
429
578
|
* `tpm_type` - The type of TPM device to which you are connecting.
|
430
579
|
* `tpm_path` - The path to the TPM device on the host system.
|
580
|
+
* `tpm_version` - The TPM version to use.
|
431
581
|
* `dtb` - The device tree blob file, mostly used for non-x86 platforms. In case
|
432
582
|
the device tree isn't added in-line to the kernel, it can be manually
|
433
583
|
specified here.
|
@@ -456,7 +606,7 @@ Vagrant.configure("2") do |config|
|
|
456
606
|
domain.memory = 2048
|
457
607
|
domain.cpus = 2
|
458
608
|
domain.nested = true
|
459
|
-
domain.
|
609
|
+
domain.disk_driver :cache => 'none'
|
460
610
|
end
|
461
611
|
end
|
462
612
|
|
@@ -503,6 +653,7 @@ defined domain:
|
|
503
653
|
* `tpm_model` - Updated
|
504
654
|
* `tpm_type` - Updated
|
505
655
|
* `tpm_path` - Updated
|
656
|
+
* `tpm_version` - Updated
|
506
657
|
|
507
658
|
## Networks
|
508
659
|
|
@@ -632,8 +783,8 @@ starts with `libvirt__` string. Here is a list of those options:
|
|
632
783
|
only when dhcp is enabled.By default is the same host that runs the DHCP
|
633
784
|
server.
|
634
785
|
* `:libvirt__adapter` - Number specifiyng sequence number of interface.
|
635
|
-
* `:libvirt__forward_mode` - Specify one of `veryisolated`, `none`, `nat`
|
636
|
-
`route` options. This option is used only when creating new network. Mode
|
786
|
+
* `:libvirt__forward_mode` - Specify one of `veryisolated`, `none`, `open`, `nat`
|
787
|
+
or `route` options. This option is used only when creating new network. Mode
|
637
788
|
`none` will create isolated network without NATing or routing outside. You
|
638
789
|
will want to use NATed forwarding typically to reach networks outside of
|
639
790
|
hypervisor. Routed forwarding is typically useful to reach other networks
|
@@ -712,6 +863,7 @@ virtual network.
|
|
712
863
|
* `:portgroup` - Name of Libvirt portgroup to connect to.
|
713
864
|
* `:ovs` - Support to connect to an Open vSwitch bridge device. Default is
|
714
865
|
'false'.
|
866
|
+
* :ovs_interfaceid - Add Open vSwitch 'interfaceid' parameter.
|
715
867
|
* `:trust_guest_rx_filters` - Support trustGuestRxFilters attribute. Details
|
716
868
|
are listed [here](http://www.libvirt.org/formatdomain.html#elementsNICSDirect).
|
717
869
|
Default is 'false'.
|
@@ -730,8 +882,8 @@ used by this network are configurable at the provider level.
|
|
730
882
|
connected. Must include the address and subnet mask. If not specified the
|
731
883
|
default is '192.168.121.0/24'.
|
732
884
|
* `management_network_mode` - Network mode for the Libvirt management network.
|
733
|
-
Specify one of veryisolated, none, nat or route options. Further
|
734
|
-
under [Private Networks](#private-network-options)
|
885
|
+
Specify one of veryisolated, none, open, nat or route options. Further
|
886
|
+
documented under [Private Networks](#private-network-options)
|
735
887
|
* `management_network_guest_ipv6` - Enable or disable guest-to-guest IPv6
|
736
888
|
communication. See
|
737
889
|
[here](https://libvirt.org/formatnetwork.html#examplesPrivate6), and
|
@@ -743,6 +895,8 @@ used by this network are configurable at the provider level.
|
|
743
895
|
* `management_network_pci_slot` - The slot of the PCI device.
|
744
896
|
* `management_network_mac` - MAC address of management network interface.
|
745
897
|
* `management_network_domain` - Domain name assigned to the management network.
|
898
|
+
* `management_network_mtu` - MTU size of management network. If not specified,
|
899
|
+
the Libvirt default (1500) will be used.
|
746
900
|
|
747
901
|
You may wonder how vagrant-libvirt knows the IP address a VM received. Libvirt
|
748
902
|
doesn't provide a standard way to find out the IP address of a running domain.
|
@@ -764,16 +918,24 @@ It has a number of options:
|
|
764
918
|
* `size` - Size of the disk image. If unspecified, defaults to 10G.
|
765
919
|
* `type` - Type of disk image to create. Defaults to *qcow2*.
|
766
920
|
* `bus` - Type of bus to connect device to. Defaults to *virtio*.
|
767
|
-
* `cache` - Cache mode to use, e.g. `none`, `writeback`, `writethrough` (see
|
768
|
-
the [libvirt documentation for possible
|
769
|
-
values](http://libvirt.org/formatdomain.html#elementsDisks) or
|
770
|
-
[here](https://www.suse.com/documentation/sles11/book_kvm/data/sect1_chapter_book_kvm.html)
|
771
|
-
for a fuller explanation). Defaults to *default*.
|
772
921
|
* `allow_existing` - Set to true if you want to allow the VM to use a
|
773
922
|
pre-existing disk. If the disk doesn't exist it will be created.
|
774
923
|
Disks with this option set to true need to be removed manually.
|
775
924
|
* `shareable` - Set to true if you want to simulate shared SAN storage.
|
776
925
|
* `serial` - Serial number of the disk device.
|
926
|
+
* `wwn` - WWN number of the disk device.
|
927
|
+
|
928
|
+
The following disk performance options can also be configured
|
929
|
+
(see the [libvirt documentation for possible values](http://libvirt.org/formatdomain.html#elementsDisks)
|
930
|
+
or [here](https://www.suse.com/documentation/sles11/book_kvm/data/sect1_chapter_book_kvm.html) for a fuller explanation).
|
931
|
+
In all cases, the options use the hypervisor default if not specified, or if set to `nil`.
|
932
|
+
|
933
|
+
* `cache` - Cache mode to use. Value may be `default`, `none`, `writeback`, `writethrough`, `directsync` or `unsafe`.
|
934
|
+
* `io` - Controls specific policies on I/O. Value may be `threads` or `native`.
|
935
|
+
* `copy_on_read` - Controls whether to copy read backing file into the image file. Value may be `on` or `off`.
|
936
|
+
* `discard` - Controls whether discard requests (also known as "trim" or "unmap") are ignored or passed to the filesystem. Value may be `unmap` or `ignore`.
|
937
|
+
Note: for discard to work, you will likely also need to set `:bus => 'scsi'`
|
938
|
+
* `detect_zeroes` - Controls whether to detect zero write requests. Value may be `off`, `on` or `unmap`.
|
777
939
|
|
778
940
|
The following example creates two additional disks.
|
779
941
|
|
@@ -781,7 +943,7 @@ The following example creates two additional disks.
|
|
781
943
|
Vagrant.configure("2") do |config|
|
782
944
|
config.vm.provider :libvirt do |libvirt|
|
783
945
|
libvirt.storage :file, :size => '20G'
|
784
|
-
libvirt.storage :file, :size => '40G', :type => 'raw'
|
946
|
+
libvirt.storage :file, :size => '40G', :bus => 'scsi', :type => 'raw', :discard => 'unmap', :detect_zeroes => 'on'
|
785
947
|
end
|
786
948
|
end
|
787
949
|
```
|
@@ -1099,6 +1261,29 @@ Vagrant.configure("2") do |config|
|
|
1099
1261
|
libvirt.hyperv_feature :name => 'relaxed', :state => 'on'
|
1100
1262
|
# Enable virtual APIC
|
1101
1263
|
libvirt.hyperv_feature :name => 'vapic', :state => 'on'
|
1264
|
+
# Enable spinlocks (requires retries to be specified)
|
1265
|
+
libvirt.hyperv_feature :name => 'spinlocks', :state => 'on', :retries => '8191'
|
1266
|
+
end
|
1267
|
+
end
|
1268
|
+
```
|
1269
|
+
|
1270
|
+
## Clock
|
1271
|
+
|
1272
|
+
Clock offset can be specified via `libvirt.clock_offset`. (Default is utc)
|
1273
|
+
|
1274
|
+
Additionally timers can be specified via `libvirt.clock_timer`.
|
1275
|
+
Available options for timers are: name, track, tickpolicy, frequency, mode, present
|
1276
|
+
|
1277
|
+
```ruby
|
1278
|
+
Vagrant.configure("2") do |config|
|
1279
|
+
config.vm.provider :libvirt do |libvirt|
|
1280
|
+
# Set clock offset to localtime
|
1281
|
+
libvirt.clock_offset = 'localtime'
|
1282
|
+
# Timers ...
|
1283
|
+
libvirt.clock_timer :name => 'rtc', :tickpolicy => 'catchup'
|
1284
|
+
libvirt.clock_timer :name => 'pit', :tickpolicy => 'delay'
|
1285
|
+
libvirt.clock_timer :name => 'hpet', :present => 'no'
|
1286
|
+
libvirt.clock_timer :name => 'hypervclock', :present => 'yes'
|
1102
1287
|
end
|
1103
1288
|
end
|
1104
1289
|
```
|
@@ -1234,40 +1419,157 @@ Default is `eth0`.
|
|
1234
1419
|
|
1235
1420
|
`config.vm.network :forwarded_port, guest: 80, host: 2000, host_ip: "0.0.0.0"`
|
1236
1421
|
|
1422
|
+
### Forwarding the ssh-port
|
1423
|
+
|
1424
|
+
Vagrant-libvirt now supports forwarding the standard ssh-port on port 2222 from
|
1425
|
+
the localhost to allow for consistent provisioning steps/ports to be used when
|
1426
|
+
defining across multiple providers.
|
1427
|
+
|
1428
|
+
To enable, set the following:
|
1429
|
+
```ruby
|
1430
|
+
Vagrant.configure("2") do |config|
|
1431
|
+
config.vm.provider :libvirt do |libvirt|
|
1432
|
+
# Enable forwarding of forwarded_port with id 'ssh'.
|
1433
|
+
libvirt.forward_ssh_port = true
|
1434
|
+
end
|
1435
|
+
end
|
1436
|
+
```
|
1437
|
+
|
1438
|
+
Previously by default libvirt skipped the forwarding of the ssh-port because
|
1439
|
+
you can access the machine directly. In the future it is expected that this
|
1440
|
+
will be enabled by default once autocorrect support is added to handle port
|
1441
|
+
collisions for multi machine environments gracefully.
|
1442
|
+
|
1237
1443
|
## Synced Folders
|
1238
1444
|
|
1239
|
-
Vagrant automatically syncs the project folder on the host to `/vagrant` in
|
1240
|
-
additional synced folders.
|
1445
|
+
Vagrant automatically syncs the project folder on the host to `/vagrant` in
|
1446
|
+
the guest. You can also configure additional synced folders.
|
1241
1447
|
|
1242
|
-
|
1243
|
-
|
1448
|
+
**SECURITY NOTE:** for remote Libvirt, nfs synced folders requires a bridged
|
1449
|
+
public network interface and you must connect to Libvirt via ssh.
|
1244
1450
|
|
1245
|
-
|
1246
|
-
it an setting the type, e.g.
|
1451
|
+
**NFS**
|
1247
1452
|
|
1248
|
-
|
1249
|
-
|
1250
|
-
|
1453
|
+
`vagrant-libvirt` supports
|
1454
|
+
[NFS](https://www.vagrantup.com/docs/synced-folders/nfs) as default with
|
1455
|
+
bidirectional synced folders.
|
1251
1456
|
|
1252
|
-
|
1457
|
+
Example with NFS:
|
1253
1458
|
|
1254
|
-
```
|
1255
|
-
|
1459
|
+
``` ruby
|
1460
|
+
Vagrant.configure("2") do |config|
|
1461
|
+
config.vm.synced_folder "./", "/vagrant"
|
1462
|
+
end
|
1256
1463
|
```
|
1257
1464
|
|
1258
|
-
|
1465
|
+
**RSync**
|
1259
1466
|
|
1260
|
-
|
1261
|
-
|
1467
|
+
`vagrant-libvirt` supports
|
1468
|
+
[rsync](https://www.vagrantup.com/docs/synced-folders/rsync) with
|
1469
|
+
unidirectional synced folders.
|
1470
|
+
|
1471
|
+
Example with rsync:
|
1472
|
+
|
1473
|
+
``` ruby
|
1474
|
+
Vagrant.configure("2") do |config|
|
1475
|
+
config.vm.synced_folder "./", "/vagrant", type: "rsync"
|
1476
|
+
end
|
1262
1477
|
```
|
1263
1478
|
|
1479
|
+
**9P**
|
1480
|
+
|
1481
|
+
`vagrant-libvirt` supports [VirtFS](http://www.linux-kvm.org/page/VirtFS) ([9p
|
1482
|
+
or Plan 9](https://en.wikipedia.org/wiki/9P_\(protocol\))) with bidirectional
|
1483
|
+
synced folders.
|
1484
|
+
|
1485
|
+
Difference between NFS and 9p is explained
|
1486
|
+
[here](https://unix.stackexchange.com/questions/240281/virtfs-plan-9-vs-nfs-as-tool-for-share-folder-for-virtual-machine).
|
1487
|
+
|
1264
1488
|
For 9p shares, a `mount: false` option allows to define synced folders without
|
1265
1489
|
mounting them at boot.
|
1266
1490
|
|
1267
|
-
|
1491
|
+
Example for `accessmode: "squash"` with 9p:
|
1268
1492
|
|
1269
|
-
|
1270
|
-
|
1493
|
+
``` ruby
|
1494
|
+
Vagrant.configure("2") do |config|
|
1495
|
+
config.vm.synced_folder "./", "/vagrant", type: "9p", disabled: false, accessmode: "squash", owner: "1000"
|
1496
|
+
end
|
1497
|
+
```
|
1498
|
+
|
1499
|
+
Example for `accessmode: "mapped"` with 9p:
|
1500
|
+
|
1501
|
+
``` ruby
|
1502
|
+
Vagrant.configure("2") do |config|
|
1503
|
+
config.vm.synced_folder "./", "/vagrant", type: "9p", disabled: false, accessmode: "mapped", mount: false
|
1504
|
+
end
|
1505
|
+
```
|
1506
|
+
|
1507
|
+
Further documentation on using 9p can be found in [kernel
|
1508
|
+
docs](https://www.kernel.org/doc/Documentation/filesystems/9p.txt) and in
|
1509
|
+
[QEMU
|
1510
|
+
wiki](https://wiki.qemu.org/Documentation/9psetup#Starting_the_Guest_directly).
|
1511
|
+
|
1512
|
+
Please do note that 9p depends on support in the guest and not all distros
|
1513
|
+
come with the 9p module by default.
|
1514
|
+
|
1515
|
+
**Virtio-fs**
|
1516
|
+
|
1517
|
+
`vagrant-libvirt` supports [Virtio-fs](https://virtio-fs.gitlab.io/) with
|
1518
|
+
bidirectional synced folders.
|
1519
|
+
|
1520
|
+
For virtiofs shares, a `mount: false` option allows to define synced folders
|
1521
|
+
without mounting them at boot.
|
1522
|
+
|
1523
|
+
So far, passthrough is the only supported access mode and it requires running
|
1524
|
+
the virtiofsd daemon as root.
|
1525
|
+
|
1526
|
+
QEMU needs to allocate the backing memory for all the guest RAM as shared
|
1527
|
+
memory, e.g. [Use file-backed
|
1528
|
+
memory](https://libvirt.org/kbase/virtiofs.html#host-setup) by enable
|
1529
|
+
`memory_backing_dir` option in `/etc/libvirt/qemu.conf`:
|
1530
|
+
|
1531
|
+
``` shell
|
1532
|
+
memory_backing_dir = "/dev/shm"
|
1533
|
+
```
|
1534
|
+
|
1535
|
+
Example for Libvirt \>= 6.2.0 (e.g. Ubuntu 20.10 with Linux 5.8.0 + QEMU 5.0 +
|
1536
|
+
Libvirt 6.6.0, i.e. NUMA nodes required) with virtiofs:
|
1537
|
+
|
1538
|
+
``` ruby
|
1539
|
+
Vagrant.configure("2") do |config|
|
1540
|
+
config.vm.provider :libvirt do |libvirt|
|
1541
|
+
libvirt.cpus = 2
|
1542
|
+
libvirt.numa_nodes = [{ :cpus => "0-1", :memory => 8192, :memAccess => "shared" }]
|
1543
|
+
libvirt.memorybacking :access, :mode => "shared"
|
1544
|
+
end
|
1545
|
+
config.vm.synced_folder "./", "/vagrant", type: "virtiofs"
|
1546
|
+
end
|
1547
|
+
```
|
1548
|
+
|
1549
|
+
Example for Libvirt \>= 6.9.0 (e.g. Ubuntu 21.04 with Linux 5.11.0 + QEMU 5.2 +
|
1550
|
+
Libvirt 7.0.0, or Ubuntu 20.04 + [PPA
|
1551
|
+
enabled](https://launchpad.net/~savoury1/+archive/ubuntu/virtualisation)) with
|
1552
|
+
virtiofs:
|
1553
|
+
|
1554
|
+
``` ruby
|
1555
|
+
Vagrant.configure("2") do |config|
|
1556
|
+
config.vm.provider :libvirt do |libvirt|
|
1557
|
+
libvirt.cpus = 2
|
1558
|
+
libvirt.memory = 8192
|
1559
|
+
libvirt.memorybacking :access, :mode => "shared"
|
1560
|
+
end
|
1561
|
+
config.vm.synced_folder "./", "/vagrant", type: "virtiofs"
|
1562
|
+
end
|
1563
|
+
```
|
1564
|
+
|
1565
|
+
Further documentation on using virtiofs can be found in [official
|
1566
|
+
HowTo](https://virtio-fs.gitlab.io/index.html#howto) and in [Libvirt
|
1567
|
+
KB](https://libvirt.org/kbase/virtiofs.html).
|
1568
|
+
|
1569
|
+
Please do note that virtiofs depends on:
|
1570
|
+
|
1571
|
+
- Host: Linux \>= 5.4, QEMU \>= 4.2 and Libvirt \>= 6.2 (e.g. Ubuntu 20.10)
|
1572
|
+
- Guest: Linux \>= 5.4 (e.g. Ubuntu 20.04)
|
1271
1573
|
|
1272
1574
|
## QEMU Session Support
|
1273
1575
|
|
@@ -1330,13 +1632,14 @@ Modern versions of Libvirt support connecting to TPM devices on the host
|
|
1330
1632
|
system. This allows you to enable Trusted Boot Extensions, among other
|
1331
1633
|
features, on your guest VMs.
|
1332
1634
|
|
1333
|
-
|
1334
|
-
configuration. However, advanced usage,
|
1335
|
-
TPM, may require modifying the
|
1635
|
+
To passthrough a hardware TPM, you will generally only need to modify the
|
1636
|
+
`tpm_path` variable in your guest configuration. However, advanced usage,
|
1637
|
+
such as the application of a Software TPM, may require modifying the
|
1638
|
+
`tpm_model`, `tpm_type` and `tpm_version` variables.
|
1336
1639
|
|
1337
|
-
The TPM options will only be used if you specify a TPM path
|
1338
|
-
any TPM options without specifying a path
|
1339
|
-
ignored.
|
1640
|
+
The TPM options will only be used if you specify a TPM path or version.
|
1641
|
+
Declarations of any TPM options without specifying a path or version will
|
1642
|
+
result in those options being ignored.
|
1340
1643
|
|
1341
1644
|
Here is an example of using the TPM options:
|
1342
1645
|
|
@@ -1350,6 +1653,41 @@ Vagrant.configure("2") do |config|
|
|
1350
1653
|
end
|
1351
1654
|
```
|
1352
1655
|
|
1656
|
+
It's also possible for Libvirt to start an emulated TPM device on the host.
|
1657
|
+
Requires `swtpm` and `swtpm-tools`
|
1658
|
+
|
1659
|
+
```ruby
|
1660
|
+
Vagrant.configure("2") do |config|
|
1661
|
+
config.vm.provider :libvirt do |libvirt|
|
1662
|
+
libvirt.tpm_model = "tpm-crb"
|
1663
|
+
libvirt.tpm_type = "emulator"
|
1664
|
+
libvirt.tpm_version = "2.0"
|
1665
|
+
end
|
1666
|
+
end
|
1667
|
+
```
|
1668
|
+
|
1669
|
+
## Memory balloon
|
1670
|
+
|
1671
|
+
The configuration of the memory balloon device can be overridden. By default,
|
1672
|
+
libvirt will automatically attach a memory balloon; this behavior is preserved
|
1673
|
+
by not configuring any memballoon-related options. The memory balloon can be
|
1674
|
+
explicitly disabled by setting `memballoon_enabled` to `false`. Setting
|
1675
|
+
`memballoon_enabled` to `true` will allow additional configuration of
|
1676
|
+
memballoon-related options.
|
1677
|
+
|
1678
|
+
Here is an example of using the memballoon options:
|
1679
|
+
|
1680
|
+
```ruby
|
1681
|
+
Vagrant.configure("2") do |config|
|
1682
|
+
config.vm.provider :libvirt do |libvirt|
|
1683
|
+
libvirt.memballoon_enabled = true
|
1684
|
+
libvirt.memballoon_model = 'virtio'
|
1685
|
+
libvirt.memballoon_pci_bus = '0x00'
|
1686
|
+
libvirt.memballoon_pci_slot = '0x0f'
|
1687
|
+
end
|
1688
|
+
end
|
1689
|
+
```
|
1690
|
+
|
1353
1691
|
## Libvirt communication channels
|
1354
1692
|
|
1355
1693
|
For certain functionality to be available within a guest, a private
|
@@ -1395,7 +1733,7 @@ For example:
|
|
1395
1733
|
|
1396
1734
|
```ruby
|
1397
1735
|
Vagrant.configure(2) do |config|
|
1398
|
-
config.vm.box = "fedora/
|
1736
|
+
config.vm.box = "fedora/32-cloud-base"
|
1399
1737
|
config.vm.provider :libvirt do |libvirt|
|
1400
1738
|
libvirt.channel :type => 'unix', :target_name => 'org.qemu.guest_agent.0', :target_type => 'virtio'
|
1401
1739
|
end
|
@@ -1438,7 +1776,11 @@ Vagrant.configure("2") do |config|
|
|
1438
1776
|
end
|
1439
1777
|
```
|
1440
1778
|
|
1441
|
-
## Box
|
1779
|
+
## Box Formats
|
1780
|
+
|
1781
|
+
### Version 1
|
1782
|
+
|
1783
|
+
This is the original format that most boxes currently use.
|
1442
1784
|
|
1443
1785
|
You can view an example box in the
|
1444
1786
|
[`example_box/directory`](https://github.com/vagrant-libvirt/vagrant-libvirt/tree/master/example_box).
|
@@ -1452,8 +1794,64 @@ The box is a tarball containing:
|
|
1452
1794
|
* `Vagrantfile` that does default settings for the provider-specific
|
1453
1795
|
configuration for this provider
|
1454
1796
|
|
1797
|
+
|
1798
|
+
### Version 2 (Experimental)
|
1799
|
+
|
1800
|
+
Due to the limitation of only being able to handle a single disk with the version 1 format, a new
|
1801
|
+
format was added to support boxes that need to specify multiple disks. This is still currently
|
1802
|
+
experimental and as such support for packaging has yet to be added. There is a script in the tools
|
1803
|
+
folder (tools/create_box_with_two_disks.sh) that should provide a guideline on how to create such
|
1804
|
+
a box for those that wish to experiment and provide early feedback.
|
1805
|
+
|
1806
|
+
At it's most basic, it expects an array of disks to allow a specific order to be presented. Disks
|
1807
|
+
will be attached in this order and as such assume device names base on this within the VM. The
|
1808
|
+
'path' attribute is required, and is expected to be relative to the base of the box. This should
|
1809
|
+
allow placing the disk images within a nested directory within the box if it useful for those
|
1810
|
+
with a larger number of disks. The name allows overriding the target volume name that will be
|
1811
|
+
used in the libvirt storage pool. Note that vagrant-libvirt will still prefix the volume name
|
1812
|
+
with `#{box_name}_vagrant_box_image_#{box_version}_` to avoid accidental clashes with other boxes.
|
1813
|
+
|
1814
|
+
Format and virtual size need no longer be specified as they are now retrieved directly from the
|
1815
|
+
provided image using `qemu-img info ...`.
|
1816
|
+
|
1817
|
+
Example format:
|
1818
|
+
```json
|
1819
|
+
{
|
1820
|
+
'disks': [
|
1821
|
+
{
|
1822
|
+
'path': 'disk1.img'
|
1823
|
+
},
|
1824
|
+
{
|
1825
|
+
'path': 'disk2.img',
|
1826
|
+
'name': 'secondary_disk'
|
1827
|
+
},
|
1828
|
+
{
|
1829
|
+
'path': 'disk3.img'
|
1830
|
+
}
|
1831
|
+
],
|
1832
|
+
'provider': 'libvirt'
|
1833
|
+
}
|
1834
|
+
```
|
1835
|
+
|
1455
1836
|
## Create Box
|
1456
1837
|
|
1838
|
+
If creating a box from a modified vagrant-libvirt machine, ensure that
|
1839
|
+
you have set the `config.ssh.insert_key = false` in the original Vagrantfile
|
1840
|
+
as otherwise Vagrant will replace the default connection key-pair that is
|
1841
|
+
required on first boot with one specific to the machine and prevent
|
1842
|
+
the default key from working on the exported result.
|
1843
|
+
```ruby
|
1844
|
+
Vagrant.configure("2") do |config|
|
1845
|
+
# this setting is only recommended if planning to export the
|
1846
|
+
# resulting machine
|
1847
|
+
config.ssh.insert_key = false
|
1848
|
+
|
1849
|
+
config.vm.define :test_vm do |test_vm|
|
1850
|
+
test_vm.vm.box = "fedora/32-cloud-base"
|
1851
|
+
end
|
1852
|
+
end
|
1853
|
+
```
|
1854
|
+
|
1457
1855
|
To create a vagrant-libvirt box from a qcow2 image, run `create_box.sh`
|
1458
1856
|
(located in the tools directory):
|
1459
1857
|
|
@@ -1551,17 +1949,49 @@ $ bundle install
|
|
1551
1949
|
Once you have the dependencies, verify the unit tests pass with `rspec`:
|
1552
1950
|
|
1553
1951
|
```shell
|
1554
|
-
$
|
1952
|
+
$ export VAGRANT_HOME=$(mktemp -d)
|
1953
|
+
$ bundle exec rspec --fail-fast --color --format documentation
|
1954
|
+
```
|
1955
|
+
|
1956
|
+
If those pass, you're ready to start developing the plugin.
|
1957
|
+
|
1958
|
+
Setting `VAGRANT_HOME` is to avoid issues with conflicting with other
|
1959
|
+
plugins/gems or data already present under `~/.vagrant.d`.
|
1960
|
+
|
1961
|
+
Additionally if you wish to test against a specific version of vagrant you
|
1962
|
+
can control the version using the following before running the tests:
|
1963
|
+
|
1964
|
+
```shell
|
1965
|
+
$ export VAGRANT_VERSION=v2.2.14
|
1555
1966
|
```
|
1556
1967
|
|
1557
|
-
|
1558
|
-
|
1559
|
-
|
1560
|
-
|
1561
|
-
|
1968
|
+
**Note** rvm is used by the maintainers to help provide an environment to test
|
1969
|
+
against multiple ruby versions that align with the ones used by vagrant for
|
1970
|
+
their embedded ruby depending on the release. You can see what version is used
|
1971
|
+
by looking at the current [unit tests](.github/workflows/unit-tests.yml)
|
1972
|
+
workflow.
|
1973
|
+
|
1974
|
+
You can test the plugin without installing it into your Vagrant environment by
|
1975
|
+
just creating a `Vagrantfile` in the top level of this directory (it is
|
1976
|
+
gitignored) that uses it. You can add the following line to your Vagrantfile
|
1977
|
+
while in development to ensure vagrant checks that the plugin is installed:
|
1562
1978
|
|
1563
1979
|
```ruby
|
1564
|
-
Vagrant.
|
1980
|
+
Vagrant.configure("2") do |config|
|
1981
|
+
config.vagrant.plugins = "vagrant-libvirt"
|
1982
|
+
end
|
1983
|
+
```
|
1984
|
+
Or add the following to the top of the file to ensure that any required plugins
|
1985
|
+
are installed globally:
|
1986
|
+
```ruby
|
1987
|
+
REQUIRED_PLUGINS = %w(vagrant-libvirt)
|
1988
|
+
exit unless REQUIRED_PLUGINS.all? do |plugin|
|
1989
|
+
Vagrant.has_plugin?(plugin) || (
|
1990
|
+
puts "The #{plugin} plugin is required. Please install it with:"
|
1991
|
+
puts "$ vagrant plugin install #{plugin}"
|
1992
|
+
false
|
1993
|
+
)
|
1994
|
+
end
|
1565
1995
|
```
|
1566
1996
|
|
1567
1997
|
Now you can use bundler to execute Vagrant:
|