From fddc9c32d68fa8f0b44119fcda1690baebe24ed8 Mon Sep 17 00:00:00 2001 From: Darragh Bailey Date: Wed, 2 Nov 2022 13:43:10 +0000 Subject: [PATCH] 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 | 59 +++++++++++++----- docs/_includes/upstream-vagrant-install.html | 20 +++++-- docs/_upstream.yml | 1 + docs/assets/js/color_scheme.js | 63 ++++++++++++++++++++ docs/index.markdown | 15 +++-- docs/installation.markdown | 47 +++++++++++++-- docs/packaging.markdown | 19 ++++++ docs/troubleshooting.markdown | 41 +++++++++++++ 8 files changed, 232 insertions(+), 33 deletions(-) create mode 100644 docs/_upstream.yml create mode 100644 docs/assets/js/color_scheme.js create mode 100644 docs/packaging.markdown create mode 100644 docs/troubleshooting.markdown diff --git a/docs/_includes/patch-vagrant-install.html b/docs/_includes/patch-vagrant-install.html index 8c8a447..63c9865 100644 --- a/docs/_includes/patch-vagrant-install.html +++ b/docs/_includes/patch-vagrant-install.html @@ -16,35 +16,49 @@ ```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 chmod a+x ./centos-git-common/*.sh git clone https://git.centos.org/rpms/libssh -{%- else %} +{%- 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" %} -{%- else %} +{%- 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 %} +{%- 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" %} -{%- else %} +{%- 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 diff --git a/docs/_includes/upstream-vagrant-install.html b/docs/_includes/upstream-vagrant-install.html index 28dd58a..04b13bc 100644 --- a/docs/_includes/upstream-vagrant-install.html +++ b/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 } @@ -37,6 +45,6 @@ sudo yum -y install vagrant https://releases.hashicorp.com/vagrant/${version}/vagrant_${version}_x86_64.rpm sudo zypper install --allow-unsigned-rpm --no-confirm vagrant.rpm ``` -{% else -%} +{% else -%} Missing the correct distro for vagrant install in site generation -{% endif -%} +{% endcase -%} diff --git a/docs/_upstream.yml b/docs/_upstream.yml new file mode 100644 index 0000000..52a24b7 --- /dev/null +++ b/docs/_upstream.yml @@ -0,0 +1 @@ +repository_nwo: vagrant-libvirt/vagrant-libvirt diff --git a/docs/assets/js/color_scheme.js b/docs/assets/js/color_scheme.js new file mode 100644 index 0000000..3715d90 --- /dev/null +++ b/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)); diff --git a/docs/index.markdown b/docs/index.markdown index a9cffcb..dfbe0c4 100644 --- a/docs/index.markdown +++ b/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 ``` diff --git a/docs/installation.markdown b/docs/installation.markdown index 8fe66f8..28ee6bf 100644 --- a/docs/installation.markdown +++ b/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,10 +327,31 @@ 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 + ``` + ### Arch Please read the related [ArchWiki](https://wiki.archlinux.org/index.php/Vagrant#vagrant-libvirt) page. diff --git a/docs/packaging.markdown b/docs/packaging.markdown new file mode 100644 index 0000000..8eacddc --- /dev/null +++ b/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)_ + + diff --git a/docs/troubleshooting.markdown b/docs/troubleshooting.markdown new file mode 100644 index 0000000..82eeddc --- /dev/null +++ b/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!