mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-01-11 23:39:38 -05:00
Merge branch 'master' into disk-troubleshooting
This commit is contained in:
Enjeck Cleopatra
GitHub
commit
f28b6b4605
@ -7,6 +7,9 @@ permalink: /doc/package-contributions/
|
||||
Package Contributions
|
||||
=====================
|
||||
|
||||
_This page is for developers who wish to contribute packages.
|
||||
If you want to install contributed packages, please see [installing contributed packages]._
|
||||
|
||||
We're very grateful to the talented and hard-working community members who contribute software packages to Qubes OS.
|
||||
This page explains the inclusion criteria and procedures for such packages, as well as the roles and responsibilities of those involved.
|
||||
|
||||
@ -94,6 +97,7 @@ If you do not wish to be the maintainer of your package, please let us know.
|
||||
If you do not act on your maintainer duties for a given package for an extended period of time and after at least one reminder, we will assume that you no longer wish to be the maintainer for that package.
|
||||
|
||||
|
||||
[installing contributed packages]: /doc/installing-contributed-packages/
|
||||
[Inclusion Criteria]: #inclusion-criteria
|
||||
[Contribution Procedure]: #contribution-procedure
|
||||
[Update Procedure]: #update-procedure
|
||||
|
||||
22
doc.md
22
doc.md
@ -122,16 +122,10 @@ Core documentation for Qubes users.
|
||||
|
||||
* [Installation Troubleshooting](/doc/installation-troubleshooting)
|
||||
* [UEFI Troubleshooting](/doc/uefi-troubleshooting/)
|
||||
* [Suspend/Resume Troubleshooting](/doc/suspend-resume-troubleshooting/)
|
||||
* [VM Troubleshooting](/doc/vm-troubleshooting/)
|
||||
* [HVM Troubleshooting](/doc/hvm-troubleshooting/)
|
||||
* [Disk Troubleshooting](/doc/disk-troubleshooting/)
|
||||
* [Installing on system with new AMD GPU (missing firmware problem)](https://groups.google.com/group/qubes-devel/browse_thread/thread/e27a57b0eda62f76)
|
||||
* [How to install an Nvidia driver in dom0](/doc/install-nvidia-driver/)
|
||||
* [Nvidia troubleshooting guide](/doc/nvidia-troubleshooting/)
|
||||
* [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/)
|
||||
|
||||
### Reference Pages
|
||||
|
||||
@ -274,6 +268,16 @@ For more, please see [Qubes Community Documentation](https://github.com/Qubes-Co
|
||||
* [Dark Theme in Dom0 and DomU](/doc/dark-theme/)
|
||||
* [Safely Removing TemplateVM Packages (Example: Thunderbird)](/doc/removing-templatevm-packages/)
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
* [Installing on system with new AMD GPU (missing firmware problem)](https://groups.google.com/group/qubes-devel/browse_thread/thread/e27a57b0eda62f76)
|
||||
* [How to install an Nvidia driver in dom0](/doc/install-nvidia-driver/)
|
||||
* [Nvidia troubleshooting guide](/doc/nvidia-troubleshooting/)
|
||||
* [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/)
|
||||
* [Intel Integrated Graphics Troubleshooting](/doc/intel-igfx-troubleshooting/)
|
||||
|
||||
### Building Guides
|
||||
|
||||
* [Building a TemplateVM based on a new OS (ArchLinux example)](/doc/building-non-fedora-template/)
|
||||
|
||||
36
external/os-guides/linux-hvm-tips.md
vendored
36
external/os-guides/linux-hvm-tips.md
vendored
@ -14,41 +14,7 @@ Tips for Linux in HVM domain
|
||||
How to fix bootup kernel error
|
||||
-------------------------------
|
||||
|
||||
The HVM may pause on boot, showing a fixed cursor.
|
||||
After a while a series of warnings may be shown similar to this:
|
||||
|
||||
BUG: soft lockup - CPU#0 stuck for 23s! [systemd-udevd:244]
|
||||
|
||||
To fix this:
|
||||
|
||||
1. Kill the HVM.
|
||||
1. Start the HVM
|
||||
1. Press "e" at the grub screen to edit the boot parameters
|
||||
1. Find the /vmlinuz line, and edit it to replace "rhgb" with "modprobe.blacklist=bochs_drm"
|
||||
1. Press "Ctrl-x" to start the HVM
|
||||
|
||||
If this solves the problem then you will want to make the change permanent:
|
||||
|
||||
1. Edit the file `/etc/default/grub`.
|
||||
1. Find the line which starts:
|
||||
~~~
|
||||
GRUB_CMDLINE_LINUX=
|
||||
~~~
|
||||
1. Remove this text from that line:
|
||||
~~~
|
||||
rhgb
|
||||
~~~
|
||||
1. Add this text to that line:
|
||||
~~~
|
||||
modprobe.blacklist=bochs_drm
|
||||
~~~
|
||||
1. Run this command:
|
||||
~~~
|
||||
grub2-mkconfig --output=/boot/grub2/grub.cfg
|
||||
~~~
|
||||
|
||||
The HVM should now start normally.
|
||||
|
||||
If the HVM pauses on boot and shows a series of warnings, visit [HVM Troubleshooting](/doc/hvm-troubleshooting/#hvm-pauses-on-boot-followed-by-kernel-error) for a fix.
|
||||
|
||||
Screen resolution
|
||||
-----------------
|
||||
|
||||
@ -0,0 +1,51 @@
|
||||
---
|
||||
layout: doc
|
||||
title: Installing contributed packages
|
||||
permalink: /doc/installing-contributed-packages/
|
||||
---
|
||||
|
||||
# Installing contributed packages
|
||||
|
||||
_This page is for users who wish to install contributed packages.
|
||||
If you want to contribute a package, please see [package contributions]._
|
||||
|
||||
|
||||
Qubes OS contributed packages are available under the [QubesOS-contrib] GitHub Project.
|
||||
This is a place where our community can [contribute Qubes OS related packages, additions and various customizations][package contributions].
|
||||
|
||||
## Installing the repositories
|
||||
|
||||
If you want to install one of these packages, first you need to enable the repository in your system (dom0 and/or templates). This can be done by installing the `qubes-repo-contrib` package. This package includes the repository definition and keys necessary to download, verify, and install [QubesOS-contrib] packages.
|
||||
|
||||
In dom0, use `qubes-dom0-update`:
|
||||
|
||||
sudo qubes-dom0-update qubes-repo-contrib
|
||||
|
||||
In a Fedora-based template, use `dnf`:
|
||||
|
||||
sudo dnf install qubes-repo-contrib
|
||||
|
||||
In a Debian-based template, use `apt`:
|
||||
|
||||
sudo apt update && sudo apt install qubes-repo-contrib
|
||||
|
||||
The new repository definition will be in the usual location for your distro, and it will follow the naming pattern `qubes-contrib-*`, depending on your Qubes release and whether it is in dom0 or a TemplateVM.
|
||||
For example, in a Fedora TemplateVM on Qubes 4.0, the new repository definition would be:
|
||||
|
||||
/etc/yum.repos.d/qubes-contrib-vm-r4.0.repo
|
||||
|
||||
## Installing packages
|
||||
|
||||
After you've installed the repositories, you can install contributed packages.
|
||||
|
||||
**Note:** The first time you install a contrib package in dom0, you must use the `--clean` flag.
|
||||
|
||||
For example, to install `qvm-screenshot-tool` in dom0:
|
||||
|
||||
sudo qubes-dom0-update --clean qvm-screenshot-tool
|
||||
|
||||
Please see the package's README for specific installation and setup instructions.
|
||||
|
||||
[package contributions]: /doc/package-contributions/
|
||||
[QubesOS-contrib]: https://github.com/QubesOS-contrib/
|
||||
|
||||
@ -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
|
||||
|
||||
@ -122,6 +122,10 @@ sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable
|
||||
To enable or disable any of these repos permanently, change the corresponding `enabled` value to `1` in
|
||||
`/etc/yum.repos.d/qubes-dom0.repo`.
|
||||
|
||||
## Contributed package repository
|
||||
|
||||
Please see [installing contributed packages].
|
||||
|
||||
## Kernel upgrade
|
||||
|
||||
This section describes upgrading the kernel in dom0 and domUs.
|
||||
@ -219,4 +223,5 @@ For example: sys-whonix.
|
||||
[testing]: /doc/testing/
|
||||
[troubleshooting newer hardware]: /doc/newer-hardware-troubleshooting/
|
||||
[Managing VM kernel]: /doc/managing-vm-kernel/
|
||||
[installing contributed packages]: /doc/installing-contributed-packages/
|
||||
|
||||
|
||||
@ -43,6 +43,9 @@ Advanced users can execute the standard update command for that operating system
|
||||
|
||||
If you wish to install updates that are still in [testing], you must enable the appropriate testing repositories.
|
||||
|
||||
## Contributed package repository
|
||||
|
||||
Please see [installing contributed packages].
|
||||
|
||||
### Fedora
|
||||
|
||||
@ -314,4 +317,5 @@ Note that the app will autostart only when the AppVM starts. If you would like t
|
||||
[RPM Fusion]: http://rpmfusion.org/
|
||||
[service framework]: /doc/qubes-service/
|
||||
[How to Reinstall a TemplateVM]: /doc/reinstall-template/
|
||||
[installing contributed packages]: /doc/installing-contributed-packages/
|
||||
|
||||
|
||||
@ -103,17 +103,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/
|
||||
|
||||
65
user/troubleshooting/hvm-troubleshooting.md
Normal file
65
user/troubleshooting/hvm-troubleshooting.md
Normal file
@ -0,0 +1,65 @@
|
||||
---
|
||||
layout: doc
|
||||
title: HVM Troubleshooting
|
||||
permalink: /doc/hvm-troubleshooting/
|
||||
|
||||
---
|
||||
|
||||
# HVM Troubleshooting #
|
||||
|
||||
## HVM pauses on boot, followed by kernel error ##
|
||||
|
||||
The HVM may pause on boot, showing a fixed cursor.
|
||||
After a while a series of warnings may be shown similar to this:
|
||||
|
||||
BUG: soft lockup - CPU#0 stuck for 23s! [systemd-udevd:244]
|
||||
|
||||
To fix this:
|
||||
|
||||
1. Kill the HVM.
|
||||
1. Start the HVM
|
||||
1. Press "e" at the grub screen to edit the boot parameters
|
||||
1. Find the /vmlinuz line, and edit it to replace "rhgb" with "modprobe.blacklist=bochs_drm"
|
||||
1. Press "Ctrl-x" to start the HVM
|
||||
|
||||
If this solves the problem then you will want to make the change permanent:
|
||||
|
||||
1. Edit the file `/etc/default/grub`.
|
||||
1. Find the line which starts:
|
||||
~~~
|
||||
GRUB_CMDLINE_LINUX=
|
||||
~~~
|
||||
1. Remove this text from that line:
|
||||
~~~
|
||||
rhgb
|
||||
~~~
|
||||
1. Add this text to that line:
|
||||
~~~
|
||||
modprobe.blacklist=bochs_drm
|
||||
~~~
|
||||
1. Run this command:
|
||||
~~~
|
||||
grub2-mkconfig --output=/boot/grub2/grub.cfg
|
||||
~~~
|
||||
|
||||
The HVM should now start normally.
|
||||
|
||||
## Can't start an OS in an HVM / "Probing EDD (edd=off to disable!... ok" message ##
|
||||
|
||||
If you see a screen popup with SeaBios and 4 lines, last one being `Probing EDD (edd=off to disable!... ok`, then enter the following command from a `dom0` prompt:
|
||||
|
||||
qvm-prefs <HVMname> kernel ""
|
||||
|
||||
## HVM crashes when booting from ISO ##
|
||||
If your HVM crashes when trying to boot an ISO, first ensure that ` qvm-prefs <HVMname> kernel` is empty, as shown above.
|
||||
If this doesn't help, then disable memory balancing and set the minimum memory to 2GB.
|
||||
|
||||
You can disable memory-balancing in the settings, under the “Advanced” tab.
|
||||
|
||||
To give the VM a RAM of 2GB, open a terminal in `dom0` and enter:
|
||||
|
||||
qvm-prefs <HVMname> memory 2000
|
||||
|
||||
## Attached devices in Windows HVM stop working on suspend/resume ##
|
||||
|
||||
After the whole system gets suspended into S3 sleep and subsequently resumed, some attached devices may stop working. To know how to make the devices work, see [Suspend/resume Troubleshooting](/doc/suspend-resume-troubleshooting/#attached-devices-in-windows-hvm-stop-working-on-suspendresume).
|
||||
@ -1,19 +1,18 @@
|
||||
---
|
||||
layout: doc
|
||||
title: Wireless Troubleshooting
|
||||
permalink: /doc/wireless-troubleshooting/
|
||||
title: Suspend/Resume Troubleshooting
|
||||
permalink: /doc/suspend-resume-troubleshooting/
|
||||
redirect_from:
|
||||
- /en/doc/wireless-troubleshooting/
|
||||
- /doc/wireless-troubleshooting/
|
||||
---
|
||||
|
||||
Wireless Troubleshooting Guide
|
||||
==============================
|
||||
# Troubleshooting problems relating to suspend/resume #
|
||||
|
||||
## Network-Manager says “Device not ready” on suspend/resume ##
|
||||
|
||||
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 ###
|
||||
@ -104,8 +103,7 @@ depends: cfg80211
|
||||
[user@sys-net ~]$ sudo modprobe iwlmvm
|
||||
~~~
|
||||
|
||||
Automatically reloading drivers on suspend/resume
|
||||
-------------------------------------------------
|
||||
## Drivers do not reload automatically 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`.
|
||||
|
||||
@ -119,3 +117,18 @@ In the above example, it would look like this:
|
||||
iwlmvm
|
||||
iwlwifi
|
||||
~~~
|
||||
|
||||
## Power consumption increases on suspend/resume ##
|
||||
|
||||
This problem is related to the software method used to disable sibling threads and how it interacts with suspend/resume.
|
||||
To solve the problem, disable hyper-threading in the BIOS. This [external guide](https://www.pcmag.com/news/how-to-disable-hyperthreading) explains how to disable hyper-threading.
|
||||
Since Qubes does disable hyperthreading by default (by not using secondary threads), you won't pay any performance cost.
|
||||
|
||||
## Attached devices in Windows HVM stop working on suspend/resume ##
|
||||
|
||||
After the whole system gets suspended into S3 sleep and subsequently resumed, some attached devices may stop working. To make the devices work, they should be restarted within the VM.
|
||||
This can be achieved under a Windows HVM by opening the Device Manager, selecting the actual device (such as a USB controller), 'Disabling' the device, and then 'Enabling' the device again.
|
||||
This is illustrated on the screenshot below:
|
||||
|
||||
|
||||
|
||||
73
user/troubleshooting/vm-troubleshooting.md
Normal file
73
user/troubleshooting/vm-troubleshooting.md
Normal file
@ -0,0 +1,73 @@
|
||||
---
|
||||
layout: doc
|
||||
title: VM Troubleshooting
|
||||
permalink: /doc/vm-troubleshooting/
|
||||
redirect_from:
|
||||
- /doc/remove-vm-manually/
|
||||
---
|
||||
|
||||
# VM troubleshooting #
|
||||
|
||||
## 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.
|
||||
|
||||
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 ##
|
||||
|
||||
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”
|
||||
|
||||
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, 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.
|
||||
Loading…
Reference in New Issue
Block a user