vagrant-libvirt 0.0.43 → 0.3.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +5 -5
- data/README.md +434 -150
- data/lib/vagrant-libvirt/action.rb +2 -2
- data/lib/vagrant-libvirt/action/create_domain.rb +103 -38
- data/lib/vagrant-libvirt/action/create_domain_volume.rb +19 -14
- data/lib/vagrant-libvirt/action/create_network_interfaces.rb +10 -5
- data/lib/vagrant-libvirt/action/create_networks.rb +7 -2
- data/lib/vagrant-libvirt/action/destroy_domain.rb +1 -1
- data/lib/vagrant-libvirt/action/destroy_networks.rb +5 -0
- data/lib/vagrant-libvirt/action/forward_ports.rb +9 -7
- data/lib/vagrant-libvirt/action/halt_domain.rb +1 -1
- data/lib/vagrant-libvirt/action/handle_box_image.rb +32 -18
- data/lib/vagrant-libvirt/action/handle_storage_pool.rb +9 -4
- data/lib/vagrant-libvirt/action/package_domain.rb +63 -12
- data/lib/vagrant-libvirt/action/prepare_nfs_settings.rb +3 -9
- data/lib/vagrant-libvirt/action/prune_nfs_exports.rb +19 -9
- data/lib/vagrant-libvirt/action/remove_libvirt_image.rb +2 -2
- data/lib/vagrant-libvirt/action/remove_stale_volume.rb +17 -11
- data/lib/vagrant-libvirt/action/set_boot_order.rb +2 -2
- data/lib/vagrant-libvirt/action/set_name_of_domain.rb +6 -9
- data/lib/vagrant-libvirt/action/start_domain.rb +3 -3
- data/lib/vagrant-libvirt/action/wait_till_up.rb +31 -16
- data/lib/vagrant-libvirt/cap/public_address.rb +16 -0
- data/lib/vagrant-libvirt/cap/synced_folder.rb +3 -3
- data/lib/vagrant-libvirt/config.rb +178 -29
- data/lib/vagrant-libvirt/driver.rb +31 -2
- data/lib/vagrant-libvirt/errors.rb +5 -1
- data/lib/vagrant-libvirt/plugin.rb +7 -2
- data/lib/vagrant-libvirt/templates/default_storage_pool.xml.erb +3 -3
- data/lib/vagrant-libvirt/templates/domain.xml.erb +48 -8
- data/lib/vagrant-libvirt/templates/public_interface.xml.erb +5 -1
- data/lib/vagrant-libvirt/util.rb +2 -0
- data/lib/vagrant-libvirt/util/erb_template.rb +6 -7
- data/lib/vagrant-libvirt/util/network_util.rb +33 -13
- data/lib/vagrant-libvirt/util/nfs.rb +17 -0
- data/lib/vagrant-libvirt/util/storage_util.rb +27 -0
- data/lib/vagrant-libvirt/util/ui.rb +23 -0
- data/lib/vagrant-libvirt/version +1 -0
- data/lib/vagrant-libvirt/version.rb +24 -1
- data/locales/en.yml +8 -4
- data/spec/support/environment_helper.rb +1 -1
- data/spec/support/libvirt_context.rb +1 -1
- data/spec/support/sharedcontext.rb +3 -3
- data/spec/unit/action/create_domain_spec.rb +85 -0
- data/spec/unit/action/create_domain_spec/default_storage_pool.xml +17 -0
- data/spec/unit/action/destroy_domain_spec.rb +2 -2
- data/spec/unit/action/set_name_of_domain_spec.rb +3 -3
- data/spec/unit/action/start_domain_spec.rb +49 -0
- data/spec/unit/action/start_domain_spec/default.xml +48 -0
- data/spec/unit/config_spec.rb +173 -0
- data/spec/unit/templates/domain_all_settings.xml +20 -4
- data/spec/unit/templates/domain_custom_cpu_model.xml +48 -0
- data/spec/unit/templates/domain_defaults.xml +2 -0
- data/spec/unit/templates/domain_spec.rb +26 -2
- metadata +34 -32
- data/.coveralls.yml +0 -1
- data/.github/issue_template.md +0 -37
- data/.gitignore +0 -21
- data/.travis.yml +0 -24
- data/Gemfile +0 -26
- data/Rakefile +0 -8
- data/example_box/README.md +0 -29
- data/example_box/Vagrantfile +0 -60
- data/example_box/metadata.json +0 -5
- data/tools/create_box.sh +0 -130
- data/tools/prepare_redhat_for_box.sh +0 -119
- data/vagrant-libvirt.gemspec +0 -54
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
|
-
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
2
|
+
SHA256:
|
3
|
+
metadata.gz: 4200a82105f1c9bf2860841eb3c801b103649c76afae39e303f28542316f0bbd
|
4
|
+
data.tar.gz: fd14f23b17262da08eac29401b779cde545913cb9b6bf4240b044a93a35fed52
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 7c068629389967340010d5d94594111fbbf661e895ede714bc45898bc7d2e21f860a8c8d6e9cdc4b7ae5ee77cdd1b6dd313193cb2d7b634971a251456695959b
|
7
|
+
data.tar.gz: 724c11548cf02a12567bbb87470087539e39ed70aa67dd2d5938a6ed5879667fc03315022dfc1c2c6ca367b2da2552cb408e264c9fd1b2ab090506723f67a688
|
data/README.md
CHANGED
@@ -4,61 +4,69 @@
|
|
4
4
|
[![Build Status](https://travis-ci.org/vagrant-libvirt/vagrant-libvirt.svg)](https://travis-ci.org/vagrant-libvirt/vagrant-libvirt)
|
5
5
|
[![Coverage Status](https://coveralls.io/repos/github/vagrant-libvirt/vagrant-libvirt/badge.svg?branch=master)](https://coveralls.io/github/vagrant-libvirt/vagrant-libvirt?branch=master)
|
6
6
|
|
7
|
-
This is a [Vagrant](http://www.vagrantup.com) plugin that adds
|
7
|
+
This is a [Vagrant](http://www.vagrantup.com) plugin that adds a
|
8
8
|
[Libvirt](http://libvirt.org) provider to Vagrant, allowing Vagrant to
|
9
9
|
control and provision machines via Libvirt toolkit.
|
10
10
|
|
11
11
|
**Note:** Actual version is still a development one. Feedback is welcome and
|
12
12
|
can help a lot :-)
|
13
13
|
|
14
|
-
## QA status
|
15
|
-
|
16
|
-
We periodically test basic functionality for vagrant-libvirt on various distributions.
|
17
|
-
In the table below, build passing means that specific version combination of Vagrant + Vagrant-libvirt was installed correctly and `vagrant up` is working. Click the badge to see the log.
|
18
|
-
|
19
|
-
|Vagrant|Vagrant-libvirt|ubuntu-12.04|ubuntu-14.04|ubuntu-16.04|debian-8|debian-9|centos-6|centos-7|fedora-21|fedora-22|fedora-23|fedora-24|arch|
|
20
|
-
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
21
|
-
|2.0.1|master|[![Build Status](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=ubuntu-12.04/badge/icon)](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=ubuntu-12.04/)|[![Build Status](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=ubuntu-14.04/badge/icon)](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=ubuntu-14.04/)|[![Build Status](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=ubuntu-16.04/badge/icon)](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=ubuntu-16.04/)|[![Build Status](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=debian-8/badge/icon)](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=debian-8/)|[![Build Status](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=debian-9/badge/icon)](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=debian-9/)|[![Build Status](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=centos-6/badge/icon)](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=centos-6/)|[![Build Status](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=centos-7/badge/icon)](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=centos-7/)|[![Build Status](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=fedora-21/badge/icon)](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=fedora-21/)|[![Build Status](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=fedora-22/badge/icon)](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=fedora-22/)|[![Build Status](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=fedora-23/badge/icon)](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=fedora-23/)|[![Build Status](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=fedora-24/badge/icon)](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=fedora-24/)|[![Build Status](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=arch/badge/icon)](https://jenkins.infernix.net/job/vagrant-libvirt-qa/qa_vagrant_libvirt_version=master,qa_vagrant_version=2.0.1,distro=arch/)|
|
22
|
-
|
23
14
|
## Index
|
24
15
|
|
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
|
-
|
16
|
+
<!-- note in vim set "let g:vmt_list_item_char='-'" to generate the correct output -->
|
17
|
+
<!-- vim-markdown-toc GFM -->
|
18
|
+
|
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
|
+
* [Vagrant Project Preparation](#vagrant-project-preparation)
|
25
|
+
* [Add Box](#add-box)
|
26
|
+
* [Create Vagrantfile](#create-vagrantfile)
|
27
|
+
* [Start VM](#start-vm)
|
28
|
+
* [How Project Is Created](#how-project-is-created)
|
29
|
+
* [Libvirt Configuration](#libvirt-configuration)
|
30
|
+
* [Provider Options](#provider-options)
|
31
|
+
* [Domain Specific Options](#domain-specific-options)
|
32
|
+
* [Reload behavior](#reload-behavior)
|
33
|
+
* [Networks](#networks)
|
34
|
+
* [Private Network Options](#private-network-options)
|
35
|
+
* [Public Network Options](#public-network-options)
|
36
|
+
* [Management Network](#management-network)
|
37
|
+
* [Additional Disks](#additional-disks)
|
38
|
+
* [Reload behavior](#reload-behavior-1)
|
39
|
+
* [CDROMs](#cdroms)
|
40
|
+
* [Input](#input)
|
41
|
+
* [PCI device passthrough](#pci-device-passthrough)
|
42
|
+
* [Using USB Devices](#using-usb-devices)
|
43
|
+
* [USB Controller Configuration](#usb-controller-configuration)
|
44
|
+
* [USB Device Passthrough](#usb-device-passthrough)
|
45
|
+
* [USB Redirector Devices](#usb-redirector-devices)
|
46
|
+
* [Filter for USB Redirector Devices](#filter-for-usb-redirector-devices)
|
47
|
+
* [Random number generator passthrough](#random-number-generator-passthrough)
|
48
|
+
* [Watchdog device](#watchdog-device)
|
49
|
+
* [Smartcard device](#smartcard-device)
|
50
|
+
* [Hypervisor Features](#hypervisor-features)
|
51
|
+
* [CPU features](#cpu-features)
|
52
|
+
* [Memory Backing](#memory-backing)
|
53
|
+
* [No box and PXE boot](#no-box-and-pxe-boot)
|
54
|
+
* [SSH Access To VM](#ssh-access-to-vm)
|
55
|
+
* [Forwarded Ports](#forwarded-ports)
|
56
|
+
* [Synced Folders](#synced-folders)
|
57
|
+
* [QEMU Session Support](#qemu-session-support)
|
58
|
+
* [Customized Graphics](#customized-graphics)
|
59
|
+
* [TPM Devices](#tpm-devices)
|
60
|
+
* [Libvirt communication channels](#libvirt-communication-channels)
|
61
|
+
* [Custom command line arguments and environment variables](#custom-command-line-arguments-and-environment-variables)
|
62
|
+
* [Box Format](#box-format)
|
63
|
+
* [Create Box](#create-box)
|
64
|
+
* [Package Box from VM](#package-box-from-vm)
|
65
|
+
* [Troubleshooting VMs](#troubleshooting-vms)
|
66
|
+
* [Development](#development)
|
67
|
+
* [Contributing](#contributing)
|
68
|
+
|
69
|
+
<!-- vim-markdown-toc -->
|
62
70
|
|
63
71
|
## Features
|
64
72
|
|
@@ -85,29 +93,74 @@ In the table below, build passing means that specific version combination of Vag
|
|
85
93
|
* Take a look at [open
|
86
94
|
issues](https://github.com/vagrant-libvirt/vagrant-libvirt/issues?state=open).
|
87
95
|
|
96
|
+
## Using Docker based Installation
|
97
|
+
|
98
|
+
Due to the number of issues encountered around compatibility between the ruby runtime environment
|
99
|
+
that is part of the upstream vagrant installation and the library dependencies of libvirt that
|
100
|
+
this project requires to communicate with libvirt, there is a docker image build and published.
|
101
|
+
|
102
|
+
This should allow users to execute vagrant with vagrant-libvirt without needing to deal with
|
103
|
+
the compatibility issues, though you may need to extend the image for your own needs should
|
104
|
+
you make use of additional plugins.
|
105
|
+
|
106
|
+
To get the image:
|
107
|
+
```bash
|
108
|
+
docker pull vagrantlibvirt/vagrant-libvirt:latest
|
109
|
+
```
|
110
|
+
|
111
|
+
Running the image:
|
112
|
+
```bash
|
113
|
+
docker run -it --rm \
|
114
|
+
-e LIBVIRT_DEFAULT_URI \
|
115
|
+
-v /var/run/libvirt/:/var/run/libvirt/ \
|
116
|
+
-v ~/.vagrant.d:/.vagrant.d \
|
117
|
+
-v $(pwd):$(pwd) \
|
118
|
+
-w $(pwd) \
|
119
|
+
vagrantlibvirt/vagrant-libvirt:latest \
|
120
|
+
vagrant status
|
121
|
+
```
|
122
|
+
|
123
|
+
Note that if you are connecting to a remote system libvirt, you may omit the
|
124
|
+
`-v /var/run/libvirt/:/var/run/libvirt/` mount bind. Some distributions patch the local
|
125
|
+
vagrant environment to ensure vagrant-libvirt uses `qemu:///session`, which means you
|
126
|
+
may need to set the environment variable `LIBVIRT_DEFAULT_URI` to the same value if
|
127
|
+
looking to use this in place of your distribution provided installation.
|
128
|
+
|
88
129
|
## Installation
|
89
130
|
|
90
|
-
First, you should have both
|
91
|
-
on your local system. For instructions, refer to your
|
131
|
+
First, you should have both QEMU and Libvirt installed if you plan to run VMs
|
132
|
+
on your local system. For instructions, refer to your Linux distribution's
|
92
133
|
documentation.
|
93
134
|
|
94
|
-
**NOTE:** Before you start using
|
95
|
-
and
|
96
|
-
|
135
|
+
**NOTE:** Before you start using vagrant-libvirt, please make sure your Libvirt
|
136
|
+
and QEMU installation is working correctly and you are able to create QEMU or
|
137
|
+
KVM type virtual machines with `virsh` or `virt-manager`.
|
97
138
|
|
98
139
|
Next, you must have [Vagrant
|
99
140
|
installed](http://docs.vagrantup.com/v2/installation/index.html).
|
100
|
-
Vagrant-libvirt supports Vagrant
|
101
|
-
|
141
|
+
Vagrant-libvirt supports Vagrant 2.0, 2.1 & 2.2. It should also work with earlier
|
142
|
+
releases from 1.5 onwards but they are not actively tested.
|
143
|
+
|
144
|
+
Check the [.travis.yml](https://github.com/vagrant-libvirt/vagrant-libvirt/blob/master/.travis.yml)
|
145
|
+
for the current list of tested versions.
|
146
|
+
|
147
|
+
*We only test with the upstream version!* If you decide to install your distro's
|
102
148
|
version and you run into problems, as a first step you should switch to upstream.
|
103
149
|
|
104
150
|
Now you need to make sure your have all the build dependencies installed for
|
105
151
|
vagrant-libvirt. This depends on your distro. An overview:
|
106
152
|
|
107
|
-
* Ubuntu
|
153
|
+
* Ubuntu 18.10, Debian 9 and up:
|
154
|
+
```shell
|
155
|
+
apt-get build-dep vagrant ruby-libvirt
|
156
|
+
apt-get install qemu libvirt-daemon-system libvirt-clients ebtables dnsmasq-base
|
157
|
+
apt-get install libxslt-dev libxml2-dev libvirt-dev zlib1g-dev ruby-dev
|
158
|
+
```
|
159
|
+
|
160
|
+
* Ubuntu 18.04, Debian 8 and older:
|
108
161
|
```shell
|
109
162
|
apt-get build-dep vagrant ruby-libvirt
|
110
|
-
apt-get install qemu libvirt-bin ebtables dnsmasq
|
163
|
+
apt-get install qemu libvirt-bin ebtables dnsmasq-base
|
111
164
|
apt-get install libxslt-dev libxml2-dev libvirt-dev zlib1g-dev ruby-dev
|
112
165
|
```
|
113
166
|
|
@@ -120,10 +173,15 @@ yum install qemu libvirt libvirt-devel ruby-devel gcc qemu-kvm
|
|
120
173
|
|
121
174
|
* Fedora 22 and up:
|
122
175
|
```shell
|
123
|
-
dnf -y
|
176
|
+
dnf install -y gcc libvirt libvirt-devel libxml2-devel make ruby-devel
|
124
177
|
```
|
125
178
|
|
126
|
-
*
|
179
|
+
* OpenSUSE leap 15.1:
|
180
|
+
```shell
|
181
|
+
zypper install qemu libvirt libvirt-devel ruby-devel gcc qemu-kvm
|
182
|
+
```
|
183
|
+
|
184
|
+
* Arch Linux: please read the related [ArchWiki](https://wiki.archlinux.org/index.php/Vagrant#vagrant-libvirt) page.
|
127
185
|
```shell
|
128
186
|
pacman -S vagrant
|
129
187
|
```
|
@@ -131,8 +189,16 @@ pacman -S vagrant
|
|
131
189
|
Now you're ready to install vagrant-libvirt using standard [Vagrant
|
132
190
|
plugin](http://docs.vagrantup.com/v2/plugins/usage.html) installation methods.
|
133
191
|
|
192
|
+
For some distributions you will need to specify `CONFIGURE_ARGS` variable before
|
193
|
+
running `vagrant plugin install`:
|
194
|
+
|
195
|
+
* Fedora 32 + upstream Vagrant:
|
196
|
+
```shell
|
197
|
+
export CONFIGURE_ARGS="with-libvirt-include=/usr/include/libvirt with-libvirt-lib=/usr/lib64"
|
198
|
+
```
|
199
|
+
|
134
200
|
```shell
|
135
|
-
|
201
|
+
vagrant plugin install vagrant-libvirt
|
136
202
|
```
|
137
203
|
|
138
204
|
### Possible problems with plugin installation on Linux
|
@@ -151,7 +217,7 @@ $ sudo dnf install libxslt-devel libxml2-devel libvirt-devel \
|
|
151
217
|
libguestfs-tools-c ruby-devel gcc
|
152
218
|
```
|
153
219
|
|
154
|
-
On Arch
|
220
|
+
On Arch Linux it is recommended to follow [steps from ArchWiki](https://wiki.archlinux.org/index.php/Vagrant#vagrant-libvirt).
|
155
221
|
|
156
222
|
If have problem with installation - check your linker. It should be `ld.gold`:
|
157
223
|
|
@@ -165,6 +231,43 @@ If you have issues building ruby-libvirt, try the following:
|
|
165
231
|
```shell
|
166
232
|
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
|
167
233
|
```
|
234
|
+
### Additional Notes for Fedora and Similar Linux Distributions
|
235
|
+
|
236
|
+
If you encounter the following load error when using the vagrant-libvirt plugin (note the required by libssh):
|
237
|
+
|
238
|
+
```shell
|
239
|
+
/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)
|
240
|
+
```
|
241
|
+
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.
|
242
|
+
|
243
|
+
```shell
|
244
|
+
dnf download --source libssh
|
245
|
+
rpm2cpio libssh-0.9.0-5.fc30.src.rpm | cpio -imdV
|
246
|
+
tar xf libssh-0.9.0.tar.xz
|
247
|
+
mkdir build
|
248
|
+
cd build
|
249
|
+
cmake ../libssh-0.9.0 -DOPENSSL_ROOT_DIR=/opt/vagrant/embedded/
|
250
|
+
make
|
251
|
+
sudo cp lib/libssh* /opt/vagrant/embedded/lib64
|
252
|
+
```
|
253
|
+
|
254
|
+
If you encounter the following load error when using the vagrant-libvirt plugin (note the required by libk5crypto):
|
255
|
+
|
256
|
+
```shell
|
257
|
+
/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)
|
258
|
+
```
|
259
|
+
|
260
|
+
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):
|
261
|
+
|
262
|
+
```shell
|
263
|
+
dnf download --source krb5-libs
|
264
|
+
rpm2cpio krb5-1.18-1.fc32.src.rpm | cpio -imdV
|
265
|
+
tar xf krb5-1.18.tar.gz
|
266
|
+
cd krb5-1.18/src
|
267
|
+
./configure
|
268
|
+
make
|
269
|
+
sudo cp -P lib/crypto/libk5crypto.* /opt/vagrant/embedded/lib64/
|
270
|
+
```
|
168
271
|
|
169
272
|
## Vagrant Project Preparation
|
170
273
|
|
@@ -173,12 +276,12 @@ CONFIGURE_ARGS='with-ldflags=-L/opt/vagrant/embedded/lib with-libvirt-include=/u
|
|
173
276
|
After installing the plugin (instructions above), the quickest way to get
|
174
277
|
started is to add Libvirt box and specify all the details manually within a
|
175
278
|
`config.vm.provider` block. So first, add Libvirt box using any name you want.
|
176
|
-
You can find more
|
177
|
-
[
|
279
|
+
You can find more Libvirt-ready boxes at
|
280
|
+
[Vagrant Cloud](https://app.vagrantup.com/boxes/search?provider=libvirt). For
|
178
281
|
example:
|
179
282
|
|
180
283
|
```shell
|
181
|
-
vagrant init fedora/
|
284
|
+
vagrant init fedora/32-cloud-base
|
182
285
|
```
|
183
286
|
|
184
287
|
### Create Vagrantfile
|
@@ -189,7 +292,7 @@ information where necessary. For example:
|
|
189
292
|
```ruby
|
190
293
|
Vagrant.configure("2") do |config|
|
191
294
|
config.vm.define :test_vm do |test_vm|
|
192
|
-
test_vm.vm.box = "fedora/
|
295
|
+
test_vm.vm.box = "fedora/32-cloud-base"
|
193
296
|
end
|
194
297
|
end
|
195
298
|
```
|
@@ -214,7 +317,7 @@ export VAGRANT_DEFAULT_PROVIDER=libvirt
|
|
214
317
|
|
215
318
|
Vagrant goes through steps below when creating new project:
|
216
319
|
|
217
|
-
1. Connect to Libvirt
|
320
|
+
1. Connect to Libvirt locally or remotely via SSH.
|
218
321
|
2. Check if box image is available in Libvirt storage pool. If not, upload it
|
219
322
|
to remote Libvirt storage pool as new volume.
|
220
323
|
3. Create COW diff image of base box image for new Libvirt domain.
|
@@ -231,29 +334,32 @@ Vagrant goes through steps below when creating new project:
|
|
231
334
|
Although it should work without any configuration for most people, this
|
232
335
|
provider exposes quite a few provider-specific configuration options. The
|
233
336
|
following options allow you to configure how vagrant-libvirt connects to
|
234
|
-
|
337
|
+
Libvirt, and are used to generate the [Libvirt connection
|
235
338
|
URI](http://libvirt.org/uri.html):
|
236
339
|
|
237
|
-
* `driver` - A hypervisor name to access. For now only
|
340
|
+
* `driver` - A hypervisor name to access. For now only KVM and QEMU are
|
238
341
|
supported
|
239
|
-
* `host` - The name of the server, where
|
342
|
+
* `host` - The name of the server, where Libvirtd is running
|
240
343
|
* `connect_via_ssh` - If use ssh tunnel to connect to Libvirt. Absolutely
|
241
|
-
needed to access
|
344
|
+
needed to access Libvirt on remote host. It will not be able to get the IP
|
242
345
|
address of a started VM otherwise.
|
243
346
|
* `username` - Username and password to access Libvirt
|
244
347
|
* `password` - Password to access Libvirt
|
245
348
|
* `id_ssh_key_file` - If not nil, uses this ssh private key to access Libvirt.
|
246
349
|
Default is `$HOME/.ssh/id_rsa`. Prepends `$HOME/.ssh/` if no directory
|
247
|
-
* `socket` - Path to the
|
350
|
+
* `socket` - Path to the Libvirt unix socket (e.g.
|
248
351
|
`/var/run/libvirt/libvirt-sock`)
|
249
|
-
* `uri` - For advanced usage. Directly specifies what
|
352
|
+
* `uri` - For advanced usage. Directly specifies what Libvirt connection URI
|
250
353
|
vagrant-libvirt should use. Overrides all other connection configuration
|
251
354
|
options
|
252
355
|
|
253
356
|
Connection-independent options:
|
254
357
|
|
255
358
|
* `storage_pool_name` - Libvirt storage pool name, where box image and instance
|
256
|
-
snapshots will be stored.
|
359
|
+
snapshots (if `snapshot_pool_name` is not set) will be stored.
|
360
|
+
* `snapshot_pool_name` - Libvirt storage pool name. If set, the created
|
361
|
+
snapshot of the instance will be stored at this location instead of
|
362
|
+
`storage_pool_name`.
|
257
363
|
|
258
364
|
For example:
|
259
365
|
|
@@ -267,8 +373,10 @@ end
|
|
267
373
|
|
268
374
|
### Domain Specific Options
|
269
375
|
|
376
|
+
* `title` - A short description of the domain.
|
377
|
+
* `description` - A human readable description of the virtual machine.
|
270
378
|
* `disk_bus` - The type of disk device to emulate. Defaults to virtio if not
|
271
|
-
set. Possible values are documented in
|
379
|
+
set. Possible values are documented in Libvirt's [description for
|
272
380
|
_target_](http://libvirt.org/formatdomain.html#elementsDisks). NOTE: this
|
273
381
|
option applies only to disks associated with a box image. To set the bus type
|
274
382
|
on additional disks, see the [Additional Disks](#additional-disks) section.
|
@@ -279,22 +387,26 @@ end
|
|
279
387
|
* `nic_model_type` - parameter specifies the model of the network adapter when
|
280
388
|
you create a domain value by default virtio KVM believe possible values, see
|
281
389
|
the [documentation for
|
282
|
-
|
390
|
+
Libvirt](https://libvirt.org/formatdomain.html#elementsNICSModel).
|
391
|
+
* `shares` - Proportional weighted share for the domain relative to others. For more details see [documentation](https://libvirt.org/formatdomain.html#elementsCPUTuning).
|
283
392
|
* `memory` - Amount of memory in MBytes. Defaults to 512 if not set.
|
284
393
|
* `cpus` - Number of virtual cpus. Defaults to 1 if not set.
|
394
|
+
* `cpuset` - Physical cpus to which the vcpus can be pinned. For more details see [documentation](https://libvirt.org/formatdomain.html#elementsCPUAllocation).
|
285
395
|
* `cputopology` - Number of CPU sockets, cores and threads running per core. All fields of `:sockets`, `:cores` and `:threads` are mandatory, `cpus` domain option must be present and must be equal to total count of **sockets * cores * threads**. For more details see [documentation](https://libvirt.org/formatdomain.html#elementsCPU).
|
396
|
+
* `nodeset` - Physical NUMA nodes where virtual memory can be pinned. For more details see [documentation](https://libvirt.org/formatdomain.html#elementsNUMATuning).
|
286
397
|
|
287
398
|
```ruby
|
288
399
|
Vagrant.configure("2") do |config|
|
289
400
|
config.vm.provider :libvirt do |libvirt|
|
290
401
|
libvirt.cpus = 4
|
402
|
+
libvirt.cpuset = '1-4,^3,6'
|
291
403
|
libvirt.cputopology :sockets => '2', :cores => '2', :threads => '1'
|
292
404
|
end
|
293
405
|
end
|
294
406
|
```
|
295
407
|
|
296
408
|
* `nested` - [Enable nested
|
297
|
-
virtualization](https://
|
409
|
+
virtualization](https://docs.fedoraproject.org/en-US/quick-docs/using-nested-virtualization-in-kvm/).
|
298
410
|
Default is false.
|
299
411
|
* `cpu_mode` - [CPU emulation
|
300
412
|
mode](https://libvirt.org/formatdomain.html#elementsCPU). Defaults to
|
@@ -303,7 +415,7 @@ end
|
|
303
415
|
* `cpu_model` - CPU Model. Defaults to 'qemu64' if not set and `cpu_mode` is
|
304
416
|
`custom` and to '' otherwise. This can really only be used when setting
|
305
417
|
`cpu_mode` to `custom`.
|
306
|
-
* `cpu_fallback` - Whether to allow
|
418
|
+
* `cpu_fallback` - Whether to allow Libvirt to fall back to a CPU model close
|
307
419
|
to the specified model if features in the guest CPU are not supported on the
|
308
420
|
host. Defaults to 'allow' if not set. Allowed values: `allow`, `forbid`.
|
309
421
|
* `numa_nodes` - Specify an array of NUMA nodes for the guest. The syntax is similar to what would be set in the domain XML. `memory` must be in MB. Symmetrical and asymmetrical topologies are supported but make sure your total count of defined CPUs adds up to `v.cpus`.
|
@@ -319,7 +431,7 @@ end
|
|
319
431
|
* `loader` - Sets path to custom UEFI loader.
|
320
432
|
* `volume_cache` - Controls the cache mechanism. Possible values are "default",
|
321
433
|
"none", "writethrough", "writeback", "directsync" and "unsafe". [See
|
322
|
-
driver->cache in
|
434
|
+
driver->cache in Libvirt
|
323
435
|
documentation](http://libvirt.org/formatdomain.html#elementsDisks).
|
324
436
|
* `kernel` - To launch the guest with a kernel residing on host filesystems.
|
325
437
|
Equivalent to qemu `-kernel`.
|
@@ -327,6 +439,9 @@ end
|
|
327
439
|
to qemu `-initrd`.
|
328
440
|
* `random_hostname` - To create a domain name with extra information on the end
|
329
441
|
to prevent hostname conflicts.
|
442
|
+
* `default_prefix` - The default Libvirt guest name becomes a concatenation of the
|
443
|
+
`<current_directory>_<guest_name>`. The current working directory is the default prefix
|
444
|
+
to the guest name. The `default_prefix` options allow you to set the guest name prefix.
|
330
445
|
* `cmd_line` - Arguments passed on to the guest kernel initramfs or initrd to
|
331
446
|
use. Equivalent to qemu `-append`, only possible to use in combination with `initrd` and `kernel`.
|
332
447
|
* `graphics_type` - Sets the protocol used to expose the guest display.
|
@@ -337,8 +452,8 @@ end
|
|
337
452
|
* `graphics_ip` - Sets the IP for the display protocol to bind to. Defaults to
|
338
453
|
"127.0.0.1".
|
339
454
|
* `graphics_passwd` - Sets the password for the display protocol. Working for
|
340
|
-
vnc and
|
341
|
-
* `graphics_autoport` - Sets autoport for graphics,
|
455
|
+
vnc and Spice. by default working without passsword.
|
456
|
+
* `graphics_autoport` - Sets autoport for graphics, Libvirt in this case
|
342
457
|
ignores graphics_port value, Defaults to 'yes'. Possible value are "yes" and
|
343
458
|
"no"
|
344
459
|
* `keymap` - Set keymap for vm. default: en-us
|
@@ -355,8 +470,8 @@ end
|
|
355
470
|
Defaults to "ich6".
|
356
471
|
* `machine_type` - Sets machine type. Equivalent to qemu `-machine`. Use
|
357
472
|
`qemu-system-x86_64 -machine help` to get a list of supported machines.
|
358
|
-
* `machine_arch` - Sets machine architecture. This helps
|
359
|
-
the correct emulator type. Possible values depend on your version of
|
473
|
+
* `machine_arch` - Sets machine architecture. This helps Libvirt to determine
|
474
|
+
the correct emulator type. Possible values depend on your version of QEMU.
|
360
475
|
For possible values, see which emulator executable `qemu-system-*` your
|
361
476
|
system provides. Common examples are `aarch64`, `alpha`, `arm`, `cris`,
|
362
477
|
`i386`, `lm32`, `m68k`, `microblaze`, `microblazeel`, `mips`, `mips64`,
|
@@ -380,7 +495,7 @@ end
|
|
380
495
|
* `nic_adapter_count` - Defaults to '8'. Only use case for increasing this
|
381
496
|
count is for VMs that virtualize switches such as Cumulus Linux. Max value
|
382
497
|
for Cumulus Linux VMs is 33.
|
383
|
-
* `uuid` - Force a domain UUID. Defaults to autogenerated value by
|
498
|
+
* `uuid` - Force a domain UUID. Defaults to autogenerated value by Libvirt if
|
384
499
|
not set.
|
385
500
|
* `suspend_mode` - What is done on vagrant suspend. Possible values: 'pause',
|
386
501
|
'managedsave'. Pause mode executes a la `virsh suspend`, which just pauses
|
@@ -394,10 +509,10 @@ end
|
|
394
509
|
specified here.
|
395
510
|
* `autostart` - Automatically start the domain when the host boots. Defaults to
|
396
511
|
'false'.
|
397
|
-
* `channel` - [
|
512
|
+
* `channel` - [Libvirt
|
398
513
|
channels](https://libvirt.org/formatdomain.html#elementCharChannel).
|
399
514
|
Configure a private communication channel between the host and guest, e.g.
|
400
|
-
for use by the [
|
515
|
+
for use by the [QEMU guest
|
401
516
|
agent](http://wiki.libvirt.org/page/Qemu_guest_agent) and the Spice/QXL
|
402
517
|
graphics type.
|
403
518
|
* `mgmt_attach` - Decide if VM has interface in mgmt network. If set to 'false'
|
@@ -478,11 +593,11 @@ https://libvirt.org/formatdomain.html#elementsNICSTCP
|
|
478
593
|
|
479
594
|
http://libvirt.org/formatdomain.html#elementsNICSMulticast
|
480
595
|
|
481
|
-
http://libvirt.org/formatdomain.html#elementsNICSUDP _(in
|
596
|
+
http://libvirt.org/formatdomain.html#elementsNICSUDP _(in Libvirt v1.2.20 and higher)_
|
482
597
|
|
483
598
|
Public Network interfaces are currently implemented using the macvtap driver.
|
484
599
|
The macvtap driver is only available with the Linux Kernel version >= 2.6.24.
|
485
|
-
See the following
|
600
|
+
See the following Libvirt documentation for the details of the macvtap usage.
|
486
601
|
|
487
602
|
http://www.libvirt.org/formatdomain.html#elementsNICSDirect
|
488
603
|
|
@@ -551,7 +666,7 @@ In example below, one network interface is configured for VM `test_vm1`. After
|
|
551
666
|
you run `vagrant up`, VM will be accessible on IP address `10.20.30.40`. So if
|
552
667
|
you install a web server via provisioner, you will be able to access your
|
553
668
|
testing server on `http://10.20.30.40` URL. But beware that this address is
|
554
|
-
private to
|
669
|
+
private to Libvirt host only. It's not visible outside of the hypervisor box.
|
555
670
|
|
556
671
|
If network `10.20.30.0/24` doesn't exist, provider will create it. By default
|
557
672
|
created networks are NATed to outside world, so your VM will be able to connect
|
@@ -568,11 +683,11 @@ reachable by anyone with access to the public network.
|
|
568
683
|
|
569
684
|
*Note: These options are not applicable to public network interfaces.*
|
570
685
|
|
571
|
-
There is a way to pass specific options for
|
686
|
+
There is a way to pass specific options for Libvirt provider when using
|
572
687
|
`config.vm.network` to configure new network interface. Each parameter name
|
573
688
|
starts with `libvirt__` string. Here is a list of those options:
|
574
689
|
|
575
|
-
* `:libvirt__network_name` - Name of
|
690
|
+
* `:libvirt__network_name` - Name of Libvirt network to connect to. By default,
|
576
691
|
network 'default' is used.
|
577
692
|
* `:libvirt__netmask` - Used only together with `:ip` option. Default is
|
578
693
|
'255.255.255.0'.
|
@@ -593,8 +708,8 @@ starts with `libvirt__` string. Here is a list of those options:
|
|
593
708
|
only when dhcp is enabled.By default is the same host that runs the DHCP
|
594
709
|
server.
|
595
710
|
* `:libvirt__adapter` - Number specifiyng sequence number of interface.
|
596
|
-
* `:libvirt__forward_mode` - Specify one of `veryisolated`, `none`, `nat`
|
597
|
-
`route` options. This option is used only when creating new network. Mode
|
711
|
+
* `:libvirt__forward_mode` - Specify one of `veryisolated`, `none`, `open`, `nat`
|
712
|
+
or `route` options. This option is used only when creating new network. Mode
|
598
713
|
`none` will create isolated network without NATing or routing outside. You
|
599
714
|
will want to use NATed forwarding typically to reach networks outside of
|
600
715
|
hypervisor. Routed forwarding is typically useful to reach other networks
|
@@ -611,7 +726,7 @@ starts with `libvirt__` string. Here is a list of those options:
|
|
611
726
|
between Guests. Useful for Switch VMs like Cumulus Linux. No virtual switch
|
612
727
|
setting like `libvirt__network_name` applies with tunnel interfaces and will
|
613
728
|
be ignored if configured.
|
614
|
-
* `:libvirt__tunnel_ip` - Sets the source IP of the
|
729
|
+
* `:libvirt__tunnel_ip` - Sets the source IP of the Libvirt tunnel interface.
|
615
730
|
By default this is `127.0.0.1` for TCP and UDP tunnels and `239.255.1.1` for
|
616
731
|
Multicast tunnels. It populates the address field in the `<source
|
617
732
|
address="XXX">` of the interface xml configuration.
|
@@ -621,11 +736,11 @@ starts with `libvirt__` string. Here is a list of those options:
|
|
621
736
|
* `:libvirt__tunnel_local_port` - Sets the local port used by the udp tunnel
|
622
737
|
interface type. It populates the port field in the `<local port=XXX">`
|
623
738
|
section of the interface xml configuration. _(This feature only works in
|
624
|
-
|
739
|
+
Libvirt 1.2.20 and higher)_
|
625
740
|
* `:libvirt__tunnel_local_ip` - Sets the local IP used by the udp tunnel
|
626
741
|
interface type. It populates the ip entry of the `<local address=XXX">`
|
627
742
|
section of the interface xml configuration. _(This feature only works in
|
628
|
-
|
743
|
+
Libvirt 1.2.20 and higher)_
|
629
744
|
* `:libvirt__guest_ipv6` - Enable or disable guest-to-guest IPv6 communication.
|
630
745
|
See [here](https://libvirt.org/formatnetwork.html#examplesPrivate6), and
|
631
746
|
[here](http://libvirt.org/git/?p=libvirt.git;a=commitdiff;h=705e67d40b09a905cd6a4b8b418d5cb94eaa95a8)
|
@@ -637,18 +752,18 @@ starts with `libvirt__` string. Here is a list of those options:
|
|
637
752
|
failures](https://github.com/vagrant-libvirt/vagrant-libvirt/pull/498)
|
638
753
|
* `:mac` - MAC address for the interface. *Note: specify this in lowercase
|
639
754
|
since Vagrant network scripts assume it will be!*
|
640
|
-
* `:libvirt__mtu` - MTU size for the
|
641
|
-
created network will use the
|
755
|
+
* `:libvirt__mtu` - MTU size for the Libvirt network, if not defined, the
|
756
|
+
created network will use the Libvirt default (1500). VMs still need to set the
|
642
757
|
MTU accordingly.
|
643
758
|
* `:model_type` - parameter specifies the model of the network adapter when you
|
644
759
|
create a domain value by default virtio KVM believe possible values, see the
|
645
|
-
documentation for
|
760
|
+
documentation for Libvirt
|
646
761
|
* `:libvirt__driver_name` - Define which network driver to use. [More
|
647
762
|
info](https://libvirt.org/formatdomain.html#elementsDriverBackendOptions)
|
648
763
|
* `:libvirt__driver_queues` - Define a number of queues to be used for network
|
649
764
|
interface. Set equal to numer of vCPUs for best performance. [More
|
650
765
|
info](http://www.linux-kvm.org/page/Multiqueue)
|
651
|
-
* `:autostart` - Automatic startup of network by the
|
766
|
+
* `:autostart` - Automatic startup of network by the Libvirt daemon.
|
652
767
|
If not specified the default is 'false'.
|
653
768
|
* `:bus` - The bus of the PCI device. Both :bus and :slot have to be defined.
|
654
769
|
* `:slot` - The slot of the PCI device. Both :bus and :slot have to be defined.
|
@@ -669,10 +784,11 @@ virtual network.
|
|
669
784
|
Default mode is 'bridge'.
|
670
785
|
* `:type` - is type of interface.(`<interface type="#{@type}">`)
|
671
786
|
* `:mac` - MAC address for the interface.
|
672
|
-
* `:network_name` - Name of
|
673
|
-
* `:portgroup` - Name of
|
787
|
+
* `:network_name` - Name of Libvirt network to connect to.
|
788
|
+
* `:portgroup` - Name of Libvirt portgroup to connect to.
|
674
789
|
* `:ovs` - Support to connect to an Open vSwitch bridge device. Default is
|
675
790
|
'false'.
|
791
|
+
* :ovs_interfaceid - Add Open vSwitch 'interfaceid' parameter.
|
676
792
|
* `:trust_guest_rx_filters` - Support trustGuestRxFilters attribute. Details
|
677
793
|
are listed [here](http://www.libvirt.org/formatdomain.html#elementsNICSDirect).
|
678
794
|
Default is 'false'.
|
@@ -681,18 +797,18 @@ virtual network.
|
|
681
797
|
|
682
798
|
vagrant-libvirt uses a private network to perform some management operations on
|
683
799
|
VMs. All VMs will have an interface connected to this network and an IP address
|
684
|
-
dynamically assigned by
|
800
|
+
dynamically assigned by Libvirt unless you set `:mgmt_attach` to 'false'.
|
685
801
|
This is in addition to any networks you configure. The name and address
|
686
802
|
used by this network are configurable at the provider level.
|
687
803
|
|
688
|
-
* `management_network_name` - Name of
|
804
|
+
* `management_network_name` - Name of Libvirt network to which all VMs will be
|
689
805
|
connected. If not specified the default is 'vagrant-libvirt'.
|
690
806
|
* `management_network_address` - Address of network to which all VMs will be
|
691
807
|
connected. Must include the address and subnet mask. If not specified the
|
692
808
|
default is '192.168.121.0/24'.
|
693
|
-
* `management_network_mode` - Network mode for the
|
694
|
-
Specify one of veryisolated, none, nat or route options. Further
|
695
|
-
under [Private Networks](#private-network-options)
|
809
|
+
* `management_network_mode` - Network mode for the Libvirt management network.
|
810
|
+
Specify one of veryisolated, none, open, nat or route options. Further
|
811
|
+
documented under [Private Networks](#private-network-options)
|
696
812
|
* `management_network_guest_ipv6` - Enable or disable guest-to-guest IPv6
|
697
813
|
communication. See
|
698
814
|
[here](https://libvirt.org/formatnetwork.html#examplesPrivate6), and
|
@@ -700,9 +816,10 @@ used by this network are configurable at the provider level.
|
|
700
816
|
for for more information.
|
701
817
|
* `management_network_autostart` - Automatic startup of mgmt network, if not
|
702
818
|
specified the default is 'false'.
|
703
|
-
*
|
704
|
-
*
|
819
|
+
* `management_network_pci_bus` - The bus of the PCI device.
|
820
|
+
* `management_network_pci_slot` - The slot of the PCI device.
|
705
821
|
* `management_network_mac` - MAC address of management network interface.
|
822
|
+
* `management_network_domain` - Domain name assigned to the management network.
|
706
823
|
|
707
824
|
You may wonder how vagrant-libvirt knows the IP address a VM received. Libvirt
|
708
825
|
doesn't provide a standard way to find out the IP address of a running domain.
|
@@ -734,6 +851,7 @@ It has a number of options:
|
|
734
851
|
Disks with this option set to true need to be removed manually.
|
735
852
|
* `shareable` - Set to true if you want to simulate shared SAN storage.
|
736
853
|
* `serial` - Serial number of the disk device.
|
854
|
+
* `wwn` - WWN number of the disk device.
|
737
855
|
|
738
856
|
The following example creates two additional disks.
|
739
857
|
|
@@ -810,29 +928,30 @@ end
|
|
810
928
|
|
811
929
|
You can specify multiple PCI devices to passthrough to the VM via
|
812
930
|
`libvirt.pci`. Available options are listed below. Note that all options are
|
813
|
-
required
|
931
|
+
required, except domain, which defaults to `0x0000`:
|
814
932
|
|
933
|
+
* `domain` - The domain of the PCI device
|
815
934
|
* `bus` - The bus of the PCI device
|
816
935
|
* `slot` - The slot of the PCI device
|
817
936
|
* `function` - The function of the PCI device
|
818
937
|
|
819
938
|
You can extract that information from output of `lspci` command. First
|
820
|
-
characters of each line are in format `[<bus>]:[<slot>].[<func>]`. For example:
|
939
|
+
characters of each line are in format `[<domain>]:[<bus>]:[<slot>].[<func>]`. For example:
|
821
940
|
|
822
941
|
```shell
|
823
942
|
$ lspci| grep NVIDIA
|
824
|
-
03:00.0 VGA compatible controller: NVIDIA Corporation GK110B [GeForce GTX TITAN Black] (rev a1)
|
943
|
+
0000:03:00.0 VGA compatible controller: NVIDIA Corporation GK110B [GeForce GTX TITAN Black] (rev a1)
|
825
944
|
```
|
826
945
|
|
827
|
-
In that case `bus` is `0x03`, `slot` is `0x00` and `function` is `0x0`.
|
946
|
+
In that case `domain` is `0x0000`, `bus` is `0x03`, `slot` is `0x00` and `function` is `0x0`.
|
828
947
|
|
829
948
|
```ruby
|
830
949
|
Vagrant.configure("2") do |config|
|
831
950
|
config.vm.provider :libvirt do |libvirt|
|
832
|
-
libvirt.pci :bus => '0x06', :slot => '0x12', :function => '0x5'
|
951
|
+
libvirt.pci :domain => '0x0000', :bus => '0x06', :slot => '0x12', :function => '0x5'
|
833
952
|
|
834
953
|
# Add another one if it is neccessary
|
835
|
-
libvirt.pci :bus => '0x03', :slot => '0x00', :function => '0x0'
|
954
|
+
libvirt.pci :domain => '0x0000', :bus => '0x03', :slot => '0x00', :function => '0x0'
|
836
955
|
end
|
837
956
|
end
|
838
957
|
```
|
@@ -841,7 +960,64 @@ Note! Above options affect configuration only at domain creation. It won't chang
|
|
841
960
|
|
842
961
|
Don't forget to [set](#domain-specific-options) `kvm_hidden` option to `true` especially if you are passthroughing NVIDIA GPUs. Otherwise GPU is visible from VM but cannot be operated.
|
843
962
|
|
844
|
-
|
963
|
+
|
964
|
+
## Using USB Devices
|
965
|
+
|
966
|
+
There are several ways to pass a USB device through to a running instance:
|
967
|
+
* Use `libvirt.usb` to [attach a USB device at boot](#usb-device-passthrough), with the device ID specified in the Vagrantfile
|
968
|
+
* Use a client (such as `virt-viewer` or `virt-manager`) to attach the device at runtime [via USB redirectors](#usb-redirector-devices)
|
969
|
+
* Use `virsh attach-device` once the VM is running (however, this is outside the scope of this readme)
|
970
|
+
|
971
|
+
In all cases, if you wish to use a high-speed USB device,
|
972
|
+
you will need to use `libvirt.usb_controller` to specify a USB2 or USB3 controller,
|
973
|
+
as the default configuration only exposes a USB1.1 controller.
|
974
|
+
|
975
|
+
### USB Controller Configuration
|
976
|
+
|
977
|
+
The USB controller can be configured using `libvirt.usb_controller`, with the following options:
|
978
|
+
|
979
|
+
* `model` - The USB controller device model to emulate. (mandatory)
|
980
|
+
* `ports` - The number of devices that can be connected to the controller.
|
981
|
+
|
982
|
+
```ruby
|
983
|
+
Vagrant.configure("2") do |config|
|
984
|
+
config.vm.provider :libvirt do |libvirt|
|
985
|
+
# Set up a USB3 controller
|
986
|
+
libvirt.usb_controller :model => "nec-xhci"
|
987
|
+
end
|
988
|
+
end
|
989
|
+
```
|
990
|
+
|
991
|
+
See the [libvirt documentation](https://libvirt.org/formatdomain.html#elementsControllers) for a list of valid models.
|
992
|
+
|
993
|
+
|
994
|
+
### USB Device Passthrough
|
995
|
+
|
996
|
+
You can specify multiple USB devices to passthrough to the VM via
|
997
|
+
`libvirt.usb`. The device can be specified by the following options:
|
998
|
+
|
999
|
+
* `bus` - The USB bus ID, e.g. "1"
|
1000
|
+
* `device` - The USB device ID, e.g. "2"
|
1001
|
+
* `vendor` - The USB devices vendor ID (VID), e.g. "0x1234"
|
1002
|
+
* `product` - The USB devices product ID (PID), e.g. "0xabcd"
|
1003
|
+
|
1004
|
+
At least one of these has to be specified, and `bus` and `device` may only be
|
1005
|
+
used together.
|
1006
|
+
|
1007
|
+
The example values above match the device from the following output of `lsusb`:
|
1008
|
+
|
1009
|
+
```
|
1010
|
+
Bus 001 Device 002: ID 1234:abcd Example device
|
1011
|
+
```
|
1012
|
+
|
1013
|
+
Additionally, the following options can be used:
|
1014
|
+
|
1015
|
+
* `startupPolicy` - Is passed through to Libvirt and controls if the device has
|
1016
|
+
to exist. Libvirt currently allows the following values: "mandatory",
|
1017
|
+
"requisite", "optional".
|
1018
|
+
|
1019
|
+
|
1020
|
+
### USB Redirector Devices
|
845
1021
|
You can specify multiple redirect devices via `libvirt.redirdev`. There are two types, `tcp` and `spicevmc` supported, for forwarding USB-devices to the guest. Available options are listed below.
|
846
1022
|
|
847
1023
|
* `type` - The type of the USB redirector device. (`tcp` or `spicevmc`)
|
@@ -861,7 +1037,10 @@ Vagrant.configure("2") do |config|
|
|
861
1037
|
end
|
862
1038
|
```
|
863
1039
|
|
864
|
-
|
1040
|
+
Note that in order to enable USB redirection with Spice clients,
|
1041
|
+
you may need to also set `libvirt.graphics_type = "spice"`
|
1042
|
+
|
1043
|
+
#### Filter for USB Redirector Devices
|
865
1044
|
You can define filter for redirected devices. These filters can be positiv or negative, by setting the mandatory option `allow=yes` or `allow=no`. All available options are listed below. Note the option `allow` is mandatory.
|
866
1045
|
|
867
1046
|
* `class` - The device class of the USB device. A list of device classes is available on [Wikipedia](https://en.wikipedia.org/wiki/USB#Device_classes).
|
@@ -928,7 +1107,7 @@ The optional action attribute describes what `action` to take when the watchdog
|
|
928
1107
|
```ruby
|
929
1108
|
Vagrant.configure("2") do |config|
|
930
1109
|
config.vm.provider :libvirt do |libvirt|
|
931
|
-
# Add
|
1110
|
+
# Add Libvirt watchdog device model i6300esb
|
932
1111
|
libvirt.watchdog :model => 'i6300esb', :action => 'reset'
|
933
1112
|
end
|
934
1113
|
end
|
@@ -954,7 +1133,7 @@ Vagrant.configure("2") do |config|
|
|
954
1133
|
end
|
955
1134
|
end
|
956
1135
|
```
|
957
|
-
## Features
|
1136
|
+
## Hypervisor Features
|
958
1137
|
|
959
1138
|
Hypervisor features can be specified via `libvirt.features` as a list. The default
|
960
1139
|
options that are enabled are `acpi`, `apic` and `pae`. If you define `libvirt.features`
|
@@ -982,15 +1161,35 @@ Vagrant.configure("2") do |config|
|
|
982
1161
|
end
|
983
1162
|
```
|
984
1163
|
|
1164
|
+
You can also specify a special set of features that help improve the behavior of guests
|
1165
|
+
running Microsoft Windows.
|
1166
|
+
|
1167
|
+
You can specify HyperV features via `libvirt.hyperv_feature`. Available
|
1168
|
+
options are listed below. Note that both options are required:
|
1169
|
+
|
1170
|
+
* `name` - The name of the feature Hypervisor feature (see Libvirt doc)
|
1171
|
+
* `state` - The state for this feature which can be either `on` or `off`.
|
1172
|
+
|
1173
|
+
```ruby
|
1174
|
+
Vagrant.configure("2") do |config|
|
1175
|
+
config.vm.provider :libvirt do |libvirt|
|
1176
|
+
# Relax constraints on timers
|
1177
|
+
libvirt.hyperv_feature :name => 'relaxed', :state => 'on'
|
1178
|
+
# Enable virtual APIC
|
1179
|
+
libvirt.hyperv_feature :name => 'vapic', :state => 'on'
|
1180
|
+
end
|
1181
|
+
end
|
1182
|
+
```
|
1183
|
+
|
985
1184
|
## CPU features
|
986
1185
|
|
987
1186
|
You can specify CPU feature policies via `libvirt.cpu_feature`. Available
|
988
1187
|
options are listed below. Note that both options are required:
|
989
1188
|
|
990
|
-
* `name` - The name of the feature for the chosen CPU (see
|
1189
|
+
* `name` - The name of the feature for the chosen CPU (see Libvirt's
|
991
1190
|
`cpu_map.xml`)
|
992
1191
|
* `policy` - The policy for this feature (one of `force`, `require`,
|
993
|
-
`optional`, `disable` and `forbid` - see
|
1192
|
+
`optional`, `disable` and `forbid` - see Libvirt documentation)
|
994
1193
|
|
995
1194
|
```ruby
|
996
1195
|
Vagrant.configure("2") do |config|
|
@@ -1023,30 +1222,6 @@ Vagrant.configure("2") do |config|
|
|
1023
1222
|
end
|
1024
1223
|
end
|
1025
1224
|
```
|
1026
|
-
## USB device passthrough
|
1027
|
-
|
1028
|
-
You can specify multiple USB devices to passthrough to the VM via
|
1029
|
-
`libvirt.usb`. The device can be specified by the following options:
|
1030
|
-
|
1031
|
-
* `bus` - The USB bus ID, e.g. "1"
|
1032
|
-
* `device` - The USB device ID, e.g. "2"
|
1033
|
-
* `vendor` - The USB devices vendor ID (VID), e.g. "0x1234"
|
1034
|
-
* `product` - The USB devices product ID (PID), e.g. "0xabcd"
|
1035
|
-
|
1036
|
-
At least one of these has to be specified, and `bus` and `device` may only be
|
1037
|
-
used together.
|
1038
|
-
|
1039
|
-
The example values above match the device from the following output of `lsusb`:
|
1040
|
-
|
1041
|
-
```
|
1042
|
-
Bus 001 Device 002: ID 1234:abcd Example device
|
1043
|
-
```
|
1044
|
-
|
1045
|
-
Additionally, the following options can be used:
|
1046
|
-
|
1047
|
-
* `startupPolicy` - Is passed through to libvirt and controls if the device has
|
1048
|
-
to exist. libvirt currently allows the following values: "mandatory",
|
1049
|
-
"requisite", "optional".
|
1050
1225
|
|
1051
1226
|
## No box and PXE boot
|
1052
1227
|
|
@@ -1169,9 +1344,44 @@ mounting them at boot.
|
|
1169
1344
|
|
1170
1345
|
Further documentation on using 9p can be found in [kernel docs](https://www.kernel.org/doc/Documentation/filesystems/9p.txt) and in [QEMU wiki](https://wiki.qemu.org/Documentation/9psetup#Starting_the_Guest_directly). Please do note that 9p depends on support in the guest and not all distros come with the 9p module by default.
|
1171
1346
|
|
1172
|
-
**SECURITY NOTE:** for remote
|
1173
|
-
public network interface and you must connect to
|
1347
|
+
**SECURITY NOTE:** for remote Libvirt, nfs synced folders requires a bridged
|
1348
|
+
public network interface and you must connect to Libvirt via ssh.
|
1349
|
+
|
1350
|
+
## QEMU Session Support
|
1351
|
+
|
1352
|
+
vagrant-libvirt supports using QEMU user sessions to maintain Vagrant VMs. As the session connection does not have root access to the system features which require root will not work. Access to networks created by the system QEMU connection can be granted by using the [QEMU bridge helper](https://wiki.qemu.org/Features/HelperNetworking). The bridge helper is enabled by default on some distros but may need to be enabled/installed on others.
|
1353
|
+
|
1354
|
+
There must be a virbr network defined in the QEMU system session. The libvirt `default` network which comes by default, the vagrant `vagrant-libvirt` network which is generated if you run a Vagrantfile using the System session, or a manually defined network can be used. These networks can be set to autostart with `sudo virsh net-autostart <net-name>`, which'll mean no further root access is required even after reboots.
|
1355
|
+
|
1356
|
+
The QEMU bridge helper is configured via `/etc/qemu/bridge.conf`. This file must include the virbr you wish to use (e.g. virbr0, virbr1, etc). You can find this out via `sudo virsh net-dumpxml <net-name>`.
|
1357
|
+
```
|
1358
|
+
allow virbr0
|
1359
|
+
```
|
1174
1360
|
|
1361
|
+
An example configuration of a machine using the QEMU session connection:
|
1362
|
+
|
1363
|
+
```ruby
|
1364
|
+
Vagrant.configure("2") do |config|
|
1365
|
+
config.vm.provider :libvirt do |libvirt|
|
1366
|
+
# Use QEMU session instead of system connection
|
1367
|
+
libvirt.qemu_use_session = true
|
1368
|
+
# URI of QEMU session connection, default is as below
|
1369
|
+
libvirt.uri = 'qemu:///session'
|
1370
|
+
# URI of QEMU system connection, use to obtain IP address for management, default is below
|
1371
|
+
libvirt.system_uri = 'qemu:///system'
|
1372
|
+
# Path to store Libvirt images for the virtual machine, default is as ~/.local/share/libvirt/images
|
1373
|
+
libvirt.storage_pool_path = '/home/user/.local/share/libvirt/images'
|
1374
|
+
# Management network device, default is below
|
1375
|
+
libvirt.management_network_device = 'virbr0'
|
1376
|
+
end
|
1377
|
+
|
1378
|
+
# Public network configuration using existing network device
|
1379
|
+
# Note: Private networks do not work with QEMU session enabled as root access is required to create new network devices
|
1380
|
+
config.vm.network :public_network, :dev => "virbr1",
|
1381
|
+
:mode => "bridge",
|
1382
|
+
:type => "bridge"
|
1383
|
+
end
|
1384
|
+
```
|
1175
1385
|
|
1176
1386
|
## Customized Graphics
|
1177
1387
|
|
@@ -1222,7 +1432,7 @@ end
|
|
1222
1432
|
|
1223
1433
|
For certain functionality to be available within a guest, a private
|
1224
1434
|
communication channel must be established with the host. Two notable examples
|
1225
|
-
of this are the
|
1435
|
+
of this are the QEMU guest agent, and the Spice/QXL graphics type.
|
1226
1436
|
|
1227
1437
|
Below is a simple example which exposes a virtio serial channel to the guest.
|
1228
1438
|
Note: in a multi-VM environment, the channel would be created for all VMs.
|
@@ -1248,7 +1458,7 @@ end
|
|
1248
1458
|
|
1249
1459
|
These settings can be specified on a per-VM basis, however the per-guest
|
1250
1460
|
settings will OVERRIDE any global 'config' setting. In the following example,
|
1251
|
-
we create 3
|
1461
|
+
we create 3 VMs with the following configuration:
|
1252
1462
|
|
1253
1463
|
* **master**: No channel settings specified, so we default to the provider
|
1254
1464
|
setting of a single virtio guest agent channel.
|
@@ -1263,7 +1473,7 @@ For example:
|
|
1263
1473
|
|
1264
1474
|
```ruby
|
1265
1475
|
Vagrant.configure(2) do |config|
|
1266
|
-
config.vm.box = "fedora/
|
1476
|
+
config.vm.box = "fedora/32-cloud-base"
|
1267
1477
|
config.vm.provider :libvirt do |libvirt|
|
1268
1478
|
libvirt.channel :type => 'unix', :target_name => 'org.qemu.guest_agent.0', :target_type => 'virtio'
|
1269
1479
|
end
|
@@ -1289,8 +1499,8 @@ Vagrant.configure(2) do |config|
|
|
1289
1499
|
end
|
1290
1500
|
```
|
1291
1501
|
|
1292
|
-
## Custom command line arguments
|
1293
|
-
You can also specify multiple qemuargs arguments for qemu-system
|
1502
|
+
## Custom command line arguments and environment variables
|
1503
|
+
You can also specify multiple qemuargs arguments or qemuenv environment variables for qemu-system
|
1294
1504
|
|
1295
1505
|
* `value` - Value
|
1296
1506
|
|
@@ -1299,6 +1509,9 @@ Vagrant.configure("2") do |config|
|
|
1299
1509
|
config.vm.provider :libvirt do |libvirt|
|
1300
1510
|
libvirt.qemuargs :value => "-device"
|
1301
1511
|
libvirt.qemuargs :value => "intel-iommu"
|
1512
|
+
libvirt.qemuenv QEMU_AUDIO_DRV: 'pa'
|
1513
|
+
libvirt.qemuenv QEMU_AUDIO_TIMER_PERIOD: '150'
|
1514
|
+
libvirt.qemuenv QEMU_PA_SAMPLES: '1024', QEMU_PA_SERVER: '/run/user/1000/pulse/native'
|
1302
1515
|
end
|
1303
1516
|
end
|
1304
1517
|
```
|
@@ -1336,6 +1549,72 @@ $ cd packer-qemu-templates
|
|
1336
1549
|
$ packer build ubuntu-14.04-server-amd64-vagrant.json
|
1337
1550
|
```
|
1338
1551
|
|
1552
|
+
## Package Box from VM
|
1553
|
+
|
1554
|
+
vagrant-libvirt has native support for [`vagrant
|
1555
|
+
package`](https://www.vagrantup.com/docs/cli/package.html) via
|
1556
|
+
libguestfs [virt-sysprep](http://libguestfs.org/virt-sysprep.1.html).
|
1557
|
+
virt-sysprep operations can be customized via the
|
1558
|
+
`VAGRANT_LIBVIRT_VIRT_SYSPREP_OPERATIONS` environment variable; see the
|
1559
|
+
[upstream
|
1560
|
+
documentation](http://libguestfs.org/virt-sysprep.1.html#operations) for
|
1561
|
+
further details especially on default sysprep operations enabled for
|
1562
|
+
your system.
|
1563
|
+
|
1564
|
+
Options to the virt-sysprep command call can be passed via
|
1565
|
+
`VAGRANT_LIBVIRT_VIRT_SYSPREP_OPTIONS` environment variable.
|
1566
|
+
|
1567
|
+
```shell
|
1568
|
+
$ export VAGRANT_LIBVIRT_VIRT_SYSPREP_OPTIONS="--delete /etc/hostname"
|
1569
|
+
$ vagrant package
|
1570
|
+
```
|
1571
|
+
|
1572
|
+
For example, on Chef [bento](https://github.com/chef/bento) VMs that
|
1573
|
+
require SSH hostkeys already set (e.g. bento/debian-7) as well as leave
|
1574
|
+
existing LVM UUIDs untouched (e.g. bento/ubuntu-18.04), these can be
|
1575
|
+
packaged into vagrant-libvirt boxes like so:
|
1576
|
+
|
1577
|
+
```shell
|
1578
|
+
$ export VAGRANT_LIBVIRT_VIRT_SYSPREP_OPERATIONS="defaults,-ssh-userdir,-ssh-hostkeys,-lvm-uuids"
|
1579
|
+
$ vagrant package
|
1580
|
+
```
|
1581
|
+
|
1582
|
+
## Troubleshooting VMs
|
1583
|
+
|
1584
|
+
The first step for troubleshooting a VM image that appears to not boot correctly,
|
1585
|
+
or hangs waiting to get an IP, is to check it with a VNC viewer. A key thing
|
1586
|
+
to remember is that if the VM doesn't get an IP, then vagrant can't communicate
|
1587
|
+
with it to configure anything, so a problem at this stage is likely to come from
|
1588
|
+
the VM, but we'll outline the tools and common problems to help you troubleshoot
|
1589
|
+
that.
|
1590
|
+
|
1591
|
+
By default, when you create a new VM, a vnc server will listen on `127.0.0.1` on
|
1592
|
+
port `TCP5900`. If you connect with a vnc viewer you can see the boot process. If
|
1593
|
+
your VM isn't listening on `5900` by default, you can use `virsh dumpxml` to find
|
1594
|
+
out which port it's listening on, or can configure it with `graphics_port` and
|
1595
|
+
`graphics_ip` (see 'Domain Specific Options' above).
|
1596
|
+
|
1597
|
+
Note: Connecting with the console (`virsh console`) requires additional config,
|
1598
|
+
so some VMs may not show anything on the console at all, instead displaying it in
|
1599
|
+
the VNC console. The issue with the text console is that you also need to build the
|
1600
|
+
image used to tell the kernel to output to the console during boot, and typically
|
1601
|
+
most do not have this built in.
|
1602
|
+
|
1603
|
+
Problems we've seen in the past include:
|
1604
|
+
- Forgetting to remove `/etc/udev/rules.d/70-persistent-net.rules` before packaging
|
1605
|
+
the VM
|
1606
|
+
- VMs expecting a specific disk device to be connected
|
1607
|
+
|
1608
|
+
If you're still confused, check the Github Issues for this repo for anything that
|
1609
|
+
looks similar to your problem.
|
1610
|
+
|
1611
|
+
[Github Issue #1032](https://github.com/vagrant-libvirt/vagrant-libvirt/issues/1032)
|
1612
|
+
contains some historical troubleshooting for VMs that appeared to hang.
|
1613
|
+
|
1614
|
+
Did you hit a problem that you'd like to note here to save time in the future?
|
1615
|
+
Please do!
|
1616
|
+
|
1617
|
+
|
1339
1618
|
## Development
|
1340
1619
|
|
1341
1620
|
To work on the `vagrant-libvirt` plugin, clone this repository out, and use
|
@@ -1378,3 +1657,8 @@ $ bundle exec vagrant up --provider=libvirt
|
|
1378
1657
|
3. Commit your changes (`git commit -am 'Add some feature'`)
|
1379
1658
|
4. Push to the branch (`git push origin my-new-feature`)
|
1380
1659
|
5. Create new Pull Request
|
1660
|
+
|
1661
|
+
<!--
|
1662
|
+
# styling for TOC
|
1663
|
+
vim: expandtab shiftwidth=2
|
1664
|
+
-->
|