Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-12-10 05:30:36 -05:00
Code Issues Projects Releases Packages Wiki Activity

Consolidate UEFI Troubleshooting, move file

Browse source
This commit is contained in:
PROTechThor 2020-10-02 09:15:32 +01:00
parent b93eccf739
commit afc2c29146
3 changed files with 34 additions and 103 deletions
Download patch file Download diff file Expand all files Collapse all files

80
user/troubleshooting/installation-troubleshooting.md
View file

@ -1,80 +0,0 @@
---
layout: doc
title: Installation Troubleshooting
permalink: /doc/installation-troubleshooting/
---
# Installation Troubleshooting #
## "An unknown error has occured" error during installation ##
Some people have encountered this error message when trying to install Qubes on drives that already have data on them.
The solution is to exit the installer, wipe all data or delete all partitions, then restart the Qubes installation.
## Trouble installing from USB stick ##
If you are facing issues when booting using UEFI mode, see the [UEFI troubleshooting guide](/doc/uefi-troubleshooting/).
There are a variety of other problems that could arise when using a USB installation medium, and some of the issues can be fixed by doing one or more of the following:
* **Use a different USB drive:**
If possible, try several drives of different sizes and formats.
This determines whether the problem stems from the flash drive or Qubes installer.
Some laptops cannot read from an external boot device larger than 8GB.
If you encounter a black screen when performing an installation from a USB stick, ensure you are using a USB drive less than 8GB, or a partition on that USB less than 8GB and of format FAT32.
* **Verify your Qubes ISO:**
Errors will occur if the Qubes installer is corrupted.
Ensure that the installer is correct and complete before writing it to a flash drive by [verifying the ISO](/security/verifying-signatures/#how-to-verify-qubes-iso-signatures).
* **Change the method you used to [write your ISO to a USB key](/doc/installation-guide/#copying-the-iso-onto-the-installation-medium):**
Some people use the ``dd`` command (recommended), others use tools like Rufus and balenaEtcher.
If installation fails after using one tool, try a different one.
For example, if you are facing trouble installing Qubes after writing the ISO using Rufus, then try using other tools like balenaEtcher or the ``dd`` command.
## Boot screen does not appear / system does not detect your installation medium ##
If the boot screen does not appear, there are several options to troubleshoot.
First, try rebooting your computer.
If it still loads your currently installed operating system or does not detect your installation medium, make sure the boot order is set up appropriately.
The process to change the boot order varies depending on the currently installed system and the motherboard manufacturer.
If **Windows 10** is installed on your machine, you may need to follow specific instructions to change the boot order.
This may require an [advanced reboot](https://support.microsoft.com/en-us/help/4026206/windows-10-find-safe-mode-and-other-startup-settings).
## "Not asking for VNC because we don't have a network" / "X startup failed, aborting installation" / "Pane is dead" error during installation ##
The boot mode in use may be causing these error messages.
Try to install after enabling both UEFI and legacy boot modes.
If that doesn't help, then disable one and try the other.
Visit the [UEFI Troubleshooting guide](/doc/uefi-troubleshooting/) if other errors arise during UEFI booting.
These errors may also occur due to an incompatible Nvidia graphics card. If you have one, follow the following instructions:
1. Disable secure/fast boot and use legacy mode
2. Enter GRUB, move the selection to the first choice, and then press the Tab key.
3. Now, you are in edit mode. Move the text cursor with your arrow key and after ``kernel=`` line, add:
``nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off``
If the above code doesn't fix the problem, replace it with:
``noexitboot=1 modprobe.blacklist=nouveau rd.driver.blacklist=nouveau --- intitrd.img``
For more information, look at the [Nvidia Troubleshooting guide](/doc/nvidia-troubleshooting/#disabling-nouveau).
## Installation freezes at "Setting up Networking" ##
If you are facing this problem on an Apple computer, check out the [Macbook Troubleshooting guide](/doc/macbook-troubleshooting/).
This issue occurs due to the network card, which may be missing some drivers or is incompatible with Qubes.
First, install all available drivers for the card.
You can install the drivers without internet access by first downloading them on another machine, then transferring them over to the current machine (e.g., with a USB drive).
If installing the available drivers does not help, disable the network card in the BIOS and perform the installation before re-enabling the card.
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.

260
user/troubleshooting/uefi-troubleshooting.md Normal file
View file

@ -0,0 +1,260 @@
---
layout: doc
title: UEFI Troubleshooting
permalink: /doc/uefi-troubleshooting/
---
# Troubleshooting UEFI related problems #
## Successfully installed in legacy mode, but had to change some kernel parameters ##
If you've installed successfully in legacy mode but had to change some kernel parameters for it to work, you should try installing in UEFI mode with the same parameters.
**Change the xen configuration on a USB media**
01. Attach the usb disk, mount the EFI partition (second partition available on the disk)
02. As `su`, edit your xen config (`EFI/BOOT/BOOTX64.cfg`) changing the `kernel` key to add your kernel parameters on the boot entry of your choice
03. Install using your modified boot entry
**Change xen configuration directly in an iso image**
01. Get EFI partition boundaries `parted Qubes-R4.0-rc4-x86_64.iso unit B print`
02. Using the start address and the size of the EFI partition, setup a loop device for it `sudo losetup -o 524288 --sizelimit 30562304 /dev/loop0 Qubes-R4.0-rc4-x86_64.iso`
03. Mount the loop device `sudo mount /dev/loop0 /mnt`
04. Edit `EFI/BOOT/BOOTX64.cfg` to add your params to the `kernel` configuration key
05. Save your changes, unmount and dd to usb device
## Installation freezes before displaying installer ##
If you have an Nvidia card, see also [Nvidia Troubleshooting](/doc/nvidia-troubleshooting/#disabling-nouveau).
### Removing `noexitboot` and `mapbs` ###
Some systems can freeze with the default UEFI install options.
You can try the following to remove `noexitboot` and `mapbs`.
1. Follow the [steps here](/doc/uefi-troubleshooting/#change-installer-kernel-parameters-in-uefi) to edit the `[qubes-verbose]` section of your installer's `BOOTX64.cfg`.
You want to comment out the `mapbs` and `noexitboot` lines.
The end result should look like this:
~~~
[qubes-verbose]
options=console=vga efi=attr=uc
# noexitboot=1
# mapbs=1
kernel=vmlinuz inst.stage2=hd:LABEL=Qubes-R4.0-x86_64 i915.alpha_support=1
ramdisk=initrd.img
~~~
2. Boot the installer and continue to install as normal, but don't reboot the system at the end when prompted.
3. Go to `tty2` (Ctrl-Alt-F2).
4. Use your preferred text editor (`nano` works) to edit `/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg`, verifying the `noexitboot` and `mapbs` lines are not present.
This is also a good time to make permanent any other changes needed to get the installer to work, such as `nouveau.modeset=0`.
For example:
~~~
[4.14.18-1.pvops.qubes.x86_64]
options=loglvl=all dom0_mem=min:1024M dom0_mem=max:4096M iommu=no-igfx ucode=scan efi=attr=uc
~~~
5. Go back to `tty6` (Ctrl-Alt-F6) and click `Reboot`.
6. Continue with setting up default templates and logging in to Qubes.
### Changing `options=console=` parameter to `none` ###
If removing `noexitboot` and `mapbs` did not help, you can try changing the `options=console=` parameter to `none`. The detailed solution can be found in the comments of [this GitHub issue](https://github.com/QubesOS/qubes-issues/issues/5383)
1. Follow the [steps here](/doc/uefi-troubleshooting/#change-installer-kernel-parameters-in-uefi) to edit the `[qubes-verbose]` section of your installer's `BOOTX64.cfg`.
You want to change `options=console=vga` to `options=console=none`.
The end result should look like this:
~~~
[qubes-verbose]
options=console=none efi=attr=uc
noexitboot=1
mapbs=1
kernel=vmlinuz inst.stage2=hd:LABEL=Qubes-R4.0-x86_64 i915.alpha_support=1
ramdisk=initrd.img
~~~
2. Boot the installer and continue to install as normal
### Disable EFI runtime services ###
On some early, buggy UEFI implementations, you may need to disable EFI under Qubes completely.
This can sometimes be done by switching to legacy mode in your BIOS/UEFI configuration.
If that's not an option there, or legacy mode does not work either, you can try the following to add `efi=no-rs`.
Consider this approach as a last resort, because it will make every Xen update a manual process.
1. Follow the [steps here](/doc/uefi-troubleshooting/#change-installer-kernel-parameters-in-uefi) to edit the `[qubes-verbose]` section of your installer's `xen.cfg`.
You want to modify the `efi=attr=uc` setting and comment out the `mapbs` and `noexitboot` lines.
The end result should look like this:
~~~
[qubes-verbose]
options=console=vga efi=no-rs
# noexitboot=1
# mapbs=1
kernel=vmlinuz inst.stage2=hd:LABEL=Qubes-R4.0-x86_64 i915.alpha_support=1
ramdisk=initrd.img
~~~
2. Boot the installer and continue to install as normal, until towards the end when you will receive a warning about being unable to create the EFI boot entry.
Click continue, but don't reboot the system at the end when prompted.
3. Go to `tty2` (Ctrl-Alt-F2).
4. Use your preferred text editor (`nano` works) to edit `/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg`, adding the `efi=no-rs` option to the end of the `options=` line.
For example:
~~~
[4.14.18-1.pvops.qubes.x86_64]
options=loglvl=all dom0_mem=min:1024M dom0_mem=max:4096M iommu=no-igfx ucode=scan efi=no-rs
~~~
5. Execute the following commands:
~~~
cp -R /mnt/sysimage/boot/efi/EFI/qubes /mnt/sysimage/boot/efi/EFI/BOOT
mv /mnt/sysimage/boot/efi/EFI/BOOT/xen-*.efi /mnt/sysimage/boot/efi/EFI/BOOT/BOOTX64.efi
mv /mnt/sysimage/boot/efi/EFI/BOOT/xen.cfg /mnt/sysimage/boot/efi/EFI/BOOT/BOOTX64.cfg
~~~
6. Go back to `tty6` (Ctrl-Alt-F6) and click `Reboot`.
7. Continue with setting up default templates and logging in to Qubes.
Whenever there is a kernel or Xen update for Qubes, you will need to follow [these steps](/doc/uefi-troubleshooting/#boot-device-not-recognized-after-installing) because your system is using the fallback UEFI bootloader in `[...]/EFI/BOOT` instead of directly booting to the Qubes entry under `[...]/EFI/qubes`.
## Installation from USB stick hangs on black screen ##
Some laptops cannot read from an external boot device larger than 8GB. If you encounter a black screen when performing an installation from a USB stick, ensure you are using a USB drive less than 8GB, or a partition on that USB lesser than 8GB and of format FAT32.
## Installation completes successfully but then boot loops or hangs on black screen ##
There is a [common bug in UEFI implementation](http://xen.markmail.org/message/f6lx2ab4o2fch35r) affecting mostly Lenovo systems, but probably some others too.
While some systems need `mapbs` and/or `noexitboot` disabled to boot, others require them enabled at all times.
Although these are enabled by default in the installer, they are disabled after the first stage of a successful install.
You can re-enable them either as part of the install process:
1. Perform installation normally, but don't reboot the system at the end yet.
2. Go to `tty2` (Ctrl-Alt-F2).
3. Enable `mapbs` and/or `noexitboot` on the just installed system.
Edit `/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg` (you can use `vi` or `nano` editor) and add to every kernel section:
mapbs=1
noexitboot=1
**Note:** You must add these parameters on two separate new lines (one
parameter on each line) at the end of each section that includes a kernel
line (i.e., all sections except the first one, since it doesn't have a
kernel line).
4. Go back to `tty6` (Ctrl-Alt-F6) and click `Reboot`.
5. Continue with setting up default templates and logging in to Qubes.
Or if you have already rebooted after the first stage install and have encountered this issue, by:
1. Boot into [rescue mode](/doc/uefi-troubleshooting/#accessing-installer-rescue-mode-on-uefi).
2. Enable `mapbs` and/or `noexitboot` on the just installed system.
Edit `/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg` (you can use `vi` or `nano` editor) and add to every kernel section:
mapbs=1
noexitboot=1
**Note:** You must add these parameters on two separate new lines (one
parameter on each line) at the end of each section that includes a kernel
line (i.e., all sections except the first one, since it doesn't have a
kernel line).
3. Type `reboot`.
4. Continue with setting up default templates and logging in to Qubes.
## Installation completes successfully but then system crash/restarts on next boot ##
Some Dell systems and probably others have [another bug in UEFI firmware](http://markmail.org/message/amw5336otwhdxi76).
These systems need `efi=attr=uc` enabled at all times.
Although this is enabled by default in the installer, it is disabled after the first stage of a successful install.
You can re-enable it either as part of the install process:
1. Perform installation normally, but don't reboot the system at the end yet.
2. Go to `tty2` (Ctrl-Alt-F2).
3. Execute:
sed -i -e 's/^options=.*/\0 efi=attr=uc/' /mnt/sysimage/boot/efi/EFI/qubes/xen.cfg
4. Go back to `tty6` (Ctrl-Alt-F6) and click `Reboot`.
5. Continue with setting up default templates and logging in to Qubes.
Or if you have already rebooted after the first stage install and have encountered this issue, by:
1. Boot into [rescue mode](/doc/uefi-troubleshooting/#accessing-installer-rescue-mode-on-uefi).
2. Execute:
sed -i -e 's/^options=.*/\0 efi=attr=uc/' /mnt/sysimage/boot/efi/EFI/qubes/xen.cfg
3. Type `reboot`.
4. Continue with setting up default templates and logging in to Qubes.
## Boot device not recognized after installing ##
Some firmware will not recognize the default Qubes EFI configuration.
As such, it will have to be manually edited to be bootable.
This will need to be done after every kernel and Xen update to ensure you use the most recently installed versions.
1. Copy the `/boot/efi/EFI/qubes/` directory to `/boot/efi/EFI/BOOT/` (the contents of `/boot/efi/EFI/BOOT` should be identical to `/boot/efi/EFI/qubes` besides what is described in steps 2 and 3):
cp -r /boot/efi/EFI/qubes/. /boot/efi/EFI/BOOT
2. Rename `/boot/efi/EFI/BOOT/xen.cfg` to `/boot/efi/EFI/BOOT/BOOTX64.cfg`:
mv /boot/efi/EFI/BOOT/xen.cfg /boot/efi/EFI/BOOT/BOOTX64.cfg
3. Copy `/boot/efi/EFI/qubes/xen-*.efi` to `/boot/efi/EFI/qubes/xen.efi` and `/boot/efi/EFI/BOOT/BOOTX64.efi`.
For example, with Xen 4.8.3 (you may need to confirm file overwrite):
cp /boot/efi/EFI/qubes/xen-4.8.3.efi /boot/efi/EFI/qubes/xen.efi
cp /boot/efi/EFI/qubes/xen-4.8.3.efi /boot/efi/EFI/BOOT/BOOTX64.efi
## Installation finished but "Qubes" boot option is missing and xen.cfg is empty / Installation fails with "failed to set new efi boot target" ##
In some cases installer fails to finish EFI setup and leave the system without a Qubes-specific EFI configuration.
In such a case you need to finish those parts manually.
You can do that just after installation (switch to `tty2` with Ctrl-Alt-F2), or by booting from installation media in [rescue mode](/doc/uefi-troubleshooting/#accessing-installer-rescue-mode-on-uefi).
1. Examine `/boot/efi/EFI/qubes` (if using Qubes installation media, it's in `/mnt/sysimage/boot/efi/EFI/qubes`). You should see 4 files there:
- xen.cfg (empty, size 0)
- xen-(xen-version).efi
- vmlinuz-(kernel-version)
- initramfs-(kernel-version).img
2. Copy `xen-(xen-version).efi` to `xen.efi`:
cd /mnt/sysimage/boot/efi/EFI/qubes
cp xen-*.efi xen.efi
3. Create xen.cfg with this content (adjust kernel version, and filesystem
locations, below values are based on default installation of Qubes 3.2):
[global]
default=4.4.14-11.pvops.qubes.x86_64
[4.4.14-11.pvops.qubes.x86_64]
options=loglvl=all dom0_mem=min:1024M dom0_mem=max:4096M
kernel=vmlinuz-4.4.14-11.pvops.qubes.x86_64 root=/dev/mapper/qubes_dom0-root rd.lvm.lv=qubes_dom0/root rd.lvm.lv=qubes_dom0/swap i915.preliminary_hw_support=1 rhgb quiet
ramdisk=initramfs-4.4.14-11.pvops.qubes.x86_64.img
4. Create boot entry in EFI firmware (replace `/dev/sda` with your disk name and `-p 1` with `/boot/efi` partition number):
efibootmgr -v -c -u -L Qubes -l /EFI/qubes/xen.efi -d /dev/sda -p 1 "placeholder /mapbs /noexitboot"
## Accessing installer Rescue mode on UEFI ##
In UEFI mode, the installer does not have a boot menu, but boots directly into the installation wizard.
To get into Rescue mode, you need to switch to tty2 (Ctrl+Alt+F2) and then execute:
~~~
pkill -9 anaconda
anaconda --rescue
~~~