From 24c86d459c1bbc29dc34267a226522e0f2bf6a1c Mon Sep 17 00:00:00 2001 From: PROTechThor Date: Sat, 10 Oct 2020 11:02:41 +0100 Subject: [PATCH 1/5] Add VM Troubleshooting --- doc.md | 10 ++- .../troubleshooting/remove-vm-manually.md | 36 ---------- .../managing-vm-kernel.md | 7 +- user/managing-os/debian/debian.md | 12 +--- user/troubleshooting/vm-troubleshooting.md | 70 +++++++++++++++++++ 5 files changed, 79 insertions(+), 56 deletions(-) delete mode 100644 external/troubleshooting/remove-vm-manually.md create mode 100644 user/troubleshooting/vm-troubleshooting.md diff --git a/doc.md b/doc.md index df16c6ed..9e3600e5 100644 --- a/doc.md +++ b/doc.md @@ -135,13 +135,19 @@ Core documentation for Qubes users. * [Making Any File Persistent Using `bind-dirs`](/doc/bind-dirs/) * [GUI Configuration](/doc/gui-configuration/) * [Resizing Disk Images](/doc/resize-disk-image/) - * [Troubleshooting UEFI](/doc/uefi-troubleshooting/) * [Troubleshooting Newer Hardware](/doc/newer-hardware-troubleshooting/) * [Mounting and Decrypting Qubes Partitions from Outside Qubes](/doc/mount-from-other-os/) * [KDE](/doc/kde/) * [i3 Window Manager](/doc/i3/) * [awesome Window Manager](/doc/awesome/) +### Troubleshooting + + * [Installation Troubleshooting](/doc/installation-troubleshooting/) + * [UEFI Troubleshooting](/doc/uefi-troubleshooting/) + * [Suspend/Resume Troubleshooting](/doc/suspend-resume-troubleshooting/) + * [VM Troubleshooting](/doc/vm-troubleshooting/) + ### Reference Pages * [Command-line Tools](/doc/tools/) @@ -294,8 +300,6 @@ Unofficial, third-party documentation from the Qubes community and others. * [Lenovo ThinkPad Troubleshooting](/doc/thinkpad-troubleshooting/) * [Apple MacBook Troubleshooting](/doc/macbook-troubleshooting/) * [Getting Sony Vaio Z laptop to work with Qubes](/doc/sony-vaio-tinkering/) - * [Fixing wireless on suspend & resume](/doc/wireless-troubleshooting/) - * [How to remove VMs manually](/doc/remove-vm-manually/) * [Intel Integrated Graphics Troubleshooting](/doc/intel-igfx-troubleshooting/) ### Building Guides diff --git a/external/troubleshooting/remove-vm-manually.md b/external/troubleshooting/remove-vm-manually.md deleted file mode 100644 index fbc1c145..00000000 --- a/external/troubleshooting/remove-vm-manually.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -layout: doc -title: How to Remove VMs Manually -permalink: /doc/remove-vm-manually/ ---- - -How to Remove VMs Manually -========================== - -How to Remove a TemplateVM Manually ------------------------------------ - -Try the [normal method] before resorting to this. -All of the following commands should be executed in a dom0 terminal. - -When a template is marked as 'installed by package manager', but cannot be uninstalled there, trying to uninstall manually will result in the error "ERROR: VM installed by package manager: template-vm-name". Do as follows to be able to uninstall the template: - -1. Check the state of `installed_by_rpm` - - $ qvm-prefs template-vm-name - -2. If `installed_by_rpm - True]`, mark the template as not installed by package manager - - $ qvm-prefs template-vm-name installed_by_rpm false - -3. Re-check the state of `installed_by_rpm` - -- If `installed_by_rpm - False`, remove the template like you would a regular qube: - - $ qvm-remove template-vm-name - -- If `installed_by_rpm` remains `True`, reboot your computer to bring qubes.xml in sync with qubesd, and try again to remove the template. - - -[normal method]: /doc/templates/#uninstalling - diff --git a/user/advanced-configuration/managing-vm-kernel.md b/user/advanced-configuration/managing-vm-kernel.md index 42dbd75d..c8948b37 100644 --- a/user/advanced-configuration/managing-vm-kernel.md +++ b/user/advanced-configuration/managing-vm-kernel.md @@ -355,12 +355,7 @@ The output should look like this: #### Troubleshooting -In case of problems, you can access the VM console using `qvm-console-dispvm VMNAME` in dom0, then access the GRUB menu. -You need to call it just after starting the VM (until `GRUB_TIMEOUT` expires); for example, in a separate dom0 terminal window. - -In any case you can later access the VM's logs (especially the VM console log `/var/log/xen/console/guest-VMNAME.log`). - -You can always set the kernel back to some dom0-provided value to fix a VM kernel installation. +In case of problems, visit the [VM Troubleshooting guide](/doc/vm-troubleshooting/#vm-kernel-troubleshooting) to learn how to access the VM console, view logs and fix a VM kernel installation. [dom0-kernel-upgrade]: /doc/software-update-dom0/#kernel-upgrade diff --git a/user/managing-os/debian/debian.md b/user/managing-os/debian/debian.md index 236c2d8e..a688e87e 100644 --- a/user/managing-os/debian/debian.md +++ b/user/managing-os/debian/debian.md @@ -99,17 +99,7 @@ The lesson is that you should carefully look at what is being installed to your ### Package installation errors in Qubes 4.0 -By default, templates in 4.0 only have a loopback interface. - -Some packages will throw an error on installation in this situation. -For example, Samba expects to be configured using a network interface post installation. - -One solution is to add a dummy interface to allow the package to install correctly: - - ip link add d0 type dummy - ip addr add 192.168.0.1/24 dev d0 - ip link set d0 up - +If some packages throw installation errors, see [this guide.](/doc/vm-troubleshooting/#fixing-package-installation-errors) [TemplateVM]: /doc/templates/ [Minimal TemplateVMs]: /doc/templates/minimal/ diff --git a/user/troubleshooting/vm-troubleshooting.md b/user/troubleshooting/vm-troubleshooting.md new file mode 100644 index 00000000..ece7b968 --- /dev/null +++ b/user/troubleshooting/vm-troubleshooting.md @@ -0,0 +1,70 @@ +--- +layout: doc +title: Suspend/Resume Troubleshooting +permalink: /doc/vm-troubleshooting/ +redirect_from: +- /doc/remove-vm-manually/ +--- + +# VM troubleshooting # + +## VM Kernel troubleshooting ## + +In case of problems, you can access the VM console using `qvm-console-dispvm VMNAME` in dom0, then access the GRUB menu. +You need to call it just after starting the VM (until `GRUB_TIMEOUT` expires); for example, in a separate dom0 terminal window. + +In any case you can later access the VM's logs (especially the VM console log `/var/log/xen/console/guest-VMNAME.log`). + +You can always set the kernel back to some dom0-provided value to fix a VM kernel installation. + +## Qubes starts, but no VMs load ## + +This issue may occur if a dom0 update is interrupted halfway through and/or a hard power off is done without shutting down Qubes, which results in files getting corrupted. +In this case, the best fix is to reinstall Qubes and restore your files from a backup. +Even if you have not backed up data in a while, you should be able to mount the volumes to pull data from them. + +## Can not uninstall a VM / “ERROR: VM installed by package manager: template-vm-name” + +Try the [normal method] before resorting to this method to remove a VM manually. +All of the following commands should be executed in a dom0 terminal. + +When a template is marked as 'installed by package manager', but cannot be uninstalled there, trying to uninstall manually will result in the error "ERROR: VM installed by package manager: template-vm-name". Do as follows to be able to uninstall the template: + +1. Check the state of `installed_by_rpm` + + $ qvm-prefs template-vm-name + +2. If `installed_by_rpm - True]`, mark the template as not installed by package manager + + $ qvm-prefs template-vm-name installed_by_rpm false + +3. Re-check the state of `installed_by_rpm` + +- If `installed_by_rpm - False`, remove the template like you would a regular qube: + + $ qvm-remove template-vm-name + +- If `installed_by_rpm` remains `True`, reboot your computer to bring qubes.xml in sync with qubesd, and try again to remove the template. + + +[normal method]: /doc/templates/#uninstalling + + +## Fixing package installation errors ## + +By default, templates in 4.0 only have a loopback interface. + +Some packages will throw an error on installation in this situation. +For example, Samba expects to be configured using a network interface post installation. + +One solution is to add a dummy interface to allow the package to install correctly: + + ip link add d0 type dummy + ip addr add 192.168.0.1/24 dev d0 + ip link set d0 up + +## "Cannot connect to qrexec agent" error ## + +If you face this error when starting a VM, it may be due to too little initial memory. +A solution is to increase the initial memory from 200MB to 400MB by navigating to VM settings » Advanced » Initial memory. + From 747055c29436a0fc1028414028e89d9c10ac875e Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Sat, 10 Oct 2020 18:10:19 +0100 Subject: [PATCH 2/5] Minor changes --- user/troubleshooting/vm-troubleshooting.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/user/troubleshooting/vm-troubleshooting.md b/user/troubleshooting/vm-troubleshooting.md index ece7b968..5fbbf2a4 100644 --- a/user/troubleshooting/vm-troubleshooting.md +++ b/user/troubleshooting/vm-troubleshooting.md @@ -1,6 +1,6 @@ --- layout: doc -title: Suspend/Resume Troubleshooting +title: VM Troubleshooting permalink: /doc/vm-troubleshooting/ redirect_from: - /doc/remove-vm-manually/ @@ -10,6 +10,8 @@ redirect_from: ## VM Kernel troubleshooting ## +This troubleshoot applies to the non-default kernel choice described in the [Managing VM docs](https://www.qubes-os.org/doc/managing-vm-kernel/#using-kernel-installed-in-the-vm). + In case of problems, you can access the VM console using `qvm-console-dispvm VMNAME` in dom0, then access the GRUB menu. You need to call it just after starting the VM (until `GRUB_TIMEOUT` expires); for example, in a separate dom0 terminal window. @@ -19,9 +21,9 @@ You can always set the kernel back to some dom0-provided value to fix a VM kerne ## Qubes starts, but no VMs load ## -This issue may occur if a dom0 update is interrupted halfway through and/or a hard power off is done without shutting down Qubes, which results in files getting corrupted. -In this case, the best fix is to reinstall Qubes and restore your files from a backup. -Even if you have not backed up data in a while, you should be able to mount the volumes to pull data from them. +First, try to start a particular VM, check any failure message and direct further steps based on that. + +This issue has been seen to occur if a dom0 update is interrupted halfway through and/or a hard power off is done without shutting down Qubes, which results in files getting corrupted. ## Can not uninstall a VM / “ERROR: VM installed by package manager: template-vm-name” @@ -65,6 +67,7 @@ One solution is to add a dummy interface to allow the package to install correct ## "Cannot connect to qrexec agent" error ## -If you face this error when starting a VM, it may be due to too little initial memory. -A solution is to increase the initial memory from 200MB to 400MB by navigating to VM settings » Advanced » Initial memory. +If you face this error when starting a VM, look into the VM logs at `/var/log/xen/console/guest-VMNAME.log`. +Common reasons that may be revealed are: too low memory, corrupted files or a VM crash on startup. +If the error occurs as a result of too little initial memory, increase the initial memory from 200MB to 400MB by navigating to VM settings » Advanced » Initial memory. From ad67bdef1921fa1bca4b8f13e6e407b58008a214 Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Sat, 10 Oct 2020 18:25:17 +0100 Subject: [PATCH 3/5] Rearrange section links --- doc.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc.md b/doc.md index 9e3600e5..787379cc 100644 --- a/doc.md +++ b/doc.md @@ -135,6 +135,7 @@ Core documentation for Qubes users. * [Making Any File Persistent Using `bind-dirs`](/doc/bind-dirs/) * [GUI Configuration](/doc/gui-configuration/) * [Resizing Disk Images](/doc/resize-disk-image/) + * [Troubleshooting UEFI](/doc/uefi-troubleshooting/) * [Troubleshooting Newer Hardware](/doc/newer-hardware-troubleshooting/) * [Mounting and Decrypting Qubes Partitions from Outside Qubes](/doc/mount-from-other-os/) * [KDE](/doc/kde/) @@ -143,9 +144,6 @@ Core documentation for Qubes users. ### Troubleshooting - * [Installation Troubleshooting](/doc/installation-troubleshooting/) - * [UEFI Troubleshooting](/doc/uefi-troubleshooting/) - * [Suspend/Resume Troubleshooting](/doc/suspend-resume-troubleshooting/) * [VM Troubleshooting](/doc/vm-troubleshooting/) ### Reference Pages @@ -300,6 +298,7 @@ Unofficial, third-party documentation from the Qubes community and others. * [Lenovo ThinkPad Troubleshooting](/doc/thinkpad-troubleshooting/) * [Apple MacBook Troubleshooting](/doc/macbook-troubleshooting/) * [Getting Sony Vaio Z laptop to work with Qubes](/doc/sony-vaio-tinkering/) + * [Fixing wireless on suspend & resume](/doc/wireless-troubleshooting/) * [Intel Integrated Graphics Troubleshooting](/doc/intel-igfx-troubleshooting/) ### Building Guides From e5c73616f9b55aad73aa146e60704938d9fc90c5 Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Mon, 12 Oct 2020 05:25:34 +0100 Subject: [PATCH 4/5] Remove space --- doc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc.md b/doc.md index 787379cc..cfab61f9 100644 --- a/doc.md +++ b/doc.md @@ -135,7 +135,7 @@ Core documentation for Qubes users. * [Making Any File Persistent Using `bind-dirs`](/doc/bind-dirs/) * [GUI Configuration](/doc/gui-configuration/) * [Resizing Disk Images](/doc/resize-disk-image/) - * [Troubleshooting UEFI](/doc/uefi-troubleshooting/) + * [Troubleshooting UEFI](/doc/uefi-troubleshooting/) * [Troubleshooting Newer Hardware](/doc/newer-hardware-troubleshooting/) * [Mounting and Decrypting Qubes Partitions from Outside Qubes](/doc/mount-from-other-os/) * [KDE](/doc/kde/) From aaf4b691f4fecda2a9108d97f9ea2597a8359cf4 Mon Sep 17 00:00:00 2001 From: Enjeck Cleopatra <32180937+PROTechThor@users.noreply.github.com> Date: Mon, 19 Oct 2020 14:09:42 +0100 Subject: [PATCH 5/5] Delete wireless-troubleshooting.md All the content here is already available at Suspend-resume-troubleshooting.md. Plus, this page should redirect to /doc/suspend-resume-troubleshooting --- .../wireless-troubleshooting.md | 121 ------------------ 1 file changed, 121 deletions(-) delete mode 100644 user/troubleshooting/wireless-troubleshooting.md diff --git a/user/troubleshooting/wireless-troubleshooting.md b/user/troubleshooting/wireless-troubleshooting.md deleted file mode 100644 index 9c8ea33d..00000000 --- a/user/troubleshooting/wireless-troubleshooting.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -layout: doc -title: Wireless Troubleshooting -permalink: /doc/wireless-troubleshooting/ -redirect_from: -- /en/doc/wireless-troubleshooting/ ---- - -Wireless Troubleshooting Guide -============================== - -These instructions may help with suspend/resume issues for more devices than just wireless cards, that is just the (unfortunately not uncommon) example used here. - -Resetting wireless cards by reloading drivers ---------------------------------------------- - -If your wireless card works, but after suspending and resuming your computer, the Network-Manager applet just says "Device not ready", then try un-loading and re-loading the driver. - -### Determining your wireless card driver ### - -First, determine which kernel module corresponds to your wireless card. There are several ways to do this. - -The easiest is via the output of `lspci -k` in your sys-net VM: - -~~~ -[user@sys-net ~]$ lspci -k -00:00.0 Network controller: Intel Corporation Wireless 8260 (rev 3a) - Subsystem: Intel Corporation Device 0130 - Kernel driver in use: iwlwifi - Kernel modules: iwlwifi -~~~ - -Here we see that the machine in question has an Intel wireless card, being used by the `iwlwifi` kernel module. - - -### Checking logs for relevant messages ### - -View the output of `dmesg` in sys-net, and check if you see a bunch of wireless related errors. Depending on your hardware, they may look like the following (or not): - -~~~ -iwlwifi 0000:00:00.0: loaded firmware version 16.242414.0 op_mode iwlmvm -iwlwifi 0000:00:00.0: Detected Intel(R) Dual Band Wireless AC 8260, REV=0x208 -... -IPv6: ADDRCONF(NETDEV_UP): wlp0s0: link is not ready -iwlwifi 0000:00:00.0: L1 Enabled - LTR Enabled -iwlwifi 0000:00:00.0: L1 Enabled - LTR Enabled -iwlwifi 0000:00:00.0: Failed to load firmware chunk! -iwlwifi 0000:00:00.0: Could not load the [0] uCode section -iwlwifi 0000:00:00.0: Failed to start INIT ucode: -110 -iwlwifi 0000:00:00.0: Failed to run INIT ucode: -110 -... -iwlwifi 0000:00:00.0: Direct firmware load for iwlwifi-8000C-18.ucode failed with error -2 -~~~ - -### Seeing what modules you have loaded ### - -You can check which drivers are currently loaded with `lsmod`, and view details about a module with `modinfo `. - -For example, we list what modules we have loaded: - -~~~ -[user@sys-net ~]$ lsmod -Module Size Used by -iwlmvm 315392 0 -iwlwifi 155648 1 iwlmvm -mac80211 708608 1 iwlmvm -cfg80211 557056 3 iwlwifi,mac80211,iwlmvm -... -~~~ - -and check one: - -~~~ -[user@sys-net ~]$ modinfo iwlmvm | grep -E '^(description|author|depends):' -author: Copyright(c) 2003- 2015 Intel Corporation -description: The new Intel(R) wireless AGN driver for Linux -depends: iwlwifi,mac80211,cfg80211 -~~~ - -Hey, it's our wireless driver! - -Now, check if reloading the module makes wireless work again: - -~~~ -[user@sys-net ~]$ sudo rmmod iwlmvm -[user@sys-net ~]$ sudo modprobe iwlmvm -~~~ - -and try reconnecting to a network that is known to work. - -If that is successful, see below about having Qubes automatically reload the driver for you. If not, try also reloading some dependent modules, in our example we must also reload iwlwifi: - -~~~ -[user@sys-net ~]$ modinfo iwlwifi | grep -E '^(description|author|depends):' -author: Copyright(c) 2003- 2015 Intel Corporation -description: Intel(R) Wireless WiFi driver for Linux -depends: cfg80211 -~~~ - -~~~ -[user@sys-net ~]$ sudo rmmod iwlmvm -[user@sys-net ~]$ sudo rmmod iwlwifi -[user@sys-net ~]$ sudo modprobe iwlwifi # note the reverse order of loading/unloading -[user@sys-net ~]$ sudo modprobe iwlmvm -~~~ - -Automatically reloading drivers on suspend/resume -------------------------------------------------- - -If reloading the driver (which resets the hardware into a known-state) resolves your issue when done manually, you can have Qubes automatically un/reload them on suspend & resume by listing the relevant modules in `/rw/config/suspend-module-blacklist`. - -In the above example, it would look like this: - -~~~ -[user@sys-net config]$ cat /rw/config/suspend-module-blacklist -# You can list here modules you want to be unloaded before going to sleep. This -# file is used only if the VM has any PCI device assigned. Modules will be -# automatically loaded after resume. -iwlmvm -iwlwifi -~~~