Skip to content

Instantly share code, notes, and snippets.

@moonlitOrca

moonlitOrca/qubes-frameworklaptop-usage-guide.md

Last active February 21, 2024 12:29
Show Gist options
  • Star 4 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save moonlitOrca/be8618e5ca5b6a1c7d9d94a66f1e31de to your computer and use it in GitHub Desktop.
Save moonlitOrca/be8618e5ca5b6a1c7d9d94a66f1e31de to your computer and use it in GitHub Desktop.
Download ZIP
Setting up and tweaking Qubes OS 4.1 and 4.2 on Framework Laptop
Raw
qubes-frameworklaptop-usage-guide.md

Guide to Qubes 4.1 and 4.2 on Framework Laptop

The purpose of this guide is to provide ways to configure not only specifically the Framework laptop, but also to give a new users a leg-up in configuring some fairly common workstation type things that I need to dig around the Internet and Documentation for to set up for myself. Some things are not documented yet anywhere else I could find. I am planning to tweak this and update it as I go to make it as useful and easy as possible for new users in general, but specifically for Framework laptop users as that is what I am using with Qubes OS. My machine is the original 11th generation Framework, but I know most of the hardware is the same in all generations so far so most of this should work for you. I strongly suggest making regular backups of your critical VMs using the handy "Qubes Backup" GUI Tool. I have had to restore more than once.

A couple other users have made useful resources for framework laptops too and I will link a couple of them here, first a guide by another user, and then the HCL reports:
https://gist.github.com/EncryptedGiraffe/39eea9cc7598d09a98711efe7c7a2c89
The HCL reports from the forum for 13th gen and 11th gen:
https://forum.qubes-os.org/t/framework-laptop-13th-gen-intel/20052/10
https://forum.qubes-os.org/t/framework-laptop/7153/31


Build laptop
Since this is a Framework laptop, build first! Instructions are here for the new 13th gen Intel: https://guides.frame.work/Guide/Framework+Laptop+13+DIY+Edition+Quick+Start+Guide/57

Update BIOS
I strongly suggest you do this first, as updating the BIOS via the USB stick method wipes your grub configuration file location from EFI, and so you will dave yourself 15 minutes and an extra step if you do this first!! The most up to date BIOS can be found by searching in a search engine, but for the 11th gen (which is mine) it is here: https://knowledgebase.frame.work/en_us/framework-laptop-bios-releases-S1dMQt6F

You can download the EFI zip file and extract to a FAT32 formatted USB stick to boot from and run. Make sure to plug in your laptop first (but not have the battery at 100% as then the flag that says charging will be toggled off).

It appears Qubes just started to support the typical Linux LVFS fwupdmgr system in version 4.2! (https://www.qubes-os.org/doc/releases/4.2/release-notes/) When I set up 4.1 originally I found a presentation that suggests it had been planned (https://3mdeb.com/wp-content/uploads/2021/06/Status-fwupd_LVFS-support-for-Qubes-OS.pdf). Now it seems to be implemented, but it is very new and I don't kow how it works in Qubes OS yet. I will update this when I learn how.

IF you install Qubes OS before updating BIOS or need to update further down the line..... Flashing the BIOS breaks the bootloader
This can be fixed two different ways. First, on boot, tap F3 repeatedly and select manually your Boot file. Probably /EFI/qubes/grubx64.efi . Then, use efibootmgr to point the boot image back to Qubes. This is from the Qubes Documentation (which is currently out of date on this topic) but updated with my own searching and helpful forum people everywhere: https://www.qubes-os.org/doc/uefi-troubleshooting/#accessing-installer-rescue-mode-on-uefi: First run from dom0 Terminal: lsblk (which lists Block devices on your system). Take note of your drive that has the efi boot partition and the number of that partition. (for me it is nvme0n1 and p1)

According to a couple forum posts and my own testing (https://forum.qubes-os.org/t/cannot-boot-into-qubes-4-1-what-has-changed-in-4-1-boot-routine-uefi/8047/2), (https://forum.qubes-os.org/t/uefi-boot-no-qubes-os-option/4168/5), the new command for 4.1 uses grub2 and should be this (may need to be run with ‘sudo’: efibootmgr -v -c -u -L QubesOS -l /EFI/qubes/grubx64.efi -d /dev/nvme0n1 -p 1

For Qubes 4.0 or older, then run from the dom0 terminal the following command:

Then the command from the documentation was: efibootmgr -v -c -u -L Qubes -l /EFI/qubes/xen.efi -d /dev/nvme0n1 -p 1 "placeholder /mapbs /noexitboot"

If the grub configuration is somehow destroyed, though this should not be the case for the BIOS update, you can rebuild it by verifying that the correct files are in the /boot/efi/EFI/qubes directory and then entering: grub2-mkconfig grub2-install /dev/sda

OR you can copy the Qubes boot directory to the general /boot/efi/EFI/BOOT/ directory. However, this appears to be a workaround for systems that don’t support directly booting from the qubes boot folder, and you will need to redo this process every time you update the kernel or Xen. This post I am making combines the information mentioned in this thread with the Qubes Documentation. https://community.frame.work/t/lost-grub-dual-boot-after-updating-to-bios-3-07/14720/6

Tweak BIOS Settings Certain BIOS settings must be set correctly to ensure Qubes OS works as expected. The BIOS can be entered on boot, by tapping F2 quickly at Framework logo.

  • Disable hyperthreading in BIOS (perhaps helps ‘suspend’ and Qubes doesn’t use hyperthreading). This option is under "CPU Configuration"
  • Disable secure boot (Qubes OS doesn't support it for now)
  • Enable boot from USB (if installing from USB)
  • Be sure to Enable Virtualization extensions VT-x and VT-d. (Qubes runs Virtual Machines!)
  • Many other settings can be tweaked at this time too.

Install Qubes

Press F12 at boot time to choose ‘USB’ to boot Qubes installer (disable secure boot first, as mentioned above!) Install Qubes- I set Fedora as ‘default template’ for compatibility advantage (newer kernel than debian generally, good for hardware support)

Download kernel-latest and update Qubes OS Naturally, you need Intenet access for this. The latest version of Qubes OS (4.2) should support your wifi card (Intel AX210) by default, but the base kernel in 4.1 might not. If this is the case, you may need to connect a USB ethernet adapter and connect to your router via ethernet. Note: for new users, this requires you to connect your ethernet controller to ‘sys-net’ from the device manager.

Download latest kernel:
In dom0 terminal run command: sudo qubes-dom0-update kernel-latest

Download package to make latest kernel available to VMs:
In dom0 terminal run command: sudo qubes-dom0-update kernel-latest

Stop sys-net and sys-usb, to swap these to newer kernel for latest hardware support:
In Qubes Manager GUI, right-click on sys-net and choose properties. Under the advanced tab for the VM change the kernel used to the latest one you see. Repeat this for sys-usb. I don't know if it is needed, but I would suggest a restart here of the system.

Finally, Run graphical updater for Qubes (Salt)!

To enable S3 sleep (deep sleep) on your laptop, you must change the kernel argument as listed below. Qubes OS does not support s0ix sleep (modern standby) yet, but should in version 4.3
In dom0 terminal, edit in your favorite text editor (e.g. nano) file: /etc/default/grub To this line GRUB_CMDLINE_LINUX= (after …..quiet), append at the end mem_sleep_default=deep

Rebuild grub config: in the dom0 terminal sudo grub2-mkconfig -o /boot/grub2/grub.cfg then: initrd sudo dracut -f

You will get this error which is discussed here: https://forum.qubes-os.org/t/about-dracut/13134

You may need to change the default actions on power button and power management timers to “suspend” instead of “hibernate”.

To use Bluetooth Mouse and keyboard: I posted in the forum on this topic here: https://forum.qubes-os.org/t/enabling-bluetooth-on-qubes-r4-1/13916/20
In Qubes 4.1, you must do the following:

  • Connect TemplateVM for your sys-usb to PCI USB controller and wifi card.
  • Install bluez service (may already be there)
  • install blueman.
  • Enable bluetooth service (systemctl enable bluetooth.service)
  • start bluetooth service (systemctl start bluetooth.service).
  • Run Bluetooth Adapters and tell to start automatically.
  • Run Blueman and pair devices in Template VM and tell them to trust.
  • Change Qubes RPC policy file for mouse to read ``sys-usb dom0 ask,user=root,default_target=dom0```
  • This can be done via nano or via echo append sys-usb dom0 ask,user=root,default_target=dom0" >> /etc/qubes-rpc/policy/qubes.InputMouse

In Qubes 4.2, there is a wonderful new tool called “Qubes Global Config”. This tool is available from the new menu system under the “Qubes Tools” category. That allows these settings, so no need for file editing.

Tweak XCFE settings for better usability: The default desktop GUI used in Qubes OS is XFCE. This is NOT my first choice when using Linux, but I have found that if you spend a bit of time tweaking everything, you can indeed make it a nice and very usable experience. You can also instead install KDE as your desktop GUI, and I cover that in a later section.

  • Scaling fonts and things so screen resolution is much better for the Framework In dom0:
    settings | appearance | fonts → increase DPI to 138 or so.
    settings | windowmanager | style → set theme to ‘default-xhdpi’
    In Fedora template: modify file /etc/x11/resources xft.dpi:138
    In Debian templates: modify file /etc/x11/resources/x11-common

To help explain the situation a bit better for new users, I found a post by one of the moderators, Sven, to be extremely useful: (https://forum.qubes-os.org/t/any-way-to-make-everything-on-screen-bigger-without-resolution-change/6842/12)

“our qubes have no idea what DPI/PPI value you use in dom0. If your template do not use a xsettings daemon like gnome-settings-daemon, you are in luck. In that case you simply add the line “Xft.dpi: 138” or whatever your DPI setting is to the respective /etc/X11/Xresources (Fedora) or /etc/X11/Xresources/x11-common (Debian), shutdown the template and restart the qubes based on them and you are done.

The standard Fedora template comes with the Gnome settings daemon installed. This means you have to install e.g. gnome-tweaks in the template and then run it in every single one of your qubes once. In it, under “Fonts” you can set a scaling factor (96 = 1 so in my case 138/96 = 1.44). It’s annoying, but on the upside you only have to do it once per qube.”

  • XFCE Tap-to-click< This is under settings "mouse and keyboard". Select "touchpad" device, and then the general tab should have a checkbox for click on tap.

Fix Screen tearing issues and Video RAM on Intel Chipsets (NOT ON ANY OTHERS): I sourced this from the https://www.qubes-os.org/doc/gui-configuration/ page. This will not be needed whenever Qubes switches to Wayland as a Window Manager, but is needed for X.

  • Open a terminal in dom0
  • Navigate to directory where the file will be written cd /etc/X11/xorg.conf.d/
  • Write the file sudo nano 90-intel.conf
  • Type what’s below into the file 
    Section “Device”
	Identifier “Intel Graphics”
	Driver “intel”
	Option “TearFree” “true”
EndSection

sys-usb RAM tweak that I needed for videoconferencing:

  • Increase sys-usb RAM to 1024 MB in the GUI in order to make smooth video conferencing.

Tweak I made to make docking via Thunderbolt to a 4k monitor work correctly: I needed to increase my video RAM according to this troubleshooting article to prevent desktop resizing issues: https://www.qubes-os.org/doc/gui-troubleshooting/ Commands for Framework (base on Framework display and 4k monitor added [(2256 + 3840) * 2160 * 4 / 1024]
qvm-features dom0 gui-videoram-min $(51435)
qvm-features dom0 gui-videoram-overhead 0

KDE INSTALL: Mostly from this forum: https://forum.qubes-os.org/t/kde-changing-the-way-you-use-qubes/4730/63 and this one: https://forum.qubes-os.org/t/installing-and-running-kde-as-desktop-environment/1513/42 and unman’s documentation: https://github.com/unman/kde Installed SDDM following this page: https://codepre.com/en/como-instalar-gdm-sddm-y-lightdm-display-manager-en-fedora.html

KDE has Night Color integrated and does not need redshift. Just change setting in Settings panel

Once I had used KDE, I needed to change the compositor or I had terrible graphical glitches: I changed the compositing method to xrender from openGL. The openGL framework tended to cause glitching in both its applied versioning.

If you need to add Fedora RPM Fusion repositories: Same as normal instructions on site, except in Qubes the repositories are already added but not enabled. So you need to Enable them as seen here: https://www.qubes-os.org/doc/how-to-install-software/#rpmfusion-for-fedora-templates If you would like to enable the RPM Fusion repositories, open a Terminal of the template and type the following commands, depending on which RPM Fusion repositories you wish to enable (see RPM Fusion for details):

sudo dnf config-manager --set-enabled rpmfusion-free sudo dnf config-manager --set-enabled rpmfusion-free-updates sudo dnf config-manager --set-enabled rpmfusion-nonfree sudo dnf config-manager --set-enabled rpmfusion-nonfree-updates sudo dnf upgrade --refresh This will permanently enable the RPM Fusion repos. If you install software from here, it’s important to keep these repos enabled so that you can receiving future updates. If you only enable these repos temporarily to install a package the Qubes update mechanism may persistently notify you that updates are available, since it cannot download them.

IF YOU DESTROY YOUR TEMPLATE somehow (this is here because I did it...): I did this accidentally when I tried to change Debian stable to testing in Qubes. Something broke the Xen packages and I couldn’t boot that Qube.

Important: This command will roll back any changes made during the last time the template was run, but not before. This means that if you have already restarted the template, using this command is unlikely to help, and you’ll likely want to reinstall it from the repository instead. On the other hand, if the template is already broken or compromised, it won’t hurt to try reverting first. Just make sure to back up all of your data and changes first!

  • Shut down . If you’ve already just shut it down, do not start it again (see above).
  • In a dom0 terminal: qvm-volume revert <template>:root

    • GETTING HDMI AUDIO OUTPUT TO WORK. Requires changing the volume control | configuration | Profile: to Digital Stereo (HDMI) out + Analog Stereo Input if Mic is desired.

    WACOM TABLET CONFIG: This can be done via KDE’s utility named Wacomtablet which can be installed in the following way

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment