vagrant-libvirt 0.0.45 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 418a49ce7fd1b2f951f64f38e13479bbe2b894933b3127d8e70ad47a27ec78a5
-  data.tar.gz: 6450a6b6a234718c59481418ecb8568af1dc1ddd8d924af1f5879e632dc3cabd
+  metadata.gz: 66b4cb8c917f32893e6388405ce042fb81d3b210f74bd8e3d58fde97b6892e91
+  data.tar.gz: 2fce46049e74a94879f5f272dcd51ded4e18f95655b6b95c126b6aec5368de44
 SHA512:
-  metadata.gz: 81a5f88b26b1048b66c8bc7249443c6f013d157dd2d43df4c2cc523f94d5e9fc96f52b522f2addab2347607ce9d8226695662032da08caaf4aabd0a5f1667120
-  data.tar.gz: 90dca18364b8b9eb23c9598d480717d2113d9b43f5846189174e4ca25868cd52a7d37ed3fde5614d8a132cf3163c8e07c8682cb9c6cb518bfa3f28381a99f0f8
+  metadata.gz: c2588e0531385b63201c9fde375ef5736eedc8d8f4504e7ea84e36dbdef94d4a1020d9574b3d2b4a1f5897cb9c4cf61c1b506d4cdfe050b6719fedd16fbdb816
+  data.tar.gz: 2f02d3407ff2ff6655207eac3fd14e93ad7a0e7873941e5218efc9c46b8802d14de60f08e18fbefb989ca906e1a36e5f1e866dd8f33a899309cccc7f8dfae3c5

data/README.md

@@ -4,7 +4,7 @@
 [![Build Status](https://travis-ci.org/vagrant-libvirt/vagrant-libvirt.svg)](https://travis-ci.org/vagrant-libvirt/vagrant-libvirt)
 [![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)
 
-This is a [Vagrant](http://www.vagrantup.com) plugin that adds an
+This is a [Vagrant](http://www.vagrantup.com) plugin that adds a
 [Libvirt](http://libvirt.org) provider to Vagrant, allowing Vagrant to
 control and provision machines via Libvirt toolkit.
 
@@ -13,6 +13,8 @@ can help a lot :-)
 
 ## Index
 
+<!-- note in vim set "let g:vmt_list_item_char='-'" to generate the correct output -->
+<!-- vim-markdown-toc GFM -->
 
 - [Features](#features)
 - [Future work](#future-work)
@@ -32,28 +34,39 @@ can help a lot :-)
   - [Public Network Options](#public-network-options)
   - [Management Network](#management-network)
 - [Additional Disks](#additional-disks)
-    - [Reload behavior](#reload-behavior-1)
+  - [Reload behavior](#reload-behavior-1)
 - [CDROMs](#cdroms)
 - [Input](#input)
 - [PCI device passthrough](#pci-device-passthrough)
-- [USB Controller Configuration](#usb-controller-configuration)
-- [USB Redirector Devices](#usb-redirector-devices)
+- [Using USB Devices](#using-usb-devices)
+  - [USB Controller Configuration](#usb-controller-configuration)
+  - [USB Device Passthrough](#usb-device-passthrough)
+  - [USB Redirector Devices](#usb-redirector-devices)
+    - [Filter for USB Redirector Devices](#filter-for-usb-redirector-devices)
 - [Random number generator passthrough](#random-number-generator-passthrough)
-- [Watchdog·Device](#watchdog-device)
+- [Watchdog device](#watchdog-device)
 - [Smartcard device](#smartcard-device)
 - [Hypervisor Features](#hypervisor-features)
-- [CPU Features](#cpu-features)
+- [CPU features](#cpu-features)
+- [Memory Backing](#memory-backing)
 - [No box and PXE boot](#no-box-and-pxe-boot)
 - [SSH Access To VM](#ssh-access-to-vm)
 - [Forwarded Ports](#forwarded-ports)
 - [Synced Folders](#synced-folders)
 - [QEMU Session Support](#qemu-session-support)
 - [Customized Graphics](#customized-graphics)
+- [TPM Devices](#tpm-devices)
+- [Libvirt communication channels](#libvirt-communication-channels)
+- [Custom command line arguments and environment variables](#custom-command-line-arguments-and-environment-variables)
 - [Box Format](#box-format)
 - [Create Box](#create-box)
+- [Package Box from VM](#package-box-from-vm)
+- [Troubleshooting VMs](#troubleshooting-vms)
 - [Development](#development)
 - [Contributing](#contributing)
 
+<!-- vim-markdown-toc -->
+
 ## Features
 
 * Control local Libvirt hypervisors.
@@ -81,27 +94,39 @@ can help a lot :-)
 
 ## Installation
 
-First, you should have both qemu and libvirt installed if you plan to run VMs
-on your local system. For instructions, refer to your linux distribution's
+First, you should have both QEMU and Libvirt installed if you plan to run VMs
+on your local system. For instructions, refer to your Linux distribution's
 documentation.
 
-**NOTE:** Before you start using Vagrant-libvirt, please make sure your libvirt
-and qemu installation is working correctly and you are able to create qemu or
-kvm type virtual machines with `virsh` or `virt-manager`.
+**NOTE:** Before you start using vagrant-libvirt, please make sure your Libvirt
+and QEMU installation is working correctly and you are able to create QEMU or
+KVM type virtual machines with `virsh` or `virt-manager`.
 
 Next, you must have [Vagrant
 installed](http://docs.vagrantup.com/v2/installation/index.html).
-Vagrant-libvirt supports Vagrant 1.5, 1.6, 1.7 and 1.8.
-*We only test with the upstream version!* If you decide to install your distros
+Vagrant-libvirt supports Vagrant 2.0, 2.1 & 2.2. It should also work with earlier
+releases from 1.5 onwards but they are not actively tested.
+
+Check the [.travis.yml](https://github.com/vagrant-libvirt/vagrant-libvirt/blob/master/.travis.yml)
+for the current list of tested versions.
+
+*We only test with the upstream version!* If you decide to install your distro's
 version and you run into problems, as a first step you should switch to upstream.
 
 Now you need to make sure your have all the build dependencies installed for
 vagrant-libvirt. This depends on your distro. An overview:
 
-* Ubuntu 12.04/14.04/16.04, Debian:
+* Ubuntu 18.10, Debian 9 and up:
+```shell
+apt-get build-dep vagrant ruby-libvirt
+apt-get install qemu libvirt-daemon-system libvirt-clients ebtables dnsmasq-base
+apt-get install libxslt-dev libxml2-dev libvirt-dev zlib1g-dev ruby-dev
+```
+
+* Ubuntu 18.04, Debian 8 and older:
 ```shell
 apt-get build-dep vagrant ruby-libvirt
-apt-get install qemu libvirt-bin ebtables dnsmasq
+apt-get install qemu libvirt-bin ebtables dnsmasq-base
 apt-get install libxslt-dev libxml2-dev libvirt-dev zlib1g-dev ruby-dev
 ```
 
@@ -114,10 +139,15 @@ yum install qemu libvirt libvirt-devel ruby-devel gcc qemu-kvm
 
 * Fedora 22 and up:
 ```shell
-dnf -y install qemu libvirt libvirt-devel ruby-devel gcc
+dnf install -y gcc libvirt libvirt-devel libxml2-devel make ruby-devel
+```
+
+* OpenSUSE leap 15.1:
+```shell
+zypper install qemu libvirt libvirt-devel ruby-devel gcc qemu-kvm
 ```
 
-* Arch linux: please read the related [ArchWiki](https://wiki.archlinux.org/index.php/Vagrant#vagrant-libvirt) page.
+* Arch Linux: please read the related [ArchWiki](https://wiki.archlinux.org/index.php/Vagrant#vagrant-libvirt) page.
 ```shell
 pacman -S vagrant
 ```
@@ -125,8 +155,16 @@ pacman -S vagrant
 Now you're ready to install vagrant-libvirt using standard [Vagrant
 plugin](http://docs.vagrantup.com/v2/plugins/usage.html) installation methods.
 
+For some distributions you will need to specify `CONFIGURE_ARGS` variable before
+running `vagrant plugin install`:
+
+* Fedora 32 + upstream Vagrant:
+  ```shell
+  export CONFIGURE_ARGS="with-libvirt-include=/usr/include/libvirt with-libvirt-lib=/usr/lib64"
+  ```
+
 ```shell
-$ vagrant plugin install vagrant-libvirt
+vagrant plugin install vagrant-libvirt
 ```
 
 ### Possible problems with plugin installation on Linux
@@ -145,7 +183,7 @@ $ sudo dnf install libxslt-devel libxml2-devel libvirt-devel \
   libguestfs-tools-c ruby-devel gcc
 ```
 
-On Arch linux it is recommended to follow [steps from ArchWiki](https://wiki.archlinux.org/index.php/Vagrant#vagrant-libvirt).
+On Arch Linux it is recommended to follow [steps from ArchWiki](https://wiki.archlinux.org/index.php/Vagrant#vagrant-libvirt).
 
 If have problem with installation - check your linker. It should be `ld.gold`:
 
@@ -167,8 +205,8 @@ CONFIGURE_ARGS='with-ldflags=-L/opt/vagrant/embedded/lib with-libvirt-include=/u
 After installing the plugin (instructions above), the quickest way to get
 started is to add Libvirt box and specify all the details manually within a
 `config.vm.provider` block. So first, add Libvirt box using any name you want.
-You can find more libvirt ready boxes at
-[Atlas](https://atlas.hashicorp.com/boxes/search?provider=libvirt). For
+You can find more Libvirt-ready boxes at
+[Vagrant Cloud](https://app.vagrantup.com/boxes/search?provider=libvirt). For
 example:
 
 ```shell
@@ -208,7 +246,7 @@ export VAGRANT_DEFAULT_PROVIDER=libvirt
 
 Vagrant goes through steps below when creating new project:
 
-1. Connect to Libvirt localy or remotely via SSH.
+1. Connect to Libvirt locally or remotely via SSH.
 2. Check if box image is available in Libvirt storage pool. If not, upload it
    to remote Libvirt storage pool as new volume.
 3. Create COW diff image of base box image for new Libvirt domain.
@@ -225,22 +263,22 @@ Vagrant goes through steps below when creating new project:
 Although it should work without any configuration for most people, this
 provider exposes quite a few provider-specific configuration options. The
 following options allow you to configure how vagrant-libvirt connects to
-libvirt, and are used to generate the [libvirt connection
+Libvirt, and are used to generate the [Libvirt connection
 URI](http://libvirt.org/uri.html):
 
-* `driver` - A hypervisor name to access. For now only kvm and qemu are
+* `driver` - A hypervisor name to access. For now only KVM and QEMU are
   supported
-* `host` - The name of the server, where libvirtd is running
+* `host` - The name of the server, where Libvirtd is running
 * `connect_via_ssh` - If use ssh tunnel to connect to Libvirt. Absolutely
-  needed to access libvirt on remote host. It will not be able to get the IP
+  needed to access Libvirt on remote host. It will not be able to get the IP
   address of a started VM otherwise.
 * `username` - Username and password to access Libvirt
 * `password` - Password to access Libvirt
 * `id_ssh_key_file` - If not nil, uses this ssh private key to access Libvirt.
   Default is `$HOME/.ssh/id_rsa`. Prepends `$HOME/.ssh/` if no directory
-* `socket` - Path to the libvirt unix socket (e.g.
+* `socket` - Path to the Libvirt unix socket (e.g.
   `/var/run/libvirt/libvirt-sock`)
-* `uri` - For advanced usage. Directly specifies what libvirt connection URI
+* `uri` - For advanced usage. Directly specifies what Libvirt connection URI
   vagrant-libvirt should use. Overrides all other connection configuration
   options
 
@@ -262,7 +300,7 @@ end
 ### Domain Specific Options
 
 * `disk_bus` - The type of disk device to emulate. Defaults to virtio if not
-  set. Possible values are documented in libvirt's [description for
+  set. Possible values are documented in Libvirt's [description for
   _target_](http://libvirt.org/formatdomain.html#elementsDisks). NOTE: this
   option applies only to disks associated with a box image. To set the bus type
   on additional disks, see the [Additional Disks](#additional-disks) section.
@@ -273,22 +311,26 @@ end
 * `nic_model_type` - parameter specifies the model of the network adapter when
   you create a domain value by default virtio KVM believe possible values, see
   the [documentation for
-  libvirt](https://libvirt.org/formatdomain.html#elementsNICSModel).
+  Libvirt](https://libvirt.org/formatdomain.html#elementsNICSModel).
+* `shares` - Proportional weighted share for the domain relative to others. For more details see [documentation](https://libvirt.org/formatdomain.html#elementsCPUTuning).
 * `memory` - Amount of memory in MBytes. Defaults to 512 if not set.
 * `cpus` - Number of virtual cpus. Defaults to 1 if not set.
+* `cpuset` - Physical cpus to which the vcpus can be pinned. For more details see [documentation](https://libvirt.org/formatdomain.html#elementsCPUAllocation).
 * `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).
+* `nodeset` - Physical NUMA nodes where virtual memory can be pinned. For more details see [documentation](https://libvirt.org/formatdomain.html#elementsNUMATuning).
 
   ```ruby
   Vagrant.configure("2") do |config|
     config.vm.provider :libvirt do |libvirt|
       libvirt.cpus = 4
+      libvirt.cpuset = '1-4,^3,6'
       libvirt.cputopology :sockets => '2', :cores => '2', :threads => '1'
     end
   end
   ```
 
 * `nested` - [Enable nested
-  virtualization](https://github.com/torvalds/linux/blob/master/Documentation/virtual/kvm/nested-vmx.txt).
+  virtualization](https://docs.fedoraproject.org/en-US/quick-docs/using-nested-virtualization-in-kvm/).
   Default is false.
 * `cpu_mode` - [CPU emulation
   mode](https://libvirt.org/formatdomain.html#elementsCPU). Defaults to
@@ -297,7 +339,7 @@ end
 * `cpu_model` - CPU Model. Defaults to 'qemu64' if not set and `cpu_mode` is
   `custom` and to '' otherwise. This can really only be used when setting
   `cpu_mode` to `custom`.
-* `cpu_fallback` - Whether to allow libvirt to fall back to a CPU model close
+* `cpu_fallback` - Whether to allow Libvirt to fall back to a CPU model close
   to the specified model if features in the guest CPU are not supported on the
   host. Defaults to 'allow' if not set. Allowed values: `allow`, `forbid`.
 * `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`.
@@ -313,7 +355,7 @@ end
 * `loader` - Sets path to custom UEFI loader.
 * `volume_cache` - Controls the cache mechanism. Possible values are "default",
   "none", "writethrough", "writeback", "directsync" and "unsafe". [See
-  driver->cache in libvirt
+  driver->cache in Libvirt
   documentation](http://libvirt.org/formatdomain.html#elementsDisks).
 * `kernel` - To launch the guest with a kernel residing on host filesystems.
   Equivalent to qemu `-kernel`.
@@ -321,6 +363,9 @@ end
   to qemu `-initrd`.
 * `random_hostname` - To create a domain name with extra information on the end
   to prevent hostname conflicts.
+* `default_prefix` - The default Libvirt guest name becomes a concatenation of the
+   `<current_directory>_<guest_name>`. The current working directory is the default prefix
+   to the guest name. The `default_prefix` options allow you to set the guest name prefix.
 * `cmd_line` - Arguments passed on to the guest kernel initramfs or initrd to
   use. Equivalent to qemu `-append`, only possible to use in combination with `initrd` and `kernel`.
 * `graphics_type` - Sets the protocol used to expose the guest display.
@@ -331,8 +376,8 @@ end
 * `graphics_ip` - Sets the IP for the display protocol to bind to.  Defaults to
   "127.0.0.1".
 * `graphics_passwd` - Sets the password for the display protocol. Working for
-  vnc and spice. by default working without passsword.
-* `graphics_autoport` - Sets autoport for graphics, libvirt in this case
+  vnc and Spice. by default working without passsword.
+* `graphics_autoport` - Sets autoport for graphics, Libvirt in this case
   ignores graphics_port value, Defaults to 'yes'. Possible value are "yes" and
   "no"
 * `keymap` - Set keymap for vm. default: en-us
@@ -349,8 +394,8 @@ end
   Defaults to "ich6".
 * `machine_type` - Sets machine type. Equivalent to qemu `-machine`. Use
   `qemu-system-x86_64 -machine help` to get a list of supported machines.
-* `machine_arch` - Sets machine architecture. This helps libvirt to determine
-  the correct emulator type. Possible values depend on your version of qemu.
+* `machine_arch` - Sets machine architecture. This helps Libvirt to determine
+  the correct emulator type. Possible values depend on your version of QEMU.
   For possible values, see which emulator executable `qemu-system-*` your
   system provides. Common examples are `aarch64`, `alpha`, `arm`, `cris`,
   `i386`, `lm32`, `m68k`, `microblaze`, `microblazeel`, `mips`, `mips64`,
@@ -374,7 +419,7 @@ end
 * `nic_adapter_count` - Defaults to '8'. Only use case for increasing this
   count is for VMs that virtualize switches such as Cumulus Linux. Max value
   for Cumulus Linux VMs is 33.
-* `uuid` - Force a domain UUID. Defaults to autogenerated value by libvirt if
+* `uuid` - Force a domain UUID. Defaults to autogenerated value by Libvirt if
   not set.
 * `suspend_mode` - What is done on vagrant suspend. Possible values: 'pause',
   'managedsave'. Pause mode executes a la `virsh suspend`, which just pauses
@@ -388,10 +433,10 @@ end
   specified here.
 * `autostart` - Automatically start the domain when the host boots. Defaults to
   'false'.
-* `channel` - [libvirt
+* `channel` - [Libvirt
   channels](https://libvirt.org/formatdomain.html#elementCharChannel).
   Configure a private communication channel between the host and guest, e.g.
-  for use by the [qemu guest
+  for use by the [QEMU guest
   agent](http://wiki.libvirt.org/page/Qemu_guest_agent) and the Spice/QXL
   graphics type.
 * `mgmt_attach` - Decide if VM has interface in mgmt network. If set to 'false'
@@ -472,11 +517,11 @@ https://libvirt.org/formatdomain.html#elementsNICSTCP
 
 http://libvirt.org/formatdomain.html#elementsNICSMulticast
 
-http://libvirt.org/formatdomain.html#elementsNICSUDP _(in libvirt v1.2.20 and higher)_
+http://libvirt.org/formatdomain.html#elementsNICSUDP _(in Libvirt v1.2.20 and higher)_
 
 Public Network interfaces are currently implemented using the macvtap driver.
 The macvtap driver is only available with the Linux Kernel version >= 2.6.24.
-See the following libvirt documentation for the details of the macvtap usage.
+See the following Libvirt documentation for the details of the macvtap usage.
 
 http://www.libvirt.org/formatdomain.html#elementsNICSDirect
 
@@ -545,7 +590,7 @@ In example below, one network interface is configured for VM `test_vm1`. After
 you run `vagrant up`, VM will be accessible on IP address `10.20.30.40`. So if
 you install a web server via provisioner, you will be able to access your
 testing server on `http://10.20.30.40` URL. But beware that this address is
-private to libvirt host only. It's not visible outside of the hypervisor box.
+private to Libvirt host only. It's not visible outside of the hypervisor box.
 
 If network `10.20.30.0/24` doesn't exist, provider will create it. By default
 created networks are NATed to outside world, so your VM will be able to connect
@@ -562,11 +607,11 @@ reachable by anyone with access to the public network.
 
 *Note: These options are not applicable to public network interfaces.*
 
-There is a way to pass specific options for libvirt provider when using
+There is a way to pass specific options for Libvirt provider when using
 `config.vm.network` to configure new network interface. Each parameter name
 starts with `libvirt__` string. Here is a list of those options:
 
-* `:libvirt__network_name` - Name of libvirt network to connect to. By default,
+* `:libvirt__network_name` - Name of Libvirt network to connect to. By default,
   network 'default' is used.
 * `:libvirt__netmask` - Used only together with `:ip` option. Default is
   '255.255.255.0'.
@@ -605,7 +650,7 @@ starts with `libvirt__` string. Here is a list of those options:
   between Guests. Useful for Switch VMs like Cumulus Linux. No virtual switch
   setting like `libvirt__network_name` applies with tunnel interfaces and will
   be ignored if configured.
-* `:libvirt__tunnel_ip` - Sets the source IP of the libvirt tunnel interface.
+* `:libvirt__tunnel_ip` - Sets the source IP of the Libvirt tunnel interface.
   By default this is `127.0.0.1` for TCP and UDP tunnels and `239.255.1.1` for
   Multicast tunnels. It populates the address field in the `<source
   address="XXX">` of the interface xml configuration.
@@ -615,11 +660,11 @@ starts with `libvirt__` string. Here is a list of those options:
 * `:libvirt__tunnel_local_port` - Sets the local port used by the udp tunnel
   interface type. It populates the port field in the `<local port=XXX">`
   section of the interface xml configuration. _(This feature only works in
-  libvirt 1.2.20 and higher)_
+  Libvirt 1.2.20 and higher)_
 * `:libvirt__tunnel_local_ip` - Sets the local IP used by the udp tunnel
   interface type. It populates the ip entry of the `<local address=XXX">`
   section of the interface xml configuration. _(This feature only works in
-  libvirt 1.2.20 and higher)_
+  Libvirt 1.2.20 and higher)_
 * `:libvirt__guest_ipv6` - Enable or disable guest-to-guest IPv6 communication.
   See [here](https://libvirt.org/formatnetwork.html#examplesPrivate6), and
   [here](http://libvirt.org/git/?p=libvirt.git;a=commitdiff;h=705e67d40b09a905cd6a4b8b418d5cb94eaa95a8)
@@ -631,18 +676,18 @@ starts with `libvirt__` string. Here is a list of those options:
   failures](https://github.com/vagrant-libvirt/vagrant-libvirt/pull/498)
 * `:mac` - MAC address for the interface. *Note: specify this in lowercase
   since Vagrant network scripts assume it will be!*
-* `:libvirt__mtu` - MTU size for the libvirt network, if not defined, the
-  created network will use the libvirt default (1500). VMs still need to set the
+* `:libvirt__mtu` - MTU size for the Libvirt network, if not defined, the
+  created network will use the Libvirt default (1500). VMs still need to set the
   MTU accordingly.
 * `:model_type` - parameter specifies the model of the network adapter when you
   create a domain value by default virtio KVM believe possible values, see the
-  documentation for libvirt
+  documentation for Libvirt
 * `:libvirt__driver_name` - Define which network driver to use. [More
   info](https://libvirt.org/formatdomain.html#elementsDriverBackendOptions)
 * `:libvirt__driver_queues` - Define a number of queues to be used for network
   interface. Set equal to numer of vCPUs for best performance. [More
   info](http://www.linux-kvm.org/page/Multiqueue)
-* `:autostart` - Automatic startup of network by the libvirt daemon.
+* `:autostart` - Automatic startup of network by the Libvirt daemon.
   If not specified the default is 'false'.
 * `:bus` - The bus of the PCI device. Both :bus and :slot have to be defined.
 * `:slot` - The slot of the PCI device. Both :bus and :slot have to be defined.
@@ -663,8 +708,8 @@ virtual network.
   Default mode is 'bridge'.
 * `:type` - is type of interface.(`<interface type="#{@type}">`)
 * `:mac` - MAC address for the interface.
-* `:network_name` - Name of libvirt network to connect to.
-* `:portgroup` - Name of libvirt portgroup to connect to.
+* `:network_name` - Name of Libvirt network to connect to.
+* `:portgroup` - Name of Libvirt portgroup to connect to.
 * `:ovs` - Support to connect to an Open vSwitch bridge device. Default is
   'false'.
 * `:trust_guest_rx_filters` - Support trustGuestRxFilters attribute. Details
@@ -675,17 +720,17 @@ virtual network.
 
 vagrant-libvirt uses a private network to perform some management operations on
 VMs. All VMs will have an interface connected to this network and an IP address
-dynamically assigned by libvirt unless you set `:mgmt_attach` to 'false'.
+dynamically assigned by Libvirt unless you set `:mgmt_attach` to 'false'.
 This is in addition to any networks you configure. The name and address
 used by this network are configurable at the provider level.
 
-* `management_network_name` - Name of libvirt network to which all VMs will be
+* `management_network_name` - Name of Libvirt network to which all VMs will be
   connected. If not specified the default is 'vagrant-libvirt'.
 * `management_network_address` - Address of network to which all VMs will be
   connected. Must include the address and subnet mask. If not specified the
   default is '192.168.121.0/24'.
-* `management_network_mode` - Network mode for the libvirt management network.
-  Specify one of veryisolated, none, nat or route options. Further documentated
+* `management_network_mode` - Network mode for the Libvirt management network.
+  Specify one of veryisolated, none, nat or route options. Further documented
   under [Private Networks](#private-network-options)
 * `management_network_guest_ipv6` - Enable or disable guest-to-guest IPv6
   communication. See
@@ -694,9 +739,10 @@ used by this network are configurable at the provider level.
   for for more information.
 * `management_network_autostart` - Automatic startup of mgmt network, if not
   specified the default is 'false'.
-* `:management_network_pci_bus` -  The bus of the PCI device.
-* `:management_network_pci_slot` -  The slot of the PCI device.
+* `management_network_pci_bus` -  The bus of the PCI device.
+* `management_network_pci_slot` -  The slot of the PCI device.
 * `management_network_mac` - MAC address of management network interface.
+* `management_network_domain` - Domain name assigned to the management network.
 
 You may wonder how vagrant-libvirt knows the IP address a VM received.  Libvirt
 doesn't provide a standard way to find out the IP address of a running domain.
@@ -804,29 +850,30 @@ end
 
 You can specify multiple PCI devices to passthrough to the VM via
 `libvirt.pci`. Available options are listed below. Note that all options are
-required:
+required, except domain, which defaults to `0x0000`:
 
+* `domain` - The domain of the PCI device
 * `bus` - The bus of the PCI device
 * `slot` - The slot of the PCI device
 * `function` - The function of the PCI device
 
 You can extract that information from output of `lspci` command. First
-characters of each line are in format `[<bus>]:[<slot>].[<func>]`. For example:
+characters of each line are in format `[<domain>]:[<bus>]:[<slot>].[<func>]`. For example:
 
 ```shell
 $ lspci| grep NVIDIA
-03:00.0 VGA compatible controller: NVIDIA Corporation GK110B [GeForce GTX TITAN Black] (rev a1)
+0000:03:00.0 VGA compatible controller: NVIDIA Corporation GK110B [GeForce GTX TITAN Black] (rev a1)
 ```
 
-In that case `bus` is `0x03`, `slot` is `0x00` and `function` is `0x0`.
+In that case `domain` is `0x0000`, `bus` is `0x03`, `slot` is `0x00` and `function` is `0x0`.
 
 ```ruby
 Vagrant.configure("2") do |config|
   config.vm.provider :libvirt do |libvirt|
-    libvirt.pci :bus => '0x06', :slot => '0x12', :function => '0x5'
+    libvirt.pci :domain => '0x0000', :bus => '0x06', :slot => '0x12', :function => '0x5'
 
     # Add another one if it is neccessary
-    libvirt.pci :bus => '0x03', :slot => '0x00', :function => '0x0'
+    libvirt.pci :domain => '0x0000', :bus => '0x03', :slot => '0x00', :function => '0x0'
   end
 end
 ```
@@ -836,15 +883,24 @@ Note! Above options affect configuration only at domain creation. It won't chang
 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.
 
 
-## USB Controller Configuration
+## Using USB Devices
+
+There are several ways to pass a USB device through to a running instance:
+* Use `libvirt.usb` to [attach a USB device at boot](#usb-device-passthrough), with the device ID specified in the Vagrantfile
+* Use a client (such as `virt-viewer` or `virt-manager`) to attach the device at runtime [via USB redirectors](#usb-redirector-devices)
+* Use `virsh attach-device` once the VM is running (however, this is outside the scope of this readme)
+
+In all cases, if you wish to use a high-speed USB device,
+you will need to use `libvirt.usb_controller` to specify a USB2 or USB3 controller,
+as the default configuration only exposes a USB1.1 controller.
+
+### USB Controller Configuration
 
 The USB controller can be configured using `libvirt.usb_controller`, with the following options:
 
 * `model` - The USB controller device model to emulate. (mandatory)
 * `ports` - The number of devices that can be connected to the controller.
 
-See the [libvirt documentation](https://libvirt.org/formatdomain.html#elementsControllers) for a list of valid models.
-
 ```ruby
 Vagrant.configure("2") do |config|
   config.vm.provider :libvirt do |libvirt|
@@ -854,8 +910,36 @@ Vagrant.configure("2") do |config|
 end
 ```
 
+See the [libvirt documentation](https://libvirt.org/formatdomain.html#elementsControllers) for a list of valid models.
+
 
-## USB Redirector Devices
+### USB Device Passthrough
+
+You can specify multiple USB devices to passthrough to the VM via
+`libvirt.usb`. The device can be specified by the following options:
+
+* `bus` - The USB bus ID, e.g. "1"
+* `device` - The USB device ID, e.g. "2"
+* `vendor` - The USB devices vendor ID (VID), e.g. "0x1234"
+* `product` - The USB devices product ID (PID), e.g. "0xabcd"
+
+At least one of these has to be specified, and `bus` and `device` may only be
+used together.
+
+The example values above match the device from the following output of `lsusb`:
+
+```
+Bus 001 Device 002: ID 1234:abcd Example device
+```
+
+Additionally, the following options can be used:
+
+* `startupPolicy` - Is passed through to Libvirt and controls if the device has
+  to exist.  Libvirt currently allows the following values: "mandatory",
+  "requisite", "optional".
+
+
+### USB Redirector Devices
 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.
 
 * `type` - The type of the USB redirector device. (`tcp` or `spicevmc`)
@@ -875,7 +959,10 @@ Vagrant.configure("2") do |config|
 end
 ```
 
-### Filter for USB Redirector Devices
+Note that in order to enable USB redirection with Spice clients,
+you may need to also set `libvirt.graphics_type = "spice"`
+
+#### Filter for USB Redirector Devices
 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.
 
 * `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).
@@ -942,7 +1029,7 @@ The optional action attribute describes what `action` to take when the watchdog
 ```ruby
 Vagrant.configure("2") do |config|
   config.vm.provider :libvirt do |libvirt|
-    # Add libvirt watchdog device model i6300esb
+    # Add Libvirt watchdog device model i6300esb
     libvirt.watchdog :model => 'i6300esb', :action => 'reset'
   end
 end
@@ -1002,7 +1089,7 @@ running Microsoft Windows.
 You can specify HyperV features via `libvirt.hyperv_feature`. Available
 options are listed below. Note that both options are required:
 
-* `name` - The name of the feature Hypervisor feature (see libvirt doc)
+* `name` - The name of the feature Hypervisor feature (see Libvirt doc)
 * `state` - The state for this feature which can be either `on` or `off`.
 
 ```ruby
@@ -1021,10 +1108,10 @@ end
 You can specify CPU feature policies via `libvirt.cpu_feature`. Available
 options are listed below. Note that both options are required:
 
-* `name` - The name of the feature for the chosen CPU (see libvirts
+* `name` - The name of the feature for the chosen CPU (see Libvirt's
   `cpu_map.xml`)
 * `policy` - The policy for this feature (one of `force`, `require`,
-  `optional`, `disable` and `forbid` - see libvirt documentation)
+  `optional`, `disable` and `forbid` - see Libvirt documentation)
 
 ```ruby
 Vagrant.configure("2") do |config|
@@ -1057,30 +1144,6 @@ Vagrant.configure("2") do |config|
   end
 end
 ```
-## USB device passthrough
-
-You can specify multiple USB devices to passthrough to the VM via
-`libvirt.usb`. The device can be specified by the following options:
-
-* `bus` - The USB bus ID, e.g. "1"
-* `device` - The USB device ID, e.g. "2"
-* `vendor` - The USB devices vendor ID (VID), e.g. "0x1234"
-* `product` - The USB devices product ID (PID), e.g. "0xabcd"
-
-At least one of these has to be specified, and `bus` and `device` may only be
-used together.
-
-The example values above match the device from the following output of `lsusb`:
-
-```
-Bus 001 Device 002: ID 1234:abcd Example device
-```
-
-Additionally, the following options can be used:
-
-* `startupPolicy` - Is passed through to libvirt and controls if the device has
-  to exist.  libvirt currently allows the following values: "mandatory",
-  "requisite", "optional".
 
 ## No box and PXE boot
 
@@ -1203,12 +1266,19 @@ mounting them at boot.
 
 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.
 
-**SECURITY NOTE:** for remote libvirt, nfs synced folders requires a bridged
-public network interface and you must connect to libvirt via ssh.
+**SECURITY NOTE:** for remote Libvirt, nfs synced folders requires a bridged
+public network interface and you must connect to Libvirt via ssh.
 
 ## QEMU Session Support
 
-vagrant-libvirt supports using the QEMU session connection 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.
+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.
+
+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.
+
+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>`.
+```
+allow virbr0
+```
 
 An example configuration of a machine using the QEMU session connection:
 
@@ -1219,11 +1289,11 @@ Vagrant.configure("2") do |config|
     libvirt.qemu_use_session = true
     # URI of QEMU session connection, default is as below
     libvirt.uri = 'qemu:///session'
-    # URI of QEMU system connection, use to obtain IP address for management
+    # URI of QEMU system connection, use to obtain IP address for management, default is below
     libvirt.system_uri = 'qemu:///system'
-    # Path to store libvirt images for the virtual machine, default is as ~/.local/share/libvirt/images
+    # Path to store Libvirt images for the virtual machine, default is as ~/.local/share/libvirt/images
     libvirt.storage_pool_path = '/home/user/.local/share/libvirt/images'
-    # Management network device
+    # Management network device, default is below
     libvirt.management_network_device = 'virbr0'
   end
 
@@ -1284,7 +1354,7 @@ end
 
 For certain functionality to be available within a guest, a private
 communication channel must be established with the host. Two notable examples
-of this are the qemu guest agent, and the Spice/QXL graphics type.
+of this are the QEMU guest agent, and the Spice/QXL graphics type.
 
 Below is a simple example which exposes a virtio serial channel to the guest.
 Note: in a multi-VM environment, the channel would be created for all VMs.
@@ -1310,7 +1380,7 @@ end
 
 These settings can be specified on a per-VM basis, however the per-guest
 settings will OVERRIDE any global 'config' setting. In the following example,
-we create 3 VM with the following configuration:
+we create 3 VMs with the following configuration:
 
 * **master**: No channel settings specified, so we default to the provider
   setting of a single virtio guest agent channel.
@@ -1351,8 +1421,8 @@ Vagrant.configure(2) do |config|
 end
 ```
 
-## Custom command line arguments
-You can also specify multiple qemuargs arguments for qemu-system
+## Custom command line arguments and environment variables
+You can also specify multiple qemuargs arguments or qemuenv environment variables for qemu-system
 
 * `value` - Value
 
@@ -1361,6 +1431,9 @@ Vagrant.configure("2") do |config|
   config.vm.provider :libvirt do |libvirt|
     libvirt.qemuargs :value => "-device"
     libvirt.qemuargs :value => "intel-iommu"
+    libvirt.qemuenv QEMU_AUDIO_DRV: 'pa'
+    libvirt.qemuenv QEMU_AUDIO_TIMER_PERIOD: '150'
+    libvirt.qemuenv QEMU_PA_SAMPLES: '1024', QEMU_PA_SERVER: '/run/user/1000/pulse/native'
   end
 end
 ```
@@ -1398,6 +1471,72 @@ $ cd packer-qemu-templates
 $ packer build ubuntu-14.04-server-amd64-vagrant.json
 ```
 
+## Package Box from VM
+
+vagrant-libvirt has native support for [`vagrant
+package`](https://www.vagrantup.com/docs/cli/package.html) via
+libguestfs [virt-sysprep](http://libguestfs.org/virt-sysprep.1.html).
+virt-sysprep operations can be customized via the
+`VAGRANT_LIBVIRT_VIRT_SYSPREP_OPERATIONS` environment variable; see the
+[upstream
+documentation](http://libguestfs.org/virt-sysprep.1.html#operations) for
+further details especially on default sysprep operations enabled for
+your system.
+
+Options to the virt-sysprep command call can be passed via
+`VAGRANT_LIBVIRT_VIRT_SYSPREP_OPTIONS` environment variable.
+
+```shell
+$ export VAGRANT_LIBVIRT_VIRT_SYSPREP_OPTIONS="--delete /etc/hostname"
+$ vagrant package
+```
+
+For example, on Chef [bento](https://github.com/chef/bento) VMs that
+require SSH hostkeys already set (e.g. bento/debian-7) as well as leave
+existing LVM UUIDs untouched (e.g. bento/ubuntu-18.04), these can be
+packaged into vagrant-libvirt boxes like so:
+
+```shell
+$ export VAGRANT_LIBVIRT_VIRT_SYSPREP_OPERATIONS="defaults,-ssh-userdir,-ssh-hostkeys,-lvm-uuids"
+$ vagrant package
+```
+
+## Troubleshooting VMs
+
+The first step for troubleshooting a VM image that appears to not boot correctly,
+or hangs waiting to get an IP, is to check it with a VNC viewer. A key thing
+to remember is that if the VM doesn't get an IP, then vagrant can't communicate
+with it to configure anything, so a problem at this stage is likely to come from
+the VM, but we'll outline the tools and common problems to help you troubleshoot
+that.
+
+By default, when you create a new VM, a vnc server will listen on `127.0.0.1` on
+port `TCP5900`. If you connect with a vnc viewer you can see the boot process. If
+your VM isn't listening on `5900` by default, you can use `virsh dumpxml` to find
+out which port it's listening on, or can configure it with `graphics_port` and
+`graphics_ip` (see 'Domain Specific Options' above).
+
+Note: Connecting with the console (`virsh console`) requires additional config,
+so some VMs may not show anything on the console at all, instead displaying it in
+the VNC console. The issue with the text console is that you also need to build the
+image used to tell the kernel to output to the console during boot, and typically
+most do not have this built in.
+
+Problems we've seen in the past include:
+- Forgetting to remove `/etc/udev/rules.d/70-persistent-net.rules` before packaging
+the VM
+- VMs expecting a specific disk device to be connected
+
+If you're still confused, check the Github Issues for this repo for anything that
+looks similar to your problem.
+
+[Github Issue #1032](https://github.com/vagrant-libvirt/vagrant-libvirt/issues/1032)
+contains some historical troubleshooting for VMs that appeared to hang.
+
+Did you hit a problem that you'd like to note here to save time in the future?
+Please do!
+
+
 ## Development
 
 To work on the `vagrant-libvirt` plugin, clone this repository out, and use
@@ -1440,3 +1579,8 @@ $ bundle exec vagrant up --provider=libvirt
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+
+<!--
+ # styling for TOC
+ vim: expandtab shiftwidth=2
+-->