Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-08-11 08:00:40 -04:00
Code Issues Projects Releases Packages Wiki Activity

Convert to RST

Browse source 
This is done using tools at
https://github.com/maiska/qubes-translation-utilz, commit
4c8e2a7f559fd37e29b51769ed1ab1c6cf92e00d.
This commit is contained in:
Marek Marczykowski-Górecki 2025-07-04 14:23:09 +02:00
parent e3db139fe3
commit 7e464d0f40
No known key found for this signature in database
GPG key ID: F32894BE9684938A
428 changed files with 32833 additions and 29703 deletions
Download patch file Download diff file Expand all files Collapse all files

146
user/troubleshooting/uefi-troubleshooting.rst Normal file
View file

@ -0,0 +1,146 @@
====================
UEFI troubleshooting
====================
Successfully installed in legacy mode, but had to change some xen parameters
----------------------------------------------------------------------------
**Note**: If you make changes, you must boot from “Partition 1” explicitly from UEFI boot menu.
**Change the xen configuration on a USB media**
1. Attach the usb disk, mount the EFI partition (second partition available on the disk)
2. Open a terminal and enter the command ``sudo su -``. Use your preferred text editor (e.g ``vi``) to edit your xen config (``EFI/BOOT/grub.cfg``):
.. code:: bash
vi EFI/BOOT/grub.cfg
3. Change the ``multiboot2 /images/pxeboot/xen.gz`` line to add your xen parameters on the boot entry of your choice
4. Install using your modified boot entry
**Change xen configuration directly in an iso image**
1. Set up a loop device (replacing ``X`` with your ISO’s version name): ``losetup -P /dev/loop0 Qubes-RX-x86_64.iso``
2. Mount the loop device: ``sudo mount /dev/loop0p2 /mnt``
3. Edit ``EFI/BOOT/grub.cfg`` to add your params to the ``multiboot2 /images/pxeboot/xen.gz`` line
4. Save your changes, unmount and dd to usb device
Installation freezes before displaying installer
------------------------------------------------
If you have an Nvidia card, see also `Nvidia Troubleshooting <https://forum.qubes-os.org/t/19021#disabling-nouveau>`__.
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 system crash/restarts on next boot
-------------------------------------------------------------------------------
Some Dell systems and probably others have `another bug in UEFI firmware <https://web.archive.org/web/20170901231026/https://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:
.. code:: bash
sed -i -e 's/ucode=scan/\0 efi=attr=uc/' /mnt/sysimage/boot/efi/EFI/qubes/grub.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 Qubes OS install media into :ref:`rescue mode <user/troubleshooting/uefi-troubleshooting:accessing installer rescue mode on uefi>`
2. Press ‘3’ to go to the shell
3. Find and mount the EFI system partition. (replace ``/dev/sda`` with your disk name. If unsure, use the ``lsblk`` command to display a list of disks): ``fdisk -l /dev/sda | grep EFI`` The output should look like this: ``/dev/sda1 2048 1230847 1228800 600M EFI System`` Then mount it: ``mkdir -p /mnt/sysimage/boot/efi mount /dev/sda1 /mnt/sysimage/boot/efi``
4. Execute:
.. code:: bash
sed -i -e 's/ucode=scan/\0 efi=attr=uc/' /mnt/sysimage/boot/efi/EFI/qubes/grub.cfg
5. Type ``reboot``.
6. 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.
1. Boot Qubes OS install media into :ref:`rescue mode <user/troubleshooting/uefi-troubleshooting:accessing installer rescue mode on uefi>`
2. Press ‘3’ to go to the shell
3. Find and mount the EFI system partition. (replace ``/dev/sda`` with your disk name. If unsure, use the ``lsblk`` command to display a list of disks): ``fdisk -l /dev/sda | grep EFI`` The output should look like this: ``/dev/sda1 2048 1230847 1228800 600M EFI System`` Then mount it: ``mkdir -p /mnt/sysimage/boot/efi mount /dev/sda1 /mnt/sysimage/boot/efi``
4. Copy ``grubx64.efi`` to the fallback path:
.. code:: bash
cp /mnt/sysimage/boot/efi/EFI/qubes/grubx64.efi /mnt/sysimage/boot/efi/EFI/BOOT/bootx64.efi
5. Type ``reboot``
"Qubes" boot option is missing after removing / attaching a disk or updating the BIOS
-------------------------------------------------------------------------------------
1. Boot Qubes OS install media into :ref:`rescue mode <user/troubleshooting/uefi-troubleshooting:accessing installer rescue mode on uefi>`
2. Press ‘3’ to go to the shell
3. Create boot entry in EFI firmware (replace ``/dev/sda`` with your disk name and ``-p 1`` with ``/boot/efi`` partition number):
.. code:: bash
efibootmgr -v -c -u -L Qubes -l /EFI/qubes/grubx64.efi -d /dev/sda -p 1
Accessing installer Rescue mode on UEFI
---------------------------------------
Choose “Rescue a Qubes OS system” from grub2 boot menu.