Update installation docs (#1650)

Include CentOS 9 Stream and CentOS 8 Stream, in addition to updating the
openSUSE instructions to cover upstream vagrant package installation.

Closes: #1429
Closes: #1537

docs/_includes/patch-vagrant-install.html

@@ -16,7 +16,8 @@
   ```bash
   mkdir patches
   pushd patches
-{%- if include.distro == "centos" or include.distro == "rhel" %}
+{%- case include.distro %}
+{%-   when "centos" %}
 
   [[ ! -d centos-git-common ]] && git clone https://git.centos.org/centos-git-common
   export PATH=$(readlink -f ./centos-git-common):$PATH
@@ -26,25 +27,38 @@
 {%-   else %}
 
   mkdir libssh
-{%- endif %}
+{%- endcase %}
   pushd libssh
+{%- case include.distro %}
+{%-   when "fedora" %}
   nvr=$(rpm -q --queryformat "libssh-%{version}-%{release}" libssh)
   nv=$(rpm -q --queryformat "libssh-%{version}" libssh)
-{%- if include.distro == "fedora" %}
   dnf download --source libssh
   rpm2cpio ${nvr}.src.rpm | cpio -imdV
   rm -rf ${nv}
   tar xf ${nv}.tar.*z
-{%- elsif include.distro == "centos" %}
+{%-   when "centos" %}
+  nvr=$(rpm -q --queryformat "libssh-%{version}-%{release}" libssh)
+  nv=$(rpm -q --queryformat "libssh-%{version}" libssh)
   git checkout $(git tag -l | grep "${nvr}\$" | tail -n1)
   into_srpm.sh -d c8s
   pushd BUILD
   tar xf ../SOURCES/${nv}.tar.*z
-{%- elsif include.distro == "opensuse" %}
+{%-   when "opensuse" %}
+  nvr=$(rpm -q --queryformat "libssh-%{version}-%{release}" libssh4)
+  nv=$(rpm -q --queryformat "libssh-%{version}" libssh4)
+
+  repository=$(zypper --quiet --no-refresh --xmlout search --type srcpackage --match-exact --details libssh | xpath -q -e 'string(//solvable/@repository)')
+  url=$(zypper --quiet --xmlout repos | xpath -q -e "//repo[@name='${repository}']/url/text()")
+
+  wget ${url}/src/${nvr}.src.rpm
+  rpm2cpio ${nvr}.src.rpm | cpio -imdV
+  rm -rf ${nv}
+  tar xf ${nv}.tar.*z
 {%-   else %}
 
   *******Missing the correct distro for patch commands********
-{%- endif %}
+{%- endcase %}
 
   mkdir libssh-build
   pushd libssh-build
@@ -58,29 +72,42 @@
   popd
 {%- endif %}
 
-{%- if include.distro == "centos" or include.distro == "rhel" %}
+{%- case include.distro %}
+{%-   when "centos" %}
 
   git clone https://git.centos.org/rpms/krb5
 {%-   else %}
 
   mkdir krb5
-{%- endif %}
+{%- endcase %}
   pushd krb5
+{%- case include.distro %}
+{%-   when "fedora" %}
   nvr=$(rpm -q --queryformat "krb5-%{version}-%{release}" krb5-libs)
   nv=$(rpm -q --queryformat "krb5-%{version}" krb5-libs)
-{%- if include.distro == "fedora" %}
   dnf download --source krb5-libs
   rpm2cpio ${nvr}.src.rpm | cpio -imdV
   tar xf ${nv}.tar.*z
-{%- elsif include.distro == "centos" %}
+{%-   when "centos" %}
+  nvr=$(rpm -q --queryformat "krb5-%{version}-%{release}" krb5-libs)
+  nv=$(rpm -q --queryformat "krb5-%{version}" krb5-libs)
   git checkout $(git tag -l | grep "${nvr}\$" | tail -n1)
   into_srpm.sh -d c8s
   pushd BUILD
   tar xf ../SOURCES/${nv}.tar.*z
-{%- elsif include.distro == "opensuse" %}
+{%-   when "opensuse" %}
+  nvr=$(rpm -q --queryformat "krb5-%{version}-%{release}\n" krb5 | uniq)
+  nv=$(rpm -q --queryformat "krb5-%{version}\n" krb5 | uniq)
+  repository=$(zypper --quiet --no-refresh --xmlout search --type srcpackage --match-exact --details krb5 | xpath -q -e 'string(//solvable/@repository)')
+  url=$(zypper --quiet --xmlout repos | xpath -q -e "//repo[@name='${repository}']/url/text()")
+
+  [[ ! -e ${nvr}.src.rpm ]] && wget ${url}/src/${nvr}.src.rpm
+  rpm2cpio ${nvr}.src.rpm | cpio -imdV
+  rm -rf ${nv}
+  tar xf ${nv}.tar.*z
 {%-   else %}
   *******Missing the correct distro for patch commands********
-{%- endif %}
+{%- endcase %}
 
   pushd ${nv}/src
   ./configure

docs/_includes/upstream-vagrant-install.html

@@ -6,25 +6,33 @@ chmod a+x ./install.bash
 ./install.bash
 ```
 * Alternatively install vagrant following [https://www.vagrantup.com/downloads](https://www.vagrantup.com/downloads):
-{% if include.distro == "debian" or include.distro == "ubuntu" -%}
+{% case include.distro -%}
+{%   when "debian", "ubuntu" -%}
 ```shell
 curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo tee /usr/share/keyrings/hashicorp-archive-keyring.asc
 echo "deb [ signed-by=/usr/share/keyrings/hashicorp-archive-keyring.asc ] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
 sudo apt-get update && sudo apt-get install vagrant
 ```
-{% elsif include.distro == "fedora" -%}
+{%   when "fedora" -%}
 ```shell
 sudo dnf install -y dnf-plugins-core
 sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/fedora/hashicorp.repo
 sudo dnf -y install vagrant
 ```
-{% elsif include.distro == "centos" or include.distro == "rhel" -%}
+{%   when "centos", "centos8" -%}
+```shell
+sudo dnf install -y dnf-plugins-core
+sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
+sudo dnf -y install vagrant
+```
+{%   when "centos6", "centos7" -%}
 ```shell
 sudo yum install -y yum-utils
 sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
 sudo yum -y install vagrant
 ```
-{% elsif include.distro == "opensuse" %}
+{%   when "opensuse" %}
+
   As there is no upstream repository this will not be kept up to date automatically.
   {: .warn }
 
@@ -39,4 +47,4 @@ sudo yum -y install vagrant
   ```
 {%   else -%}
 Missing the correct distro for vagrant install in site generation
-{% endif -%}
+{% endcase -%}

docs/_upstream.yml

@@ -0,0 +1 @@
+repository_nwo: vagrant-libvirt/vagrant-libvirt

docs/assets/js/color_scheme.js

@@ -0,0 +1,63 @@
+function setTheme(theme) {
+    if (theme === "dark") {
+        jtd.setTheme('dark');
+        document.documentElement.setAttribute('data-theme', 'dark');
+        window.localStorage.setItem('theme', 'dark');
+    } else {
+        jtd.setTheme('light');
+        document.documentElement.setAttribute('data-theme', 'light');
+        window.localStorage.setItem('theme', 'light');
+    }
+}
+
+if (window.matchMedia) {
+    window.matchMedia('(prefers-color-scheme: dark)')
+        .addEventListener('change', event => {
+            if (event.matches) {
+                setTheme('dark');
+            } else {
+                setTheme('light');
+            }
+        });
+}
+
+function getUserThemePreference() {
+  return localStorage.getItem('theme') || getComputedStyle(document.documentElement).getPropertyValue('content') || 'system';
+}
+
+function saveUserThemePreference(preference) {
+  localStorage.setItem('theme', preference);
+}
+
+function getAppliedMode(preference) {
+  if (preference === 'dark') {
+    return 'dark';
+  }
+  if (preference === 'light') {
+    return 'light';
+  }
+  // system
+  if (matchMedia('(prefers-color-scheme: dark)').matches) {
+    return 'dark';
+  }
+  return 'light';
+}
+
+const colorScheme = document.querySelector('meta[name="color-scheme"]');
+function setAppliedMode(mode) {
+  setTheme(mode);
+}
+
+function modeSwitcher() {
+    let currentMode = document.documentElement.getAttribute('data-theme');
+    if (currentMode === "dark") {
+        setAppliedMode('light');
+        document.getElementById("theme-toggle").innerHTML = "Dark Mode";
+      } else {
+        setAppliedMode('dark');
+        document.getElementById("theme-toggle").innerHTML = "Light Mode";
+    }
+}
+
+let theme = getUserThemePreference();
+setAppliedMode(getAppliedMode(theme));

docs/index.markdown

@@ -36,18 +36,21 @@ See [Requirements]({{ '/installation/#requirements' | relative_url }}) for guide
    * Ubuntu
 
    ```
+   sudo apt-get purge vagrant-libvirt
+   sudo apt-mark hold vagrant-libvirt
    sudo apt-get update && \
-       sudo apt install -y qemu libvirt-daemon-system libvirt-clients \
-           ebtables dnsmasq-base libguestfs-tools
-   sudo apt install -y --no-install-recommends vagrant ruby-fog-libvirt
+       sudo apt-get install -y qemu libvirt-daemon-system ebtables libguestfs-tools \
+           vagrant ruby-fog-libvirt
    ```
 
    * Fedora
 
    ```
-   vagrant_libvirt_deps=($(sudo dnf repoquery --depends vagrant-libvirt 2>/dev/null | cut -d' ' -f1))
-   dependencies=$(sudo dnf repoquery --qf "%{name}" ${vagrant_libvirt_deps[@]/#/--whatprovides })
-   sudo dnf install --assumeyes --setopt=install_weak_deps=False @virtualization ${dependencies}
+   sudo dnf remove vagrant-libvirt
+   sudo sed -i \
+       '/^\(exclude=.*\)/ {/vagrant-libvirt/! s//\1 vagrant-libvirt/;:a;n;ba;q}; $aexclude=vagrant-libvirt' \
+       /etc/dnf/dnf.conf
+   sudo dnf install --assumeyes @virtualization vagrant rubygem-fog-libvirt
    ```
 2. Install the latest release of vagrant-libvirt
 ```

docs/installation.markdown

@@ -237,6 +237,8 @@ rather than exclude all versions.
   ```shell
   sudo dnf install --assumeyes libvirt libguestfs-tools \
       gcc libvirt-devel libxml2-devel make ruby-devel
+  # additional deps to rebuild libraries in upstream vagrant package.
+  sudo dnf install --assumeyes byacc cmake gcc-c++ wget zlib-devel
   ```
 
   Before installing the plugin it is necessary to compile some libraries to replace those
@@ -265,21 +267,35 @@ vagrant plugin install vagrant-libvirt
 
 ### CentOS
 
-#### CentOS 8
+#### CentOS 9 Stream
 
 {% include upstream-vagrant-install.html distro="centos" -%}
+  Subsequent install remaining dependencies and plugin
+
+  ```shell
+  sudo dnf config-manager --set-enabled crb
+  sudo dnf install -y '@Virtualization Hypervisor' '@Virtualization Tools' \
+      '@Development Tools' 'libvirt-devel'
+  vagrant plugin install vagrant-libvirt
+  ```
+
+#### CentOS 8 (and Stream)
+
+{% include upstream-vagrant-install.html distro="centos8" -%}
   Subsequently install remaining dependencies:
 
   ```shell
   sudo dnf install --assumeyes libvirt libguestfs-tools \
-      gcc libvirt-devel libxml2-devel make ruby-devel
+      gcc libvirt-devel libxml2-devel make pkgconf-pkg-config ruby-devel
+  # additional deps to rebuild libraries in upstream vagrant package.
+  sudo dnf install --assumeyes byacc cmake gcc-c++ rpm-build wget zlib-devel
   ```
 
   Before installing the plugin it is necessary to compile some libraries to replace those
   shipped with the upstream vagrant to prevent the following errors from appearing when
   vagrant attempts to use vagrant-libvirt on recent CentOS releases.
 
-{% include patch-vagrant-install.html distro="fedora" %}
+{% include patch-vagrant-install.html distro="centos" %}
 
   Finally install the plugin:
   ```
@@ -288,7 +304,7 @@ vagrant plugin install vagrant-libvirt
 
 #### CentOS 6 & 7
 
-{% include upstream-vagrant-install.html distro="centos" -%}
+{% include upstream-vagrant-install.html distro="centos6" -%}
 And subsequently install remaining dependencies and plugin:
 ```shell
 sudo yum install --assumeyes qemu qemu-kvm libvirt libguestfs-tools \
@@ -311,7 +327,28 @@ sudo zypper addlock vagrant-libvirt
 fog_libvirt_pkg="$(
     sudo zypper --terse -n --quiet search --provides "rubygem(fog-libvirt)" | \
     tail -n1 | cut -d' ' -f4)"
-sudo zypper install --no-confirm libvirt qemu-kvm libguestfs vagrant ${fog_libvirt_pkg}
+sudo zypper install --no-confirm libvirt qemu-kvm libguestfs polkit vagrant ${fog_libvirt_pkg}
+vagrant plugin install vagrant-libvirt
+```
+
+{% include upstream-vagrant-install.html distro="opensuse" -%}
+  Subsequently install remaining dependencies:
+
+  ```shell
+  sudo zypper install --no-confirm libvirt qemu-kvm libguestfs \
+      gcc make libvirt-devel polkit ruby-devel
+  # additional deps to rebuild libraries in upstream vagrant package.
+  sudo zypper install --no-confirm byacc cmake gcc-++ libssh4 perl-XML-XPath wget zlib-devel
+  ```
+
+  Before installing the plugin it is necessary to compile some libraries to replace those
+  shipped with the upstream vagrant to prevent the following errors from appearing when
+  vagrant attempts to use vagrant-libvirt on recent OpenSUSE Leap releases.
+
+{% include patch-vagrant-install.html distro="opensuse" %}
+
+  Finally install the plugin:
+  ```
   vagrant plugin install vagrant-libvirt
   ```
 

docs/packaging.markdown

@@ -0,0 +1,19 @@
+---
+title: Packaging
+nav_order: 6
+toc: true
+---
+
+Packaging can be somewhat difficult to get right due to some of the specific requirements of this provider and of unexpected default behaviour of distributions.
+The root cause of most issues is typically related to the management network requirement. That is this provider requires that any box has the
+DHCP enabled for the first network device attached.
+
+The most results where this requirement is not met are failure of the guest to get an IP address on boot or failure for SSH connections to be established.
+
+## No IP Address Detected
+
+This typically manifests with the following message appearing as part of a traceback
+
+_The specified wait_for timeout (2 seconds) was exceeded (Fog::Errors::TimeoutError)_
+
+

docs/troubleshooting.markdown

@@ -0,0 +1,41 @@
+---
+title: Troubleshooting
+nav_order: 7
+toc: true
+---
+
+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;
+
+ * Check the create domain details outputted to the console, or
+ * Use `virsh dumpxml` to find out which port it's listening on, or
+ * Explicitly configure it with `graphics_port` and `graphics_ip`
+   (see ['Domain Specific Options']({{ '/configuration#domain-specific-options' | relative_url }})).
+
+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!