Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-12-25 23:39:37 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'patch-4' of https://github.com/awokd/qubes-doc into awokd-patch-4

Browse Source
This commit is contained in:
Andrew David Wong 2019-09-15 16:20:03 -05:00
commit b17b2fa803
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
1 changed files with 141 additions and 133 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

274
user/advanced-configuration/uefi-troubleshooting.md
View File

@ -14,7 +14,7 @@ If you've installed successfully in legacy mode but had to change some kernel pa
**Change the xen configuration on a USB media** **Change the xen configuration on a USB media**
01. Attach the usb disk, mount the EFI partition (second partition available on the disk) 01. Attach the usb disk, mount the EFI partition (second partition available on the disk)
02. Edit your xen config (`xen.cfg/BOOTX64.cfg`) changing the `kernel` key to add your kernel parameters on the boot entry of your choice 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 03. Install using your modified boot entry
**Change xen configuration directly in an iso image** **Change xen configuration directly in an iso image**
@ -25,41 +25,99 @@ If you've installed successfully in legacy mode but had to change some kernel pa
05. Save your changes, unmount and dd to usb device 05. Save your changes, unmount and dd to usb device
Cannot start installation, installation completes successfully but then BIOS loops at boot device selection, hangs at four penguins after choosing "Test media and install Qubes OS" in GRUB menu Installation freezes before displaying installer
-----------------------------------------------------------
Some systems can freeze with the default UEFI install options.
You can try the following to remove `noexitboot` and `mapbs`.
If you have an Nvidia card, see also [Nvidia Troubleshooting](/doc/nvidia-troubleshooting/#disabling-nouveau).
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.
Installation freezes before displaying installer / 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 completes successfully but then boot loops or hangs on black screen
--------------------- ---------------------
There is some [common bug in UEFI implementation](http://xen.markmail.org/message/f6lx2ab4o2fch35r), affecting mostly Lenovo systems, but probably some others too. You can try existing workaround: 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:
01. In GRUB menu<sup id="a1-1">[1](#f1)</sup>, select "Troubleshoot", then "Boot from device", then press `e`. 1. Perform installation normally, but don't reboot the system at the end yet.
02. At the end of `chainloader` line add `/mapbs /noexitboot`. 2. Go to `tty2` (Ctrl-Alt-F2).
03. Perform installation normally, but don't reboot the system at the end yet. 3. Enable `mapbs` and/or `noexitboot` on the just installed system.
04. Go to `tty2` (Ctrl-Alt-F2). Edit `/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg` (you can use `vi` or `nano` editor) and add to every kernel section:
05. Enable `/mapbs /noexitboot` on just installed system. This step differs between Qubes releases:
**For Qubes 3.1:**
06. Execute `mount | grep boot/efi` and note device name (first column). It should be something like `/dev/sda1`.
07. Execute `efibootmgr -v`, search for `Qubes` entry and note its number (it should be something like `Boot0001` - `0001` is an entry number).
08. Replace existing `Qubes` entry with modified one. Replace `XXXX` with entry number from previous step, `/dev/sda` with your disk name and `-p 1` with `/boot/efi` partition number):
efibootmgr -b XXXX -B
efibootmgr -v -c -u -L Qubes -l /EFI/qubes/xen.efi -d /dev/sda -p 1 "placeholder /mapbs /noexitboot"
09. Compare new entry with the old one (printed in step 6) - it should only differ in additional options at the end, and look probably something like this:
Boot0001* Qubes HD(1,GPT,partition-guid-here,0x800,0x64000)/File(\EFI\qubes\xen.efi)p.l.a.c.e.h.o.l.d.e.r. ./.m.a.p.b.s. ./.n.o.e.x.i.t.b.o.o.t.
If instead it looks like:
Boot0001* Qubes HD(1,0,00000000...0,0x0,0x0)/File(\EFI\qubes\xen.efi)p.l.a.c.e.h.o.l.d.e.r. ./.m.a.p.b.s. ./.n.o.e.x.i.t.b.o.o.t.
then try passing `/dev/sda1` or `/dev/nvme0n1p1` or whatever your EFI partition is instead of `/dev/sda` and `-p 1`.
10. Now you can reboot the system by issuing `reboot` command.
**For Qubes 3.2 or later:**
11. Edit `/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg` (you can use `vi` editor) and add to every kernel section:
mapbs=1 mapbs=1
noexitboot=1 noexitboot=1
@ -69,43 +127,63 @@ There is some [common bug in UEFI implementation](http://xen.markmail.org/messag
line (i.e., all sections except the first one, since it doesn't have a line (i.e., all sections except the first one, since it doesn't have a
kernel line). kernel line).
12. Now you can reboot the system by issuing `reboot` command. 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.
System crash/restart when booting installer 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). And there is another workaround for it: 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.
1. In GRUB menu<sup id="a1-2">[1](#f1)</sup> press `e`. 2. Go to `tty2` (Ctrl-Alt-F2).
2. At the end of `chainloader` line add `-- efi=attr=uc`. 3. Execute:
3. Perform installation normally, but don't reboot the system at the end yet.
4. Go to `tty2` (Ctrl-Alt-F2).
5. Execute:
sed -i -e 's/^options=.*/\0 efi=attr=uc/' /mnt/sysimage/boot/efi/qubes/xen.cfg
or if you're installing 3.2 execute:
sed -i -e 's/^options=.*/\0 efi=attr=uc/' /mnt/sysimage/boot/efi/EFI/qubes/xen.cfg sed -i -e 's/^options=.*/\0 efi=attr=uc/' /mnt/sysimage/boot/efi/EFI/qubes/xen.cfg
6. Now you can reboot the system by issuing `reboot` command. 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:
<b name="f1">1</b> If you use rEFInd, you can see 3 options regarding the USB installer. Choose "Fallback Boot Loader" to enter the GRUB menu. [↩](#a1-1) [↩](#a1-2)
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 Boot device not recognized after installing
------------------------------------------ ------------------------------------------
Some firmware will not recognize the default Qubes EFI configuration. As such, Some firmware will not recognize the default Qubes EFI configuration.
it will have to be manually edited to be bootable. This will need to be done after As such, it will have to be manually edited to be bootable.
every kernel and Xen update to ensure you use the most recently installed versions. 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/` 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):
(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 cp -r /boot/efi/EFI/qubes/. /boot/efi/EFI/BOOT
@ -113,20 +191,19 @@ besides what is described in steps 2 and 3):
mv /boot/efi/EFI/BOOT/xen.cfg /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` 3. Copy `/boot/efi/EFI/qubes/xen-*.efi` to `/boot/efi/EFI/qubes/xen.efi` and `/boot/efi/EFI/BOOT/BOOTX64.efi`.
and `/boot/efi/EFI/BOOT/BOOTX64.efi`. For example with Xen 4.8.3 For example, with Xen 4.8.3 (you may need to confirm file overwrite):
(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/qubes/xen.efi
cp /boot/efi/EFI/qubes/xen-4.8.3.efi /boot/efi/EFI/BOOT/BOOTX64.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 finished but "Qubes" boot option is missing and xen.cfg is empty
-------------------------------------------------------------------------------------- --------------------------------------------------------------------------------------
In some cases installer fails to finish EFI setup and leave the system without In some cases installer fails to finish EFI setup and leave the system without a Qubes-specific EFI configuration.
Qubes-specific EFI configuration. In such a case you need to finish those parts In such a case you need to finish those parts manually.
manually. You can do that just after installation (switch to `tty2` with 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).
Ctrl-Alt-F2), or booting from installation media in "Rescue a Qubes system" mode.
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: 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:
@ -143,7 +220,6 @@ Ctrl-Alt-F2), or booting from installation media in "Rescue a Qubes system" mode
3. Create xen.cfg with this content (adjust kernel version, and filesystem 3. Create xen.cfg with this content (adjust kernel version, and filesystem
locations, below values are based on default installation of Qubes 3.2): locations, below values are based on default installation of Qubes 3.2):
[global] [global]
default=4.4.14-11.pvops.qubes.x86_64 default=4.4.14-11.pvops.qubes.x86_64
@ -157,79 +233,11 @@ Ctrl-Alt-F2), or booting from installation media in "Rescue a Qubes system" mode
efibootmgr -v -c -u -L Qubes -l /EFI/qubes/xen.efi -d /dev/sda -p 1 "placeholder /mapbs /noexitboot" efibootmgr -v -c -u -L Qubes -l /EFI/qubes/xen.efi -d /dev/sda -p 1 "placeholder /mapbs /noexitboot"
Installation freezes before getting to Anaconda (Qubes 4.0)
-----------------------------------------------------------
Some systems can freeze with the default UEFI install options.
You can try the following to remove `noexitboot` and `mapbs`.
If you have an Nvidia card, see also [Nvidia Troubleshooting](/doc/nvidia-troubleshooting/#disabling-nouveau).
1. Follow the [steps above](/doc/uefi-troubleshooting/#change-installer-kernel-parameters-in-uefi) to edit the `[qubes-verbose]` section of your installer's `xen.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.
Installation freezes before getting to Anaconda / 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`.
1. Follow the [steps above](/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 [other steps above](/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`.
Accessing installer Rescue mode on UEFI Accessing installer Rescue mode on UEFI
--------------------------------------- ---------------------------------------
In UEFI mode installer do not have boot menu, but starts directly the installation wizard. To get into Rescue mode, you need to switch to tty2 (Ctrl+Alt+F2) and then execute: 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 pkill -9 anaconda