diff --git a/doc.md b/doc.md index fa6292a4..eba31efa 100644 --- a/doc.md +++ b/doc.md @@ -111,7 +111,6 @@ 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 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/) @@ -131,6 +130,7 @@ Core documentation for Qubes users. * [GUI Troubleshooting](/doc/gui-troubleshooting/) * [Media Troubleshooting](/doc/media-troubleshooting/) * [Firewall Troubleshooting](/doc/firewall/#firewall-troubleshooting) + * [Hardware Troubleshooting](/doc/hardware-troubleshooting/) * [VPN Troubleshooting](/doc/vpn-troubleshooting/) * [Update Troubleshooting](/doc/update-troubleshooting/) diff --git a/introduction/faq.md b/introduction/faq.md index 56b69ac4..f7369860 100644 --- a/introduction/faq.md +++ b/introduction/faq.md @@ -448,23 +448,7 @@ See [Update Troubleshooting](/doc/update-troubleshooting/#lost-internet-access-a ### My keyboard layout settings are not behaving correctly. What should I do? -The best approach is to choose the right keyboard layout during the installation process. -But if you want to change things afterwards, you can try this workaround. - -Assuming XFCE desktop: in `Q` → `System Tools` → `Keyboard` → `Layout`, leave the checkbox "`Use system defaults`" checked. Do not customize the keyboard layout here. - -Set the system-wide layout and options for `xorg` with the `localectl` command in `dom0`. You can use `localectl --help` as a starting point. - -Example: `localectl set-x11-keymap us dell ,qwerty compose:caps`. - -This generates the appropriate configuration in `/etc/X11/xorg.conf.d/00-keyboard.conf`. -This file is auto-generated. -Do not edit it by hand, unless you know what you are doing. - -Restarting `xorg` is required. -The most straightforward way is to reboot the system. - -More information in [this discussion][layout_discussion] and [this issue][layout_issue]. +See [Hardware Troubleshooting](/doc/hardware-troubleshooting/#keyboard-layout-settings-not-behaving-correctly). ### My dom0 and/or TemplateVM update stalls when attempting to update via the GUI tool. What should I do? @@ -755,8 +739,6 @@ There is also the unofficial [ansible-qubes toolkit][ansible]. [intro1]: https://en.wikibooks.org/wiki/Fedora_And_Red_Hat_System_Administration/Shell_Basics [intro2]: https://en.wikibooks.org/wiki/A_Quick_Introduction_to_Unix [intro3]: https://en.wikibooks.org/wiki/Bash_Shell_Scripting -[layout_discussion]: https://groups.google.com/d/topic/qubes-devel/d8ZQ_62asKI/discussion -[layout_issue]: https://github.com/QubesOS/qubes-issues/issues/1396 [LUKS]: https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup [Markdown]: /doc/doc-guidelines/#markdown-conventions [network]: /doc/networking/ diff --git a/user/advanced-configuration/newer-hardware-troubleshooting.md b/user/advanced-configuration/newer-hardware-troubleshooting.md deleted file mode 100644 index 4ed30ba8..00000000 --- a/user/advanced-configuration/newer-hardware-troubleshooting.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -layout: doc -title: Troubleshooting newer hardware -permalink: /doc/newer-hardware-troubleshooting/ ---- - -Troubleshooting newer hardware -============================== - -By default, the kernel that is installed in dom0 comes from the `kernel` package, which is an older Linux LTS kernel. -For most cases this works fine since the Linux kernel developers backport fixes to this kernel, but for some newer hardware, you may run into issues. -For example, the audio might not work if the sound card is too new for the LTS kernel. -To fix this, you can try the `kernel-latest` package -- though be aware that it's less tested! -(See [here][dom0-kernel-upgrade] for more information about upgrading kernels in dom0.) -In dom0: - -~~~ -sudo qubes-dom0-update kernel-latest -~~~ - -Reboot when it's done installing. -You can double-check that the boot used the newer kernel with `uname -r`, which prints the version of the currently-running kernel. -Compare this with the output of `rpm -q kernel`. -If the start of `uname -r` matches one of the versions printed by `rpm`, then you're still using the Linux LTS kernel, and you'll probably need to manually fix your boot settings. -If `uname -r` reports a higher version number, then you've successfully booted with the kernel shipped by `kernel-latest`. - - -[dom0-kernel-upgrade]: /doc/software-update-dom0/#kernel-upgrade - diff --git a/user/troubleshooting/hardware-troubleshooting.md b/user/troubleshooting/hardware-troubleshooting.md new file mode 100644 index 00000000..c76e81ae --- /dev/null +++ b/user/troubleshooting/hardware-troubleshooting.md @@ -0,0 +1,59 @@ +--- +layout: doc +title: Hardware Troubleshooting +permalink: /doc/hardware-troubleshooting/ +redirect_from: +- /doc/newer-hardware-troubleshooting/ +--- + +# Troubleshooting hardware-related issues + +## Audio doesn't work / Troubleshooting newer hardware + +By default, the kernel that is installed in dom0 comes from the `kernel` package, which is an older Linux LTS kernel. +For most cases this works fine since the Linux kernel developers backport fixes to this kernel, but for some newer hardware, you may run into issues. +For example, the audio might not work if the sound card is too new for the LTS kernel. +To fix this, you can try the `kernel-latest` package -- though be aware that it's less tested! +(See [here][dom0-kernel-upgrade] for more information about upgrading kernels in dom0). +In dom0: + +~~~ +sudo qubes-dom0-update kernel-latest +~~~ + +Reboot when it's done installing. +You can double-check that the boot used the newer kernel with `uname -r`, which prints the version of the currently-running kernel. +Compare this with the output of `rpm -q kernel`. +If the start of `uname -r` matches one of the versions printed by `rpm`, then you're still using the Linux LTS kernel, and you'll probably need to manually fix your boot settings. +If `uname -r` reports a higher version number, then you've successfully booted with the kernel shipped by `kernel-latest`. + +## "Unsupported Hardware Detected" error + +See [Installation Troubleshooting](/doc/installation-troubleshooting/#unsupported-hardware-detected-error). + +## Keyboard layout settings not behaving correctly + +The best approach is to choose the right keyboard layout during the installation process. +But if you want to change things afterwards, you can try this workaround. + +Assuming XFCE desktop: in `Q` → `System Tools` → `Keyboard` → `Layout`, leave the checkbox "`Use system defaults`" checked. Do not customize the keyboard layout here. + +Set the system-wide layout and options for `xorg` with the `localectl` command in `dom0`. You can use `localectl --help` as a starting point. + +Example: `localectl set-x11-keymap us dell ,qwerty compose:caps`. + +This generates the appropriate configuration in `/etc/X11/xorg.conf.d/00-keyboard.conf`. +This file is auto-generated. +Do not edit it by hand, unless you know what you are doing. + +Restarting `xorg` is required. +The most straightforward way is to reboot the system. + +More information in [this discussion][layout_discussion] and [this GitHub issue][layout_issue]. + + +[dom0-kernel-upgrade]: /doc/software-update-dom0/#kernel-upgrade +[hardware-reqs]: /doc/installation-guide/#hardware-requirements +[layout_discussion]: https://groups.google.com/d/topic/qubes-devel/d8ZQ_62asKI/discussion +[layout_issue]: https://github.com/QubesOS/qubes-issues/issues/1396 + diff --git a/user/troubleshooting/installation-troubleshooting.md b/user/troubleshooting/installation-troubleshooting.md index f0bc0213..ce306938 100644 --- a/user/troubleshooting/installation-troubleshooting.md +++ b/user/troubleshooting/installation-troubleshooting.md @@ -77,6 +77,19 @@ If installing the available drivers does not help, disable the network card in t If this solves the issue, it confirms the PCI card is incompatible with Qubes. In this case, you may want to consider replacing it with a network card of a different brand. Broadcom cards are notoriously problematic with Qubes. - +## "Unsupported Hardware Detected" error ## + +During Qubes installation, you may come across the error message which reads "Unsupported Hardware Detected. +Missing features: IOMMU/VT-d/AMD-Vi, Interrupt Remapping. Without these features, Qubes OS will not function normally". + +This error message indicates that IOMMU-virtualization hasn’t been activated in the BIOS. +Return to the [hardware requirements][hardware-reqs] section to learn how to activate it. +If the setting is not configured correctly, it means that your hardware won’t be able to leverage some Qubes security features, such as a strict isolation of the networking and USB hardware. + +In Qubes 4.0, the default installation won't function properly without IOMMU, as default sys-net and sys-usb qubes require IOMMU. It is possible to configure them to reduce isolation and not use IOMMU by changing virtualization mode of these two VMs to "PV". + +In Qubes 4.1, IOMMU is strictly required, even when the virtualization mode of a VM is changed to "PV"; it is not possible to use Qubes on a system without IOMMU. + +[hardware-reqs]: /doc/installation-guide/#hardware-requirements