From a78075a4429b91aba7e1f1d6ccb1018fd8086605 Mon Sep 17 00:00:00 2001
From: zetigu <81594452+zetigu@users.noreply.github.com>
Date: Thu, 1 Apr 2021 18:18:49 -0400
Subject: [PATCH 01/87] Add instruction for using Btrfs as a qvm-pool

I reformated the article to devide it in 2 section, one concerning LVM pools and the other Btrfs pool.
The synthax should be close to the original.
Awaiting comments.
---
 .../secondary-storage.md                      | 79 ++++++++++++++++++-
 1 file changed, 76 insertions(+), 3 deletions(-)

diff --git a/user/advanced-configuration/secondary-storage.md b/user/advanced-configuration/secondary-storage.md
index 90faca71..8de061cd 100644
--- a/user/advanced-configuration/secondary-storage.md
+++ b/user/advanced-configuration/secondary-storage.md
@@ -20,6 +20,24 @@ You want to store a subset of your AppVMs on the HDD.
 Qubes 4.0 is more flexible than earlier versions about placing different VMs on different disks.
 For example, you can keep templates on one disk and AppVMs on another, without messy symlinks.
 
+You can query qvm-pool to list available storage drivers.
+
+```
+qvm-pool --help-drivers
+```
+qvm-pool driver explaination :
+```
+<file> refers to using a simple file for image storage and lacks a few features.
+<file-reflink> refers to storing images on a filesystem supporting copy on write.
+<linux-kernel> refers to a directory holding kernel images.
+<lvm_thin> refers to LVM managed pools.
+```
+In theory, you can still use file-based disk images ("file" pool driver), but it lacks some features such as you won't be able to do backups without shutting down the qube.
+
+Additionnal storage can also be added on a Btrfs filesystem. A unique feature of Btrfs over LVM is that data can be compressed transparently. The subvolume can also be backuped using snapshots for an other layer protection and Btrfs supports different level of redundancy and is able to be expanded/shrinked easily. Revelant information will be provided after LVM section.
+
+### LVM storage
+
 These steps assume you have already created a separate [volume group](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/logical_volume_manager_administration/vg_admin#VG_create) and [thin pool](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/logical_volume_manager_administration/thinly_provisioned_volume_creation) (not thin volume) for your HDD.
 See also [this example](https://www.linux.com/blog/how-full-encrypt-your-linux-system-lvm-luks) if you would like to create an encrypted LVM pool (but note you can use a single logical volume if preferred, and to use the `-T` option on `lvcreate` to specify it is thin). You can find the commands for this example applied to Qubes at the bottom of this R4.0 section.
 
@@ -39,6 +57,24 @@ Take note of the VG and thin pool names for your HDD, then register it with Qube
 qvm-pool --add <pool_name> lvm_thin -o volume_group=<vg_name>,thin_pool=<thin_pool_name>,revisions_to_keep=2
 ```
 
+### BTRFS storage
+Theses steps assume you have already created a separate Btrfs filesystem for your HDD, that it is encrypted with LUKS and it is mounted. It is recommended to use a subvolume as it enables compression and excess storage can be use for other things.
+
+
+It is possible to use already available Btrfs storage if it is configured. In dom0, available Btrfs storage can be displayed using :
+```
+mount -t btrfs
+```
+To register the storage to qubes :
+
+```shell_session
+# <pool_name> is a freely chosen pool name
+# <dir_path> is the mounted path to the second btrfs storage
+qvm-pool --add <pool_name> file-reflink -o dir_path=<dir_path>,revisions_to_keep=2
+```
+
+#### Using the new pool
+
 Now, you can create qubes in that pool:
 
 ```
@@ -59,9 +95,7 @@ For example:
 qvm-prefs <appvmname_based_on_old_template> template <new_template_name>
 ```
 
-In theory, you can still use file-based disk images ("file" pool driver), but it lacks some features such as you won't be able to do backups without shutting down the qube.
-
-### Example HDD setup
+#### Example HDD setup
 
 Assuming the secondary hard disk is at /dev/sdb (it will be completely erased), you can set it up for encryption by doing in a dom0 terminal (use the same passphrase as the main Qubes disk to avoid a second password prompt at boot):
 
@@ -84,6 +118,8 @@ luks-b20975aa-8318-433d-8508-6c23982c6cde UUID=b20975aa-8318-433d-8508-6c23982c6
 
 Reboot the computer so the new luks device appears at /dev/mapper/luks-b209... and we can then create its pool, by doing this on a dom0 terminal (substitute the b209... UUIDs with yours):
 
+##### For LVM
+
 First create the physical volume
 
 ```
@@ -107,6 +143,40 @@ Finally we will tell Qubes to add a new pool on the just created thin pool
 ```
 qvm-pool --add poolhd0_qubes lvm_thin -o volume_group=qubes,thin_pool=poolhd0,revisions_to_keep=2
 ```
+#### For Btrfs
+
+First create the physical volume
+
+```
+# <label> Btrfs Label
+sudo mkfs.btrfs -L <label> /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde
+```
+
+Then mount the new Btrfs to a temporary path
+
+```
+sudo mount /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde /mnt/new_qube_storage
+```
+Create a subvolume to hold the data. 
+```
+sudo btrfs subvolume create /mnt/new_qube_storage/qubes
+```
+Unmount the temporary Btrfs filesystem
+```
+sudo umount /mnt/new_qube_storage
+```
+Mount the subvolume with compression enabled if desired
+```
+# <compression> zlib|lzo|zstd
+# <subvol> btrfs subvolume "qubes" in this example
+sudo mount /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde /var/lib/qubes_newpool -o compress=<compression>,subvol=qubes
+```
+
+Finally we will tell Qubes to add a new pool on the just created Btrfs subvolume
+
+```
+qvm-pool --add poolhd0_qubes file-reflink -o dir_path=/var/lib/qubes_newpool,revisions_to_keep=2
+```
 
 By default VMs will be created on the main Qubes disk (i.e. a small SSD), to create them on this secondary HDD do the following on a dom0 terminal:
 
@@ -114,5 +184,8 @@ By default VMs will be created on the main Qubes disk (i.e. a small SSD), to cre
 qvm-create -P poolhd0_qubes --label red unstrusted-hdd
 ```
 
+Verify that corresponding lines to /etc/fstab and /etc/cryptab where added to enable auto mounting of the new pool.
+
+
 [Qubes Backup]: /doc/BackupRestore/
 [TemplateVM]: /doc/Templates/

From 8de70db07872ca1f874a384390adc3c8b9d522b0 Mon Sep 17 00:00:00 2001
From: zetigu <81594452+zetigu@users.noreply.github.com>
Date: Fri, 2 Apr 2021 08:46:44 -0400
Subject: [PATCH 02/87] Clarification in introduction

More descriptive advantages of using Btrfs
---
 user/advanced-configuration/secondary-storage.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/user/advanced-configuration/secondary-storage.md b/user/advanced-configuration/secondary-storage.md
index 8de061cd..fd0594f2 100644
--- a/user/advanced-configuration/secondary-storage.md
+++ b/user/advanced-configuration/secondary-storage.md
@@ -34,7 +34,7 @@ qvm-pool driver explaination :
 ```
 In theory, you can still use file-based disk images ("file" pool driver), but it lacks some features such as you won't be able to do backups without shutting down the qube.
 
-Additionnal storage can also be added on a Btrfs filesystem. A unique feature of Btrfs over LVM is that data can be compressed transparently. The subvolume can also be backuped using snapshots for an other layer protection and Btrfs supports different level of redundancy and is able to be expanded/shrinked easily. Revelant information will be provided after LVM section.
+Additionnal storage can also be added on a Btrfs filesystem. A unique feature of Btrfs over LVM is that data can be compressed transparently. The subvolume can also be backuped using snapshots for an additionnal layer of protection; Btrfs supports differents level of redundancy; it has parity checksum; it is able to be expanded/shrinked. Starting/stoping a VM has less impact and less chances of causing slowdown of the system as some have noted with LVM. Revelant information for general btrfs configuration will be provided after LVM section.
 
 ### LVM storage
 

From 6479d371b9a311f6ea1ffc83b54177311b8bb84f Mon Sep 17 00:00:00 2001
From: zetigu <81594452+zetigu@users.noreply.github.com>
Date: Fri, 2 Apr 2021 08:50:03 -0400
Subject: [PATCH 03/87] Add shell_session to terminal box

Added a shell_session to the ``` of the first line.
---
 .../secondary-storage.md                      | 40 +++++++++----------
 1 file changed, 20 insertions(+), 20 deletions(-)

diff --git a/user/advanced-configuration/secondary-storage.md b/user/advanced-configuration/secondary-storage.md
index fd0594f2..c5fd4248 100644
--- a/user/advanced-configuration/secondary-storage.md
+++ b/user/advanced-configuration/secondary-storage.md
@@ -22,11 +22,11 @@ For example, you can keep templates on one disk and AppVMs on another, without m
 
 You can query qvm-pool to list available storage drivers.
 
-```
+``` shell_session
 qvm-pool --help-drivers
 ```
 qvm-pool driver explaination :
-```
+```shell_session
 <file> refers to using a simple file for image storage and lacks a few features.
 <file-reflink> refers to storing images on a filesystem supporting copy on write.
 <linux-kernel> refers to a directory holding kernel images.
@@ -43,7 +43,7 @@ See also [this example](https://www.linux.com/blog/how-full-encrypt-your-linux-s
 
 First, collect some information in a dom0 terminal:
 
-```
+```shell_session
 sudo pvs
 sudo lvs
 ```
@@ -62,7 +62,7 @@ Theses steps assume you have already created a separate Btrfs filesystem for you
 
 
 It is possible to use already available Btrfs storage if it is configured. In dom0, available Btrfs storage can be displayed using :
-```
+```shell_session
 mount -t btrfs
 ```
 To register the storage to qubes :
@@ -77,13 +77,13 @@ qvm-pool --add <pool_name> file-reflink -o dir_path=<dir_path>,revisions_to_keep
 
 Now, you can create qubes in that pool:
 
-```
+```shell_session
 qvm-create -P <pool_name> --label red <vmname>
 ```
 
 It isn't possible to directly migrate an existing qube to the new pool, but you can clone it there, then remove the old one:
 
-```
+```shell_session
 qvm-clone -P <pool_name> <sourceVMname> <cloneVMname>
 qvm-remove <sourceVMname>
 ```
@@ -91,7 +91,7 @@ qvm-remove <sourceVMname>
 If that was a template, or other qube referenced elsewhere (NetVM or such), you will need to adjust those references manually after moving.
 For example:
 
-```
+```shell_session
 qvm-prefs <appvmname_based_on_old_template> template <new_template_name>
 ```
 
@@ -99,20 +99,20 @@ qvm-prefs <appvmname_based_on_old_template> template <new_template_name>
 
 Assuming the secondary hard disk is at /dev/sdb (it will be completely erased), you can set it up for encryption by doing in a dom0 terminal (use the same passphrase as the main Qubes disk to avoid a second password prompt at boot):
 
-```
+```shell_session
 sudo cryptsetup luksFormat --hash=sha512 --key-size=512 --cipher=aes-xts-plain64 --verify-passphrase /dev/sdb
 sudo blkid /dev/sdb
 ```
 
 Note the device's UUID (in this example "b209..."), we will use it as its luks name for auto-mounting at boot, by doing:
 
-```
+```shell_session
 sudo nano /etc/crypttab
 ```
 
 And adding this line (change both "b209..." for your device's UUID from blkid) to crypttab:
 
-```
+```shell_session
 luks-b20975aa-8318-433d-8508-6c23982c6cde UUID=b20975aa-8318-433d-8508-6c23982c6cde none
 ```
 
@@ -122,39 +122,39 @@ Reboot the computer so the new luks device appears at /dev/mapper/luks-b209... a
 
 First create the physical volume
 
-```
+```shell_session
 sudo pvcreate /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde
 ```
 
 Then create the LVM volume group, we will use for example "qubes" as the <vg_name>:
 
-```
+```shell_session
 sudo vgcreate qubes /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde
 ```
 
 And then use "poolhd0" as the <thin_pool_name> (LVM thin pool name):
 
-```
+```shell_session
 sudo lvcreate -T -n poolhd0 -l +100%FREE qubes
 ```
 
 Finally we will tell Qubes to add a new pool on the just created thin pool
 
-```
+```shell_session
 qvm-pool --add poolhd0_qubes lvm_thin -o volume_group=qubes,thin_pool=poolhd0,revisions_to_keep=2
 ```
 #### For Btrfs
 
 First create the physical volume
 
-```
+```shell_session
 # <label> Btrfs Label
 sudo mkfs.btrfs -L <label> /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde
 ```
 
 Then mount the new Btrfs to a temporary path
 
-```
+```shell_session
 sudo mount /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde /mnt/new_qube_storage
 ```
 Create a subvolume to hold the data. 
@@ -162,11 +162,11 @@ Create a subvolume to hold the data.
 sudo btrfs subvolume create /mnt/new_qube_storage/qubes
 ```
 Unmount the temporary Btrfs filesystem
-```
+```shell_session
 sudo umount /mnt/new_qube_storage
 ```
 Mount the subvolume with compression enabled if desired
-```
+```shell_session
 # <compression> zlib|lzo|zstd
 # <subvol> btrfs subvolume "qubes" in this example
 sudo mount /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde /var/lib/qubes_newpool -o compress=<compression>,subvol=qubes
@@ -174,13 +174,13 @@ sudo mount /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde /var/lib/qubes_
 
 Finally we will tell Qubes to add a new pool on the just created Btrfs subvolume
 
-```
+```shell_session
 qvm-pool --add poolhd0_qubes file-reflink -o dir_path=/var/lib/qubes_newpool,revisions_to_keep=2
 ```
 
 By default VMs will be created on the main Qubes disk (i.e. a small SSD), to create them on this secondary HDD do the following on a dom0 terminal:
 
-```
+```shell_session
 qvm-create -P poolhd0_qubes --label red unstrusted-hdd
 ```
 

From 32e728d8a95285bcc96e1c171ff0cf0aacef2dcb Mon Sep 17 00:00:00 2001
From: zetigu <81594452+zetigu@users.noreply.github.com>
Date: Fri, 2 Apr 2021 08:51:33 -0400
Subject: [PATCH 04/87] Add btrfs filesystem show line

Added one btrfs filesystem show line for displaying available btrfs filesystems.
---
 user/advanced-configuration/secondary-storage.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/user/advanced-configuration/secondary-storage.md b/user/advanced-configuration/secondary-storage.md
index c5fd4248..3fbf22b1 100644
--- a/user/advanced-configuration/secondary-storage.md
+++ b/user/advanced-configuration/secondary-storage.md
@@ -64,6 +64,7 @@ Theses steps assume you have already created a separate Btrfs filesystem for you
 It is possible to use already available Btrfs storage if it is configured. In dom0, available Btrfs storage can be displayed using :
 ```shell_session
 mount -t btrfs
+btrfs show filesystem
 ```
 To register the storage to qubes :
 

From 75d18931d11ba8c634b5710ad37d365667a8764b Mon Sep 17 00:00:00 2001
From: zetigu <81594452+zetigu@users.noreply.github.com>
Date: Fri, 2 Apr 2021 09:00:36 -0400
Subject: [PATCH 05/87] Normalize punctuation and create/remove tmp dir

Mostly fix before console text by using ":" without space.
Create/remove /mnt/new_qube_storage
---
 .../secondary-storage.md                      | 27 ++++++++++---------
 1 file changed, 14 insertions(+), 13 deletions(-)

diff --git a/user/advanced-configuration/secondary-storage.md b/user/advanced-configuration/secondary-storage.md
index 3fbf22b1..eedf2526 100644
--- a/user/advanced-configuration/secondary-storage.md
+++ b/user/advanced-configuration/secondary-storage.md
@@ -20,12 +20,12 @@ You want to store a subset of your AppVMs on the HDD.
 Qubes 4.0 is more flexible than earlier versions about placing different VMs on different disks.
 For example, you can keep templates on one disk and AppVMs on another, without messy symlinks.
 
-You can query qvm-pool to list available storage drivers.
+You can query qvm-pool to list available storage drivers:
 
 ``` shell_session
 qvm-pool --help-drivers
 ```
-qvm-pool driver explaination :
+qvm-pool driver explaination:
 ```shell_session
 <file> refers to using a simple file for image storage and lacks a few features.
 <file-reflink> refers to storing images on a filesystem supporting copy on write.
@@ -61,12 +61,12 @@ qvm-pool --add <pool_name> lvm_thin -o volume_group=<vg_name>,thin_pool=<thin_po
 Theses steps assume you have already created a separate Btrfs filesystem for your HDD, that it is encrypted with LUKS and it is mounted. It is recommended to use a subvolume as it enables compression and excess storage can be use for other things.
 
 
-It is possible to use already available Btrfs storage if it is configured. In dom0, available Btrfs storage can be displayed using :
+It is possible to use already available Btrfs storage if it is configured. In dom0, available Btrfs storage can be displayed using:
 ```shell_session
 mount -t btrfs
 btrfs show filesystem
 ```
-To register the storage to qubes :
+To register the storage to qubes:
 
 ```shell_session
 # <pool_name> is a freely chosen pool name
@@ -121,8 +121,7 @@ Reboot the computer so the new luks device appears at /dev/mapper/luks-b209... a
 
 ##### For LVM
 
-First create the physical volume
-
+First create the physical volume:
 ```shell_session
 sudo pvcreate /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde
 ```
@@ -139,41 +138,43 @@ And then use "poolhd0" as the <thin_pool_name> (LVM thin pool name):
 sudo lvcreate -T -n poolhd0 -l +100%FREE qubes
 ```
 
-Finally we will tell Qubes to add a new pool on the just created thin pool
+Finally we will tell Qubes to add a new pool on the just created thin pool:
 
 ```shell_session
 qvm-pool --add poolhd0_qubes lvm_thin -o volume_group=qubes,thin_pool=poolhd0,revisions_to_keep=2
 ```
 #### For Btrfs
 
-First create the physical volume
+First create the physical volume:
 
 ```shell_session
 # <label> Btrfs Label
 sudo mkfs.btrfs -L <label> /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde
 ```
 
-Then mount the new Btrfs to a temporary path
+Then mount the new Btrfs to a temporary path:
 
 ```shell_session
+sudo mkdir -p /mnt/new_qube_storage
 sudo mount /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde /mnt/new_qube_storage
 ```
-Create a subvolume to hold the data. 
+Create a subvolume to hold the data:
 ```
 sudo btrfs subvolume create /mnt/new_qube_storage/qubes
 ```
-Unmount the temporary Btrfs filesystem
+Unmount the temporary Btrfs filesystem:
 ```shell_session
 sudo umount /mnt/new_qube_storage
+rmdir /mnt/new_qube_storage
 ```
-Mount the subvolume with compression enabled if desired
+Mount the subvolume with compression enabled if desired:
 ```shell_session
 # <compression> zlib|lzo|zstd
 # <subvol> btrfs subvolume "qubes" in this example
 sudo mount /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde /var/lib/qubes_newpool -o compress=<compression>,subvol=qubes
 ```
 
-Finally we will tell Qubes to add a new pool on the just created Btrfs subvolume
+Finally we will tell Qubes to add a new pool on the just created Btrfs subvolume:
 
 ```shell_session
 qvm-pool --add poolhd0_qubes file-reflink -o dir_path=/var/lib/qubes_newpool,revisions_to_keep=2

From dc0819594baa7b2e4ecb28672495e49ba975cb04 Mon Sep 17 00:00:00 2001
From: qubesbugreport <112062467+qubesbugreport@users.noreply.github.com>
Date: Thu, 1 Sep 2022 07:32:52 +0200
Subject: [PATCH 06/87] Use sentence case instead of title case

As required by the style guide
---
 user/how-to-guides/how-to-use-usb-devices.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/user/how-to-guides/how-to-use-usb-devices.md b/user/how-to-guides/how-to-use-usb-devices.md
index e515231f..c3db0601 100644
--- a/user/how-to-guides/how-to-use-usb-devices.md
+++ b/user/how-to-guides/how-to-use-usb-devices.md
@@ -28,9 +28,9 @@ Examples of valid cases for USB-passthrough:
 (If you are thinking to use a two-factor-authentication device, [there is an app for that](/doc/u2f-proxy/).
 But it has some [issues](https://github.com/QubesOS/qubes-issues/issues/4661).)
 
-## Attaching And Detaching a USB Device
+## Attaching and detaching a USB device
 
-### With Qubes Device Manager
+### With Qubes device manager
 
 Click the device-manager-icon: ![device manager icon](/attachment/doc/media-removable.png)
 A list of available devices appears.
@@ -48,7 +48,7 @@ Hover on the attached device to display a list of running VMs.
 The one to which your device is connected will have an eject button ![eject icon](/attachment/doc/media-eject.png) next to it.
 Click that and your device will be detached.
 
-### With The Command Line Tool
+### With the command line tool
 
 In dom0, you can use `qvm-usb` from the commandline to attach and detach devices.
 
@@ -87,14 +87,14 @@ sys-usb:2-5     058f:3822 058f_USB_2.0_Camera
 sys-usb:2-1     03f0:0641 PixArt_Optical_Mouse
 ```
 
-## Maintenance And Customisation
+## Maintenance and customisation
 
-### Creating And Using a USB qube
+### Creating and using a USB qube
 
 If you've selected to install a usb-qube during system installation, everything is already set up for you in `sys-usb`.
 If you've later decided to create a usb-qube, please follow [this guide](/doc/usb-qubes/).
 
-### Installation Of `qubes-usb-proxy`
+### Installation of `qubes-usb-proxy`
 
 To use this feature, the `qubes-usb-proxy` package needs to be installed in the templates used for the USB qube and qubes you want to connect USB devices to.
 This section exists for reference or in case something broke and you need to reinstall `qubes-usb-proxy`.
@@ -111,13 +111,13 @@ If you receive this error: `ERROR: qubes-usb-proxy not installed in the VM`, you
   sudo apt-get install qubes-usb-proxy
   ```
 
-### Using USB Keyboards And Other Input Devices
+### Using USB keyboards and other input devices
 
 **Warning:** especially keyboards need to be accepted by default when using them to login! Please make sure you carefully read and understood the **[security considerations](/doc/device-handling-security/#usb-security)** before continuing!
 
 Mouse and keyboard setup are part of [setting up a USB qube](/doc/usb-qubes/).
 
-### Finding The Right USB Controller
+### Finding the right USB controller
 
 Some USB devices are not compatible with the USB pass-through method Qubes employs.
 In situations like these, you can try to pass through the entire USB controller to a qube as PCI device.

From 2b24640962d12880aa91c93a478d0b71d4553444 Mon Sep 17 00:00:00 2001
From: qubesbugreport <112062467+qubesbugreport@users.noreply.github.com>
Date: Thu, 1 Sep 2022 08:00:33 +0200
Subject: [PATCH 07/87] Add instructions for using Qube Manager

Using the Qube Manager to determine USB controller and address
---
 user/how-to-guides/how-to-use-usb-devices.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/user/how-to-guides/how-to-use-usb-devices.md b/user/how-to-guides/how-to-use-usb-devices.md
index c3db0601..f845f89e 100644
--- a/user/how-to-guides/how-to-use-usb-devices.md
+++ b/user/how-to-guides/how-to-use-usb-devices.md
@@ -123,6 +123,10 @@ Some USB devices are not compatible with the USB pass-through method Qubes emplo
 In situations like these, you can try to pass through the entire USB controller to a qube as PCI device.
 However, with this approach one cannot attach single USB devices but has to attach the whole USB controller with whatever USB devices are connected to it.
 
+You can find your controller and its BDF address using either of two methods described below. Using the command-line tools lsusb and readlink or by using the Qube Manager GUI. It is possible that on some system configurations the readlink method produces output which is different from the example below, while the Qube Manager method allows one to easily determine the correct controller and BDF address.
+
+#### Method 1: Using lsusb and readlink
+
 If you have multiple USB controllers, you must first figure out which PCI device is the right controller.
 
 First, find out which USB bus the device is connected to (note that these steps need to be run from a terminal inside your USB qube):
@@ -155,6 +159,8 @@ This should output something like:
 ../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
 ```
 
+If the output format does not match this example, or you are unsure if it contains the correct BDF address, you can try finding the address using method 2 using the Qube Manager instead.
+
 Now you see the path and the text between `/pci0000:00/0000:` and `/usb3` i.e. `00:1a.0` is the BDF address. Strip the address and pass it to the [`qvm-pci` tool](/doc/how-to-use-pci-devices/) to attach the controller to the targetVM.
 
 For example, On R 4.0 the command would look something like
@@ -162,3 +168,17 @@ For example, On R 4.0 the command would look something like
 ```
 qvm-pci attach --persistent personal dom0:00_1a.0
 ```
+
+#### Method 2: Using the Qube Manager
+
+Open the Qube Manager, then right click on one of the VMs and open the settings. Go to the tab "Devices".
+
+Here you should see your available devices along with their BDF addresses. Look for the lines containing "USB controller".
+
+They should look something like: `01:00.0 USB controller: Name of manufacturer`
+
+The first part is the BDF address, in this example: `01:00.0`
+
+If, for example, you have 2 USB controllers in your system because you added one you should see 2 such lines and you can probably guess which controller is the one on the mainboard and which one you added. For example, if you have a mainboard with an Intel chipset, it is possible that all of the mainboard devices show as "Intel Corporation" while the added controller shows another name of manufacturer.
+
+Now you should be able to tell which is the correct BDF address of the mainboard USB controller or the added USB controller.

From 9eb7926ffe515a044d0f4ec31ca9eecb5c54bc09 Mon Sep 17 00:00:00 2001
From: Andrew David Wong <adw@qubes-os.org>
Date: Wed, 23 Nov 2022 17:34:08 -0800
Subject: [PATCH 08/87] Update and improve Emergency backup restore v4 page

- Update formatting and style to be consistent with the rest of the docs
- Improve language
- Clarify instructions
- Improve organization
---
 .../backup-emergency-restore-v4.md            | 109 ++++++++----------
 1 file changed, 47 insertions(+), 62 deletions(-)

diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md
index 19367a24..38df4b12 100644
--- a/user/how-to-guides/backup-emergency-restore-v4.md
+++ b/user/how-to-guides/backup-emergency-restore-v4.md
@@ -12,13 +12,17 @@ title: Emergency backup recovery (v4)
 This page describes how to perform an emergency restore of a backup created on
 Qubes R4.X (which uses backup format version 4).
 
-The Qubes backup system has been designed with emergency disaster recovery in
-mind. No special Qubes-specific tools are required to access data backed up by
-Qubes. In the event a Qubes system is unavailable, you can access your data on
-any GNU/Linux system with the following procedure.
+The Qubes backup system is designed with emergency disaster recovery in mind. No
+special Qubes-specific tools are required to access data backed up by Qubes. In
+the event a Qubes system is unavailable, you can access your data on any
+GNU/Linux system by following the instructions on this page.
 
-Required `scrypt` Utility
--------------------------
+**Important:** You may wish to store a copy of these instructions with your
+Qubes backups. All Qubes documentation, including this page, is available in
+plain text format in the the [qubes-doc](https://github.com/QubesOS/qubes-doc)
+Git repository.
+
+## Required `scrypt` utility
 
 In Qubes 4.X, backups are encrypted and integrity-protected with
 [scrypt](https://www.tarsnap.com/scrypt.html). You will need a copy of this
@@ -34,8 +38,8 @@ easier scripting, which means you'll need to enter the passphrase for each file
 separately, instead of using `echo ... | scrypt`.
 
 Here are instructions for obtaining a compiled `scrypt` binary. This example
-uses an RPM-based system (Fedora), but the same general procedure should work
-on any GNU/Linux system.
+uses an RPM-based system (Fedora), but the same general procedure should work on
+any GNU/Linux system.
 
  1. If you're not on Qubes 4.X, [import and authenticate the Release 4 Signing
     Key](/security/verifying-signatures/#how-to-import-and-authenticate-release-signing-keys).
@@ -46,7 +50,7 @@ on any GNU/Linux system.
 
         [user@restore ~]$ dnf download scrypt
 
-    or, if that doesn't work:
+    Or, if that doesn't work:
 
         [user@restore ~]$ curl -O https://yum.qubes-os.org/r4.0/current/vm/fc28/rpm/scrypt-1.2.1-1.fc28.x86_64.rpm
 
@@ -66,17 +70,19 @@ on any GNU/Linux system.
 
         [user@restore ~]$ rpmdev-extract scrypt-*.rpm
 
- 6. (Optional) Create an alias for the new binary.
-
-        [user@restore ~]$ alias scrypt="scrypt-*/usr/bin/scrypt"
-
-Emergency Recovery Instructions
--------------------------------
+## Emergency recovery instructions
 
 **Note:** In the following example, the backup file is both *encrypted* and
 *compressed*.
 
- 1. Untar the main backup file.
+ 1. (Optional) If you're working with binaries that you saved with your backup,
+    such as `scrypt` or `bzip2`, you can make things easier by aliasing those
+    binaries now, e.g.,
+
+        [user@restore ~]$ alias scrypt="/home/user/scrypt-*"
+        [user@restore ~]$ alias bzip2="/home/user/bzip2-*"
+
+ 2. Untar the main backup file.
 
         [user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456
         backup-header
@@ -90,32 +96,15 @@ Emergency Recovery Instructions
         vm1/whitelisted-appmenus.list.000.enc
         dom0-home/dom0user.000.enc
 
-    **To extract only specific VMs:** Each VM in the backup file has its path
-    listed in `qubes.xml.000.enc`. Decrypt it. (In this example, the password is
-    `password`.)
-
-        [user@restore ~]$ cat backup-header | grep backup-id
-        backup-id=20190128T123456-1234
-        [user@restore ~]$ scrypt dec -P qubes.xml.000.enc qubes.xml.000
-        Please enter passphrase: 20190128T123456-1234!qubes.xml.000!password
-        [user@restore ~]$ tar -i -xvf qubes.xml.000
-
-    Now that you have the decrypted `qubes.xml.000` file, search for the
-    `backup-path` property inside of it. With the `backup-path`, extract only
-    the files necessary for your VM (`vmX`).
-
-        [user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456 \
-            backup-header backup-header.hmac vmX/
-
- 2. Set the backup passphrase environment variable. While this isn't strictly
-    required, it will be handy later and will avoid saving the passphrase in
-    the shell's history.
+ 3. Set the backup passphrase environment variable. While this isn't strictly
+    required, it will be handy later and will avoid saving the passphrase in the
+    shell's history.
 
         [user@restore ~]$ read -r backup_pass
 
- 3. Verify the integrity of `backup-header`. For compatibility reasons,
-    `backup-header.hmac` is an encrypted *and integrity protected*
-    version of `backup-header`.
+ 4. Verify the integrity of `backup-header`. For compatibility reasons,
+    `backup-header.hmac` is an encrypted *and integrity protected* version of
+    `backup-header`.
 
         [user@restore ~]$ set +H
         [user@restore ~]$ echo "backup-header!$backup_pass" |\
@@ -123,28 +112,31 @@ Emergency Recovery Instructions
             diff -qs backup-header backup-header.verified
         Files backup-header and backup-header.verified are identical
 
-    **Note:** If this command fails, it may be that the backup was tampered
-    with or is in a different format. In the latter case, look inside
-    `backup-header` at the `version` field. If it contains a value other than
-    `version=4`, go to the instructions for that format version:
+    **Note:** If this command fails, it may be that the backup was tampered with
+    or is in a different format. In the latter case, look inside `backup-header`
+    at the `version` field. If it contains a value other than `version=4`, go to
+    the instructions for that format version:
     - [Emergency Backup Recovery without Qubes (v2)](/doc/backup-emergency-restore-v2/)
     - [Emergency Backup Recovery without Qubes (v3)](/doc/backup-emergency-restore-v3/)
 
- 4. Read `backup-header`:
+ 5. Read `backup-header`.
 
         [user@restore ~]$ cat backup-header
         version=4
         encrypted=True
         compressed=True
         compression-filter=gzip
-        backup_id=20161020T123455-1234
+        hmac-algorithm=scrypt
+        backup-id=20161020T123455-1234
 
- 5. Set `backup_id` to the value in the last line of `backup-header`:
+ 6. Set `backup_id` to the value in the last line of `backup-header`. (Note that
+    there is a hyphen in `backup-id` in the file, whereas there is an underscore
+    in `backup_id` in the variable you're setting.)
 
         [user@restore ~]$ backup_id=20161020T123455-1234
 
- 6. Verify the integrity of your data, decrypt, decompress, and extract
-    `private.img`:
+ 7. Choose a qube whose data you wish to restore. Verify the data's integrity,
+    decrypt it, decompress it, and extract it.
 
         [user@restore ~]$ find vm1 -name 'private.img.*.enc' | sort -V | while read f_enc; do \
             f_dec=${f_enc%.enc}; \
@@ -157,24 +149,17 @@ Emergency Recovery Instructions
 
     **Note:** If your backup was compressed with a program other than `gzip`,
     you must substitute the correct compression program in the command above.
-    This information is contained in `backup-header` (see step 4). For example,
-    if your backup is compressed with `bzip2`, use `bzip2 -d` instead in the
-    command above.
+    This information is contained in `backup-header` (see step 5). For example,
+    if your backup is compressed with `bzip2`, use `bzip2 -d` instead of `gzip
+    -d` in the command above.
 
- 7. Mount `private.img` and access your data.
+ 8. Enter the decrypted directory, mount `private.img`, and access your data.
 
+        [user@restore ~]$ cd vm1/
         [user@restore vm1]$ sudo mkdir /mnt/img
         [user@restore vm1]$ sudo mount -o loop vm1/private.img /mnt/img/
         [user@restore vm1]$ cat /mnt/img/home/user/your_data.txt
         This data has been successfully recovered!
 
- 8. Success! If you wish to recover data from more than one VM in your backup,
-    simply repeat steps 6 and 7 for each additional VM.
-
-    **Note:** You may wish to store a copy of these instructions with your
-    Qubes backups in the event that you fail to recall the above procedure
-    while this web page is inaccessible. All Qubes documentation, including
-    this page, is available in plain text format in the following Git
-    repository:
-
-        https://github.com/QubesOS/qubes-doc.git
+Success! If you wish to recover data from more than one qube in your backup,
+simply repeat steps 7 and 8 for each additional qube.

From b6c99d486bf7fb38f9958dabb56107cf20223e7d Mon Sep 17 00:00:00 2001
From: Andrew David Wong <adw@qubes-os.org>
Date: Wed, 23 Nov 2022 17:53:29 -0800
Subject: [PATCH 09/87] Fix typo

---
 user/how-to-guides/backup-emergency-restore-v4.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md
index 38df4b12..026de11f 100644
--- a/user/how-to-guides/backup-emergency-restore-v4.md
+++ b/user/how-to-guides/backup-emergency-restore-v4.md
@@ -19,8 +19,8 @@ GNU/Linux system by following the instructions on this page.
 
 **Important:** You may wish to store a copy of these instructions with your
 Qubes backups. All Qubes documentation, including this page, is available in
-plain text format in the the [qubes-doc](https://github.com/QubesOS/qubes-doc)
-Git repository.
+plain text format in the [qubes-doc](https://github.com/QubesOS/qubes-doc) Git
+repository.
 
 ## Required `scrypt` utility
 

From 39342e8c98066603839d7f77ce0416e4af439b75 Mon Sep 17 00:00:00 2001
From: Andrew David Wong <adw@qubes-os.org>
Date: Wed, 23 Nov 2022 17:55:04 -0800
Subject: [PATCH 10/87] Clarify example

---
 user/how-to-guides/backup-emergency-restore-v4.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md
index 026de11f..1caa526b 100644
--- a/user/how-to-guides/backup-emergency-restore-v4.md
+++ b/user/how-to-guides/backup-emergency-restore-v4.md
@@ -135,8 +135,8 @@ any GNU/Linux system.
 
         [user@restore ~]$ backup_id=20161020T123455-1234
 
- 7. Choose a qube whose data you wish to restore. Verify the data's integrity,
-    decrypt it, decompress it, and extract it.
+ 7. Choose a qube whose data you wish to restore (in this example, `vm1`).
+    Verify the data's integrity, decrypt it, decompress it, and extract it.
 
         [user@restore ~]$ find vm1 -name 'private.img.*.enc' | sort -V | while read f_enc; do \
             f_dec=${f_enc%.enc}; \

From c5314bed7f3001996c10458145cc5ba4a0ebaad8 Mon Sep 17 00:00:00 2001
From: zenkuro <42751749+zenkuro@users.noreply.github.com>
Date: Thu, 5 Jan 2023 22:57:18 -0500
Subject: [PATCH 11/87] Eetend VPN troubleshooting by notify-send case

There are guides and scripts on internet that are helping to configure and run VPN service on QubesOS
This record provides explanation how to identify and what to do to fix possible issues with notify-send that being used by this guides.
---
 user/troubleshooting/vpn-troubleshooting.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/user/troubleshooting/vpn-troubleshooting.md b/user/troubleshooting/vpn-troubleshooting.md
index d63bbe0c..d06eb5d1 100644
--- a/user/troubleshooting/vpn-troubleshooting.md
+++ b/user/troubleshooting/vpn-troubleshooting.md
@@ -31,3 +31,20 @@ After suspend/resume, OpenVPN may not automatically reconnect. In order to get i
 After setting up OpenVPN and restarting the VM, you may be repeatedly getting the popup "Ready to start link", but the VPN isn't connected.
 
 To figure out the root of the problem, check the VPN logs in `/var/logs/syslog`. The log may reveal issues like missing OpenVPN libraries, which you can then install.
+
+## `notify-send` induced failure
+[Some VPN guides](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md) use complex scripts that by themselves include call of `notify-send`, yet some images may not contain this tool or may not have it working properly.
+For instance calling `notify-send` on `fedora-36` template VM gives:
+```
+Failed to execute child process “dbus-launch” (No such file or directory)
+```
+
+To check this tool is working properly run:
+```bash
+sudo notify-send "$(hostname): Test notify-send OK" --icon=network-idle
+```
+You should see `info` message appear on the top of your scree.
+If that is the case then, `notify-send` is not the issue.
+If it is not, and you have an error of some sort you can:
+1. Remove all calls of `notify-send` from scripts you are using to start VPN
+2. Use other template VM that have `notify-send` working or find proper guide and make your current template VM run `notify-send` work properly.

From a65a507db57fc5166163f05c4f1244edcd5bf3fa Mon Sep 17 00:00:00 2001
From: zenkuro <42751749+zenkuro@users.noreply.github.com>
Date: Sat, 7 Jan 2023 02:47:34 -0500
Subject: [PATCH 12/87] Update vpn-troubleshooting.md

Fix typo
---
 user/troubleshooting/vpn-troubleshooting.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/user/troubleshooting/vpn-troubleshooting.md b/user/troubleshooting/vpn-troubleshooting.md
index d06eb5d1..4671066c 100644
--- a/user/troubleshooting/vpn-troubleshooting.md
+++ b/user/troubleshooting/vpn-troubleshooting.md
@@ -43,7 +43,7 @@ To check this tool is working properly run:
 ```bash
 sudo notify-send "$(hostname): Test notify-send OK" --icon=network-idle
 ```
-You should see `info` message appear on the top of your scree.
+You should see `info` message appear on the top of your screen.
 If that is the case then, `notify-send` is not the issue.
 If it is not, and you have an error of some sort you can:
 1. Remove all calls of `notify-send` from scripts you are using to start VPN

From edbfa3c9b6fc133af765687e796520118cd7f3dc Mon Sep 17 00:00:00 2001
From: Andrew David Wong <adw@qubes-os.org>
Date: Tue, 11 Apr 2023 16:35:19 -0700
Subject: [PATCH 13/87] Update
 user/how-to-guides/backup-emergency-restore-v4.md

Co-authored-by: Rusty Bird <rustybird@net-c.com>
---
 user/how-to-guides/backup-emergency-restore-v4.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md
index 1caa526b..ce04ba70 100644
--- a/user/how-to-guides/backup-emergency-restore-v4.md
+++ b/user/how-to-guides/backup-emergency-restore-v4.md
@@ -79,7 +79,7 @@ any GNU/Linux system.
     such as `scrypt` or `bzip2`, you can make things easier by aliasing those
     binaries now, e.g.,
 
-        [user@restore ~]$ alias scrypt="/home/user/scrypt-*"
+        [user@restore ~]$ alias scrypt="$PWD/scrypt-*/usr/bin/scrypt"
         [user@restore ~]$ alias bzip2="/home/user/bzip2-*"
 
  2. Untar the main backup file.

From f43e54f3a5736f9ce972e0d4889dd42cc0dfff4d Mon Sep 17 00:00:00 2001
From: Andrew David Wong <adw@qubes-os.org>
Date: Tue, 11 Apr 2023 16:42:34 -0700
Subject: [PATCH 14/87] Remove unnecessary example and step

Per @rustybird's suggestions on #1279
---
 user/how-to-guides/backup-emergency-restore-v4.md | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md
index ce04ba70..f3ca1129 100644
--- a/user/how-to-guides/backup-emergency-restore-v4.md
+++ b/user/how-to-guides/backup-emergency-restore-v4.md
@@ -76,11 +76,10 @@ any GNU/Linux system.
 *compressed*.
 
  1. (Optional) If you're working with binaries that you saved with your backup,
-    such as `scrypt` or `bzip2`, you can make things easier by aliasing those
-    binaries now, e.g.,
+    such as `scrypt`, you can make things easier by aliasing those binaries now,
+    e.g.,
 
         [user@restore ~]$ alias scrypt="$PWD/scrypt-*/usr/bin/scrypt"
-        [user@restore ~]$ alias bzip2="/home/user/bzip2-*"
 
  2. Untar the main backup file.
 
@@ -155,10 +154,9 @@ any GNU/Linux system.
 
  8. Enter the decrypted directory, mount `private.img`, and access your data.
 
-        [user@restore ~]$ cd vm1/
-        [user@restore vm1]$ sudo mkdir /mnt/img
-        [user@restore vm1]$ sudo mount -o loop vm1/private.img /mnt/img/
-        [user@restore vm1]$ cat /mnt/img/home/user/your_data.txt
+        [user@restore]$ sudo mkdir /mnt/img
+        [user@restore]$ sudo mount -o loop vm1/private.img /mnt/img/
+        [user@restore]$ cat /mnt/img/home/user/your_data.txt
         This data has been successfully recovered!
 
 Success! If you wish to recover data from more than one qube in your backup,

From 3b550699afcd692e63c1a554a1dfdf6619f93aa7 Mon Sep 17 00:00:00 2001
From: Rusty Bird <rustybird@net-c.com>
Date: Thu, 13 Apr 2023 06:47:22 +0000
Subject: [PATCH 15/87] Emergency backup restore v4 tweaks

---
 .../backup-emergency-restore-v4.md            | 76 ++++++++++---------
 1 file changed, 41 insertions(+), 35 deletions(-)

diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md
index f3ca1129..54844e96 100644
--- a/user/how-to-guides/backup-emergency-restore-v4.md
+++ b/user/how-to-guides/backup-emergency-restore-v4.md
@@ -66,44 +66,33 @@ any GNU/Linux system.
 
         [user@restore ~]$ sudo dnf install rpmdevtools
 
- 5. Extract the `scrypt` binary from the RPM.
+ 5. Extract the `scrypt` binary from the RPM and make it conveniently
+    available.
 
         [user@restore ~]$ rpmdev-extract scrypt-*.rpm
+        [user@restore ~]$ alias scrypt="$PWD/scrypt-*/usr/bin/scrypt"
 
 ## Emergency recovery instructions
 
 **Note:** In the following example, the backup file is both *encrypted* and
 *compressed*.
 
- 1. (Optional) If you're working with binaries that you saved with your backup,
-    such as `scrypt`, you can make things easier by aliasing those binaries now,
-    e.g.,
+ 1. Untar the backup metadata from the main backup file.
 
-        [user@restore ~]$ alias scrypt="$PWD/scrypt-*/usr/bin/scrypt"
-
- 2. Untar the main backup file.
-
-        [user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456
+        [user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456 \
+            backup-header backup-header.hmac qubes.xml.000.enc
         backup-header
         backup-header.hmac
         qubes.xml.000.enc
-        vm1/private.img.000.enc
-        vm1/private.img.001.enc
-        vm1/private.img.002.enc
-        vm1/icon.png.000.enc
-        vm1/firewall.xml.000.enc
-        vm1/whitelisted-appmenus.list.000.enc
-        dom0-home/dom0user.000.enc
 
- 3. Set the backup passphrase environment variable. While this isn't strictly
+ 2. Set the backup passphrase environment variable. While this isn't strictly
     required, it will be handy later and will avoid saving the passphrase in the
     shell's history.
 
         [user@restore ~]$ read -r backup_pass
 
- 4. Verify the integrity of `backup-header`. For compatibility reasons,
-    `backup-header.hmac` is an encrypted *and integrity protected* version of
-    `backup-header`.
+ 3. Verify the integrity of `backup-header` using `backup-header.hmac` (an
+    encrypted *and integrity protected* version of `backup-header`).
 
         [user@restore ~]$ set +H
         [user@restore ~]$ echo "backup-header!$backup_pass" |\
@@ -118,7 +107,7 @@ any GNU/Linux system.
     - [Emergency Backup Recovery without Qubes (v2)](/doc/backup-emergency-restore-v2/)
     - [Emergency Backup Recovery without Qubes (v3)](/doc/backup-emergency-restore-v3/)
 
- 5. Read `backup-header`.
+ 4. Read `backup-header`.
 
         [user@restore ~]$ cat backup-header
         version=4
@@ -128,36 +117,53 @@ any GNU/Linux system.
         hmac-algorithm=scrypt
         backup-id=20161020T123455-1234
 
- 6. Set `backup_id` to the value in the last line of `backup-header`. (Note that
+ 5. Set `backup_id` to the value in the last line of `backup-header`. (Note that
     there is a hyphen in `backup-id` in the file, whereas there is an underscore
     in `backup_id` in the variable you're setting.)
 
         [user@restore ~]$ backup_id=20161020T123455-1234
 
- 7. Choose a qube whose data you wish to restore (in this example, `vm1`).
-    Verify the data's integrity, decrypt it, decompress it, and extract it.
+ 6. Verify and decrypt, decompress, and extract the `qubes.xml` file.
 
-        [user@restore ~]$ find vm1 -name 'private.img.*.enc' | sort -V | while read f_enc; do \
-            f_dec=${f_enc%.enc}; \
-            echo "$backup_id!$f_dec!$backup_pass" | scrypt dec -P $f_enc || break; \
-            done | gzip -d | tar -xv
-        vm1/private.img
+        [user@restore ~]$ echo "$backup_id!qubes.xml.000!$backup_pass" |\
+            scrypt dec -P qubes.xml.000.enc | gzip -d | tar -xv
+        qubes.xml
 
     If this pipeline fails, it is likely that the backup is corrupted or has
     been tampered with.
 
     **Note:** If your backup was compressed with a program other than `gzip`,
     you must substitute the correct compression program in the command above.
-    This information is contained in `backup-header` (see step 5). For example,
+    This information is contained in `backup-header` (see step 4). For example,
     if your backup is compressed with `bzip2`, use `bzip2 -d` instead of `gzip
     -d` in the command above.
 
- 8. Enter the decrypted directory, mount `private.img`, and access your data.
+ 7. Search inside of `qubes.xml` for the `backup-path` property of the qube
+    whose data you wish to restore. Using the value of this property (e.g.
+    `vm123`), untar the necessary data files:
 
-        [user@restore]$ sudo mkdir /mnt/img
-        [user@restore]$ sudo mount -o loop vm1/private.img /mnt/img/
-        [user@restore]$ cat /mnt/img/home/user/your_data.txt
+        [user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456 vm123
+
+ 8. Verify and decrypt the backed up data, decompress it, and extract it.
+
+        [user@restore ~]$ find vm123 -name 'private.img.*.enc' | sort -V | while read f_enc; do \
+            f_dec=${f_enc%.enc}; \
+            echo "$backup_id!$f_dec!$backup_pass" | scrypt dec -P $f_enc || break; \
+            done | gzip -d | tar -xv
+        vm123/private.img
+
+    If this pipeline fails, it is likely that the backup is corrupted or has
+    been tampered with.
+
+    Also see the note in step 6 about substituting a different compression
+    program for `gzip`.
+
+ 9. Mount `private.img` and access your data.
+
+        [user@restore ~]$ sudo mkdir /mnt/img
+        [user@restore ~]$ sudo mount -o loop vm123/private.img /mnt/img/
+        [user@restore ~]$ cat /mnt/img/home/user/your_data.txt
         This data has been successfully recovered!
 
 Success! If you wish to recover data from more than one qube in your backup,
-simply repeat steps 7 and 8 for each additional qube.
+simply repeat steps 7, 8, and 9 for each additional qube.

From 034976f80fe61562412a2ae3d18fb7adb7093f77 Mon Sep 17 00:00:00 2001
From: Rusty Bird <rustybird@net-c.com>
Date: Fri, 14 Apr 2023 16:28:59 +0000
Subject: [PATCH 16/87] Use vm123/ with a trailing slash like in the
 backup-path value

---
 user/how-to-guides/backup-emergency-restore-v4.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md
index 54844e96..2cf18a51 100644
--- a/user/how-to-guides/backup-emergency-restore-v4.md
+++ b/user/how-to-guides/backup-emergency-restore-v4.md
@@ -140,13 +140,13 @@ any GNU/Linux system.
 
  7. Search inside of `qubes.xml` for the `backup-path` property of the qube
     whose data you wish to restore. Using the value of this property (e.g.
-    `vm123`), untar the necessary data files:
+    `vm123/`), untar the necessary data files:
 
-        [user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456 vm123
+        [user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456 vm123/
 
  8. Verify and decrypt the backed up data, decompress it, and extract it.
 
-        [user@restore ~]$ find vm123 -name 'private.img.*.enc' | sort -V | while read f_enc; do \
+        [user@restore ~]$ find vm123/ -name 'private.img.*.enc' | sort -V | while read f_enc; do \
             f_dec=${f_enc%.enc}; \
             echo "$backup_id!$f_dec!$backup_pass" | scrypt dec -P $f_enc || break; \
             done | gzip -d | tar -xv

From 35b16e2e372a80ccd81e9c4e4d5b87a56a507a49 Mon Sep 17 00:00:00 2001
From: Rusty Bird <rustybird@net-c.com>
Date: Fri, 14 Apr 2023 16:29:00 +0000
Subject: [PATCH 17/87] Mention installing the compression program

---
 user/how-to-guides/backup-emergency-restore-v4.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md
index 2cf18a51..ea47708f 100644
--- a/user/how-to-guides/backup-emergency-restore-v4.md
+++ b/user/how-to-guides/backup-emergency-restore-v4.md
@@ -136,7 +136,8 @@ any GNU/Linux system.
     you must substitute the correct compression program in the command above.
     This information is contained in `backup-header` (see step 4). For example,
     if your backup is compressed with `bzip2`, use `bzip2 -d` instead of `gzip
-    -d` in the command above.
+    -d` in the command above. You might need to install a package of the same
+    name (in this example, `bzip2`) through your distribution's package manager.
 
  7. Search inside of `qubes.xml` for the `backup-path` property of the qube
     whose data you wish to restore. Using the value of this property (e.g.

From 51d387a9fe935781d741eafcec818472d4e235a0 Mon Sep 17 00:00:00 2001
From: Rusty Bird <rustybird@net-c.com>
Date: Sat, 15 Apr 2023 10:45:27 +0000
Subject: [PATCH 18/87] Add xmlstarlet command

Also update the backup filename's date to avoid anachronisms in the
resulting example qube list (e.g. a backup of fedora-37 in 2015)
---
 .../backup-emergency-restore-v4.md            | 38 ++++++++++++++++---
 1 file changed, 33 insertions(+), 5 deletions(-)

diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md
index ea47708f..b42d400b 100644
--- a/user/how-to-guides/backup-emergency-restore-v4.md
+++ b/user/how-to-guides/backup-emergency-restore-v4.md
@@ -79,7 +79,7 @@ any GNU/Linux system.
 
  1. Untar the backup metadata from the main backup file.
 
-        [user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456 \
+        [user@restore ~]$ tar -i -xvf qubes-backup-2023-04-05T123456 \
             backup-header backup-header.hmac qubes.xml.000.enc
         backup-header
         backup-header.hmac
@@ -139,11 +139,39 @@ any GNU/Linux system.
     -d` in the command above. You might need to install a package of the same
     name (in this example, `bzip2`) through your distribution's package manager.
 
- 7. Search inside of `qubes.xml` for the `backup-path` property of the qube
-    whose data you wish to restore. Using the value of this property (e.g.
-    `vm123/`), untar the necessary data files:
+ 7. Search inside of the `qubes.xml` file for the `backup-path` of the qube
+    whose data you wish to restore. If you install the `xmlstarlet` package, the
+    following command will convert `qubes.xml` to a friendlier listing for this
+    purpose:
 
-        [user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456 vm123/
+        [user@restore ~]$ xmlstarlet sel -T -t -m //domain \
+            -v 'concat(.//property[@name="name"], " ", .//feature[@name="backup-path"])' \
+            -n qubes.xml
+        
+        anon-whonix
+        debian-11
+        default-mgmt-dvm
+        disp2345
+        fedora-37
+        fedora-37-dvm
+        personal vm123/
+        sys-firewall
+        sys-net
+        sys-usb
+        untrusted
+        vault vm321/
+        whonix-gw-16
+        whonix-ws-16
+        whonix-ws-16-dvm
+        work
+
+    The example output above shows that the backup file includes a qube named
+    `personal` and a qube named `vault`, with `backup-path` values of `vm123/`
+    and `vm321/` respectively. (Every other listed qube was not selected to be
+    included in the backup file.) Use the corresponding value to untar the
+    necessary data files of the qube:
+
+        [user@restore ~]$ tar -i -xvf qubes-backup-2023-04-05T123456 vm123/
 
  8. Verify and decrypt the backed up data, decompress it, and extract it.
 

From 0251ed63d5d63474d5ce9dadedec3b270448ba50 Mon Sep 17 00:00:00 2001
From: Rusty Bird <rustybird@net-c.com>
Date: Sat, 15 Apr 2023 11:08:35 +0000
Subject: [PATCH 19/87] Update to a plausible timestamp in the backup ID too

---
 user/how-to-guides/backup-emergency-restore-v4.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md
index b42d400b..0d318b5e 100644
--- a/user/how-to-guides/backup-emergency-restore-v4.md
+++ b/user/how-to-guides/backup-emergency-restore-v4.md
@@ -115,13 +115,13 @@ any GNU/Linux system.
         compressed=True
         compression-filter=gzip
         hmac-algorithm=scrypt
-        backup-id=20161020T123455-1234
+        backup-id=20230405T123455-1234
 
  5. Set `backup_id` to the value in the last line of `backup-header`. (Note that
     there is a hyphen in `backup-id` in the file, whereas there is an underscore
     in `backup_id` in the variable you're setting.)
 
-        [user@restore ~]$ backup_id=20161020T123455-1234
+        [user@restore ~]$ backup_id=20230405T123455-1234
 
  6. Verify and decrypt, decompress, and extract the `qubes.xml` file.
 

From d4778384da7ae12bec3cd691b88cacb8900d9090 Mon Sep 17 00:00:00 2001
From: Rusty Bird <rustybird@net-c.com>
Date: Sat, 15 Apr 2023 16:05:47 +0000
Subject: [PATCH 20/87] Add sys-whonix to example qube list

---
 user/how-to-guides/backup-emergency-restore-v4.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md
index 0d318b5e..92b4866c 100644
--- a/user/how-to-guides/backup-emergency-restore-v4.md
+++ b/user/how-to-guides/backup-emergency-restore-v4.md
@@ -158,6 +158,7 @@ any GNU/Linux system.
         sys-firewall
         sys-net
         sys-usb
+        sys-whonix
         untrusted
         vault vm321/
         whonix-gw-16

From 4992cf406e67450134cf07c3987b823b5f044bcd Mon Sep 17 00:00:00 2001
From: noskb <63541981+noskb@users.noreply.github.com>
Date: Tue, 25 Apr 2023 02:07:22 +0000
Subject: [PATCH 21/87] Modernize uefi-troubleshooting.md

Remove workarounds that no longer function and modernize those that remain
---
 user/troubleshooting/uefi-troubleshooting.md | 280 +++++--------------
 1 file changed, 65 insertions(+), 215 deletions(-)

diff --git a/user/troubleshooting/uefi-troubleshooting.md b/user/troubleshooting/uefi-troubleshooting.md
index a364ee89..7c3834de 100644
--- a/user/troubleshooting/uefi-troubleshooting.md
+++ b/user/troubleshooting/uefi-troubleshooting.md
@@ -3,178 +3,42 @@ lang: en
 layout: doc
 permalink: /doc/uefi-troubleshooting/
 ref: 177
-title: UEFI troubleshooting
+title: UEFI Troubleshooting
 ---
 
-## 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.
+
+## 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**
 
 01. Attach the usb disk, mount the EFI partition (second partition available on the disk)
-02. Open a terminal and enter the command `sudo su -`. Use your preferred text editor (e.g `nano`) to edit your xen config (`EFI/BOOT/BOOTX64.cfg`):
+02. 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`):
 
     ```
-    nano EFI/BOOT/BOOTX64.cfg
+    vi EFI/BOOT/grub.cfg
     ```
 
-03. Change the `kernel` key to add your kernel parameters on the boot entry of your choice
+03. Change the `multiboot2 /images/pxeboot/xen.gz` line to add your xen parameters on the boot entry of your choice
 04. Install using your modified boot entry
 
 **Change xen configuration directly in an iso image**
 01. Set up a loop device (replacing `X` with your ISO's version name): `losetup -P /dev/loop0 Qubes-RX-x86_64.iso`
 02. Mount the loop device: `sudo mount /dev/loop0p2 /mnt`
-03. Edit `EFI/BOOT/BOOTX64.cfg` to add your params to the `kernel` configuration key
+03. Edit `EFI/BOOT/grub.cfg` to add your params to the `multiboot2 /images/pxeboot/xen.gz` line
 04. 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://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/nvidia-troubleshooting.md#disabling-nouveau).
+If you have an Nvidia card, see [Nvidia Troubleshooting](https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/nvidia-troubleshooting.md#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/#successfully-installed-in-legacy-mode-but-had-to-change-some-kernel-parameters) 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/#successfully-installed-in-legacy-mode-but-had-to-change-some-kernel-parameters) 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/#successfully-installed-in-legacy-mode-but-had-to-change-some-kernel-parameters) 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).
@@ -187,7 +51,7 @@ You can re-enable it either as part of the install process:
 3. Execute:
 
     ```
-    sed -i -e 's/^options=.*/\0 efi=attr=uc/' /mnt/sysimage/boot/efi/EFI/qubes/xen.cfg
+    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`.
@@ -195,87 +59,73 @@ You can re-enable it either as part of the install process:
 
 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:
+1. Boot Qubes OS install media into [rescue mode](/doc/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:
 
     ```
-    sed -i -e 's/^options=.*/\0 efi=attr=uc/' /mnt/sysimage/boot/efi/EFI/qubes/xen.cfg
+    sed -i -e 's/ucode=scan/\0 efi=attr=uc/' /mnt/sysimage/boot/efi/EFI/qubes/grub.cfg
     ```
 
-3. Type `reboot`.
-4. Continue with setting up default templates and logging in to Qubes.
+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.
-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):
+1. Boot Qubes OS install media into [rescue mode](/doc/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:
+    
+    ```
+    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 [rescue mode](/doc/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):
 
     ```
-    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"
+    efibootmgr -v -c -u -L Qubes -l /EFI/qubes/grubx64.efi -d /dev/sda -p 1 
     ```
 
 ## 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
-~~~
+Choose "Rescue a Qubes OS system" from grub2 boot menu.

From f24299be1ebdd81a5acb6af66967104955ae885a Mon Sep 17 00:00:00 2001
From: Oni <git@oni.blue>
Date: Wed, 7 Jun 2023 05:59:45 -0400
Subject: [PATCH 22/87] Use 'qvm-template' to uninstall templates

The 'dnf remove' command no longer removes templates and mentions "No
Match" when using <package-name-spec>. The 'qvm-template' command will
remove templates from both package installation and
cloning. 'qvm-template' also warns about qubes dependent on the template
which reduces the need for the user to preemptively check that
relationship.

In its implementation, 'qvm-template' imports and calls 'qvm-remove'
to remove the template. 'qvm-template' was selected as the command to
present as it provides a more consistent interface when installing,
listing, and removing among other commands.
---
 user/templates/templates.md | 27 +++++++++------------------
 1 file changed, 9 insertions(+), 18 deletions(-)

diff --git a/user/templates/templates.md b/user/templates/templates.md
index f3740dec..30e40635 100644
--- a/user/templates/templates.md
+++ b/user/templates/templates.md
@@ -144,28 +144,19 @@ Please see [How to Install Software](/doc/how-to-install-software).
 
 ## Uninstalling
 
-If you want to remove a template you must make sure that it is not being used.
-You should check that the template is not being used by any qubes,
-and also that it is not set as the default template.
-
-The procedure for uninstalling a template depends on how it was created.
-
-If the template was originaly created by cloning another template, then you can
-delete it the same way as you would any other qube. In the Qube Manager,
-right-click on the template and select **Delete qube**. (If you're not sure,
-you can safely try this method first to see if it works.)
-
-If, on the other hand, the template came pre-installed or was installed by
-installing a template package in dom0, per the instructions
-[above](#installing), then you must execute the following type of command in
-dom0 in order to uninstall it:
+To remove a template, the graphical `Qube Manager` (Qubes Menu > Qubes Tools > Qube Manager) may be used. Right-click the template to be uninstalled and click "Delete qube" to begin removal.
 
+Alternatively, to remove a template via the command line in dom0:
 ```
-$ sudo dnf remove qubes-template-<DISTRO_NAME>-<RELEASE_NUMBER>
+$ qvm-template remove <TEMPLATE_NAME>
 ```
 
-`qubes-template-<DISTRO_NAME>-<RELEASE_NUMBER>` is the name of the desired
-template package.
+\<TEMPLATE_NAME> is the first column from the output of:
+```
+$ qvm-template list --installed
+```
+
+In either case, if another qube is based on the template, the template will remain installed and a list of the dependent qubes will be displayed. [Switch](#switching) the dependent qubes to another template before attempting the removal again.
 
 You may see warning messages like the following:
 

From e1abb55e638ce29bf8ae17f504a83b4ba024e101 Mon Sep 17 00:00:00 2001
From: Oni <git@oni.blue>
Date: Mon, 19 Jun 2023 06:26:18 -0400
Subject: [PATCH 23/87] Retire template removal warning messages

This section was added in response to:

https://github.com/QubesOS/qubes-issues/issues/6432

Seven months later, 'qvm-template' became the installation redirection
target:

https://github.com/QubesOS/qubes-core-admin-linux/pull/80

Now that 'dnf remove' is not being called directly, these warnings
should not be an issue.
---
 user/templates/templates.md | 26 --------------------------
 1 file changed, 26 deletions(-)

diff --git a/user/templates/templates.md b/user/templates/templates.md
index 30e40635..a15bfc16 100644
--- a/user/templates/templates.md
+++ b/user/templates/templates.md
@@ -158,32 +158,6 @@ $ qvm-template list --installed
 
 In either case, if another qube is based on the template, the template will remain installed and a list of the dependent qubes will be displayed. [Switch](#switching) the dependent qubes to another template before attempting the removal again.
 
-You may see warning messages like the following:
-
-```
-warning: file /var/lib/qubes/vm-templates/fedora-XX/whitelisted-appmenus.list: remove failed: No such file or directory
-warning: file /var/lib/qubes/vm-templates/fedora-XX/vm-whitelisted-appmenus.list: remove failed: No such file or directory
-warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.04: remove failed: No such file or directory
-warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.03: remove failed: No such file or directory
-warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.02: remove failed: No such file or directory
-warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.01: remove failed: No such file or directory
-warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.00: remove failed: No such file or directory
-warning: file /var/lib/qubes/vm-templates/fedora-XX/netvm-whitelisted-appmenus.list: remove failed: No such file or directory
-warning: file /var/lib/qubes/vm-templates/fedora-XX/icon.png: remove failed: No such file or directory
-warning: file /var/lib/qubes/vm-templates/fedora-XX/clean-volatile.img.tar: remove failed: No such file or directory
-warning: file /var/lib/qubes/vm-templates/fedora-XX/apps.templates: remove failed: No such file or directory
-warning: file /var/lib/qubes/vm-templates/fedora-XX/apps.tempicons: remove failed: No such file or directory
-warning: file /var/lib/qubes/vm-templates/fedora-XX/apps: remove failed: No such file or directory
-warning: file /var/lib/qubes/vm-templates/fedora-XX: remove failed: No such file or directory
-```
-
-These are normal and expected. Nothing is wrong, and no action is required to
-address these warnings.
-
-If the uninstallation command doesn't work, pay close attention to
-any error message: it may tell you what qube is using the template,
-or if the template is default. In other cases, please see [VM Troubleshooting](/doc/vm-troubleshooting/).
-
 If the Applications Menu entry doesn't go away after you uninstall a template,
 execute the following type of command in dom0:
 

From 781780f07e7bd24618bfef64e650f482fd914b16 Mon Sep 17 00:00:00 2001
From: Oni <git@oni.blue>
Date: Mon, 19 Jun 2023 06:59:06 -0400
Subject: [PATCH 24/87] Redirect Qubes Menu issues with template uninstallation

Manually removing Qubes Menu entries is covered on the linked page.
---
 user/templates/templates.md | 14 +-------------
 1 file changed, 1 insertion(+), 13 deletions(-)

diff --git a/user/templates/templates.md b/user/templates/templates.md
index a15bfc16..7bd6a9a3 100644
--- a/user/templates/templates.md
+++ b/user/templates/templates.md
@@ -158,19 +158,7 @@ $ qvm-template list --installed
 
 In either case, if another qube is based on the template, the template will remain installed and a list of the dependent qubes will be displayed. [Switch](#switching) the dependent qubes to another template before attempting the removal again.
 
-If the Applications Menu entry doesn't go away after you uninstall a template,
-execute the following type of command in dom0:
-
-```
-$ rm ~/.local/share/applications/<TEMPLATE_NAME>
-```
-
-Applications Menu entries for backups of removed qubes can also be found in
-`/usr/local/share/applications/` of dom0.
-
-```
-$ rm /usr/local/share/applications/<TEMPLATE_NAME>
-```
+If the template's entry in the Qubes Menu is not removed with its uninstallation, consult the [troubleshooting page](/doc/app-menu-shortcut-troubleshooting/#fixing-shortcuts).
 
 ## Reinstalling
 

From 1e7a9f7437f6428e9fba97be3dea67de172a80b3 Mon Sep 17 00:00:00 2001
From: Oni <git@oni.blue>
Date: Mon, 19 Jun 2023 08:42:59 -0400
Subject: [PATCH 25/87] Address two potential issues raised when removing a
 template

Mentioned the final confirmation step asked for by the `Qube Manager`
to type the template's name. However, before this final confirmation
is displayed, issues may be raised. Deleting templates may run afoul
of dependent qubes and the "default_template" global
property. Instructions to resolve via switching are linked.
---
 user/templates/templates.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/user/templates/templates.md b/user/templates/templates.md
index 7bd6a9a3..651c7a88 100644
--- a/user/templates/templates.md
+++ b/user/templates/templates.md
@@ -144,7 +144,7 @@ Please see [How to Install Software](/doc/how-to-install-software).
 
 ## Uninstalling
 
-To remove a template, the graphical `Qube Manager` (Qubes Menu > Qubes Tools > Qube Manager) may be used. Right-click the template to be uninstalled and click "Delete qube" to begin removal.
+To remove a template, the graphical `Qube Manager` (Qubes Menu > Qubes Tools > Qube Manager) may be used. Right-click the template to be uninstalled and click "Delete qube" to begin removal. If no issues are found, a dialog box will request the template's name be typed as a final confirmation. Upon completion, the template will be deleted.
 
 Alternatively, to remove a template via the command line in dom0:
 ```
@@ -156,7 +156,7 @@ $ qvm-template remove <TEMPLATE_NAME>
 $ qvm-template list --installed
 ```
 
-In either case, if another qube is based on the template, the template will remain installed and a list of the dependent qubes will be displayed. [Switch](#switching) the dependent qubes to another template before attempting the removal again.
+In either case, issues with template removal may be raised. If an issue is raised, the template will remain installed and a list of concerns displayed. "Global property default_template" requires [switching](#switching) the default_template property to another template. "Template for" can be resolved by [switching](#switching) the dependent qubes' template. Once the issues are addressed, attempt the removal again.
 
 If the template's entry in the Qubes Menu is not removed with its uninstallation, consult the [troubleshooting page](/doc/app-menu-shortcut-troubleshooting/#fixing-shortcuts).
 

From 6e15603483b02bef6ae8f76fca78be3bc93b353e Mon Sep 17 00:00:00 2001
From: Rusty Bird <rustybird@net-c.com>
Date: Tue, 20 Jun 2023 13:52:30 +0000
Subject: [PATCH 26/87] Clarify reading the passphrase

https://forum.qubes-os.org/t/getting-stuck-on-emergency-backup-recovery/18520/5
https://forum.qubes-os.org/t/getting-stuck-on-emergency-backup-recovery/18520/6
---
 user/how-to-guides/backup-emergency-restore-v4.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md
index 92b4866c..8688f5b0 100644
--- a/user/how-to-guides/backup-emergency-restore-v4.md
+++ b/user/how-to-guides/backup-emergency-restore-v4.md
@@ -91,6 +91,8 @@ any GNU/Linux system.
 
         [user@restore ~]$ read -r backup_pass
 
+    Type in your passphrase (it will be visible on screen!) and press Enter.
+
  3. Verify the integrity of `backup-header` using `backup-header.hmac` (an
     encrypted *and integrity protected* version of `backup-header`).
 

From 0aee55a8dd6b29a0a55006532c046b56e04c5416 Mon Sep 17 00:00:00 2001
From: Rusty Bird <rustybird@net-c.com>
Date: Tue, 20 Jun 2023 13:52:31 +0000
Subject: [PATCH 27/87] Use ls instead of cat to show example data

https://forum.qubes-os.org/t/getting-stuck-on-emergency-backup-recovery/18520/5
---
 user/how-to-guides/backup-emergency-restore-v4.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md
index 8688f5b0..d4baa698 100644
--- a/user/how-to-guides/backup-emergency-restore-v4.md
+++ b/user/how-to-guides/backup-emergency-restore-v4.md
@@ -194,8 +194,9 @@ any GNU/Linux system.
 
         [user@restore ~]$ sudo mkdir /mnt/img
         [user@restore ~]$ sudo mount -o loop vm123/private.img /mnt/img/
-        [user@restore ~]$ cat /mnt/img/home/user/your_data.txt
-        This data has been successfully recovered!
+        [user@restore ~]$ ls /mnt/img/home/user/
+        example_data_file.txt
+        ...
 
 Success! If you wish to recover data from more than one qube in your backup,
 simply repeat steps 7, 8, and 9 for each additional qube.

From 108fb1e106a65e0d5c0a7f13913be8fd288a62d0 Mon Sep 17 00:00:00 2001
From: chomiczosc <155738605+chomiczosc@users.noreply.github.com>
Date: Fri, 5 Jan 2024 15:26:36 +0100
Subject: [PATCH 28/87] Update getting-started.md

- simplifying "Getting started section" to make it more comprehensible
- updating the section to match Qubes 4.2
---
 introduction/getting-started.md | 135 +++++++++++++++-----------------
 1 file changed, 64 insertions(+), 71 deletions(-)

diff --git a/introduction/getting-started.md b/introduction/getting-started.md
index 1ac922d5..92409e27 100644
--- a/introduction/getting-started.md
+++ b/introduction/getting-started.md
@@ -18,14 +18,13 @@ Dive right in to [organizing your qubes](/doc/how-to-organize-your-qubes/).)
 
 ## The Basics
 
-Qubes OS is an operating system built out of securely-isolated compartments
-called [qubes](/doc/glossary/#qube). For example, you might have a work qube, a
-personal qube, a banking qube, a web browsing qube, and so on. You can have as
-many qubes as you want! Most of the time, you'll be using an [app
-qube](/doc/glossary/#app-qube), which is a qube intended for running software
+Qubes OS is an operating system built out of securely-isolated compartments, or [qubes](/doc/glossary/#qube). 
+You can have a work qube, a personal qube, a banking qube, a web browsing qube, a standalone Windows qube and so on. 
+You can have as many qubes as you want! Most of the time, you'll be using an [app
+qube](/doc/glossary/#app-qube), a qube for running software
 programs like web browsers, email clients, and word processors. Each app qube
 is based on another type of qube called a [template](/doc/glossary/#template).
-More than one qube can be based on the same template. Importantly, a qube
+The same template can be a base for various cubes. Importantly, a qube
 cannot modify its template in any way. This means that, if a qube is ever
 compromised, its template and any other qubes based on that template will
 remain safe. This is what makes Qubes OS so secure. Even if an attack is
@@ -35,9 +34,8 @@ Suppose you want to use your favorite web browser in several different qubes.
 You'd install the web browser in a template, then every qube based on that
 template would be able to run the web browser software (while still being
 forbidden from modifying the template and any other qubes). This way, you only
-have to install the web browser a single time, and updating the template serves
-to update all the qubes based on it. This elegant design saves time and space
-while enhancing security.
+have to install the web browser a single time, and updating the template updates all the qubes based on it. 
+This elegant design saves time and space while enhancing security.
 
 There are also some "helper" qubes in your system. Each qube that connects to
 the Internet does so through a network-providing [service
@@ -54,27 +52,24 @@ corresponding version number. There are many ready-to-use
 many as you like.
 
 Last but not least, there's a very special [admin
-qube](/doc/glossary/#admin-qube) which, as the name suggests, is used to
-administer your entire system. There's only one admin qube, and it's called
-[dom0](/doc/glossary/#dom0). You can think of it as the master qube, holding
-ultimate power over everything that happens in Qubes OS. Dom0 is more trusted
-than any other qube. If dom0 were ever compromised, it would be "game over."
-The entire system would effectively be compromised. That's why everything in
-Qubes OS is specifically designed to protect dom0 and ensure that doesn't
+qube](/doc/glossary/#admin-qube) used to administer your entire system. 
+There's only one admin qube, and it's called [dom0](/doc/glossary/#dom0). 
+You can think of it as the master qube, holding ultimate power over everything that happens in Qubes OS. 
+Dom0 is the most trusted one of all qubes. If dom0 were ever to be compromised, it would be "game over"- an effective compromise of the entire system.
+That's why everything in Qubes OS is specifically designed to protect dom0 and ensure that doesn't
 happen. Due to its overarching importance, dom0 has no network connectivity and
 is used only for running the [desktop
 environment](https://en.wikipedia.org/wiki/Desktop_environment) and [window
 manager](https://en.wikipedia.org/wiki/Window_manager). Dom0 should never be
 used for anything else. In particular, you should never run user applications
-in dom0. (That's what your app qubes are for!)
+in dom0. (That's what your app qubes are for!) In short, do not interact directly with dom0 in any way, shape or form.
 
 ### Color & Security
 
 You'll choose a **color** for each of your qubes out of a predefined set of
-colors. Each window on your desktop will have its frame colored according to
-the color of that qube. These colored frames help you keep track of which qube
-each window belongs to and how trustworthy it is. This is especially helpful
-when you have the same app running in multiple qubes at the same time. For
+colors. The color of the frame of each window on your desktop will correspond to the color of that cube. 
+These colored frames help you keep track of which qube you're currently using and how trustworthy it is. This is especially helpful
+when you have the same program running in multiple qubes at the same time. For
 example, if you're logged in to your bank account in one qube while doing some
 random web surfing in a different qube, you wouldn't want to accidentally enter
 your banking password in the latter! The colored frames help to avoid such
@@ -83,16 +78,16 @@ mistakes.
 [![snapshot_40.png](/attachment/doc/r4.0-snapshot_40.png)](/attachment/doc/r4.0-snapshot_40.png)
 
 Most Qubes users associate red with what's untrusted and dangerous (like a red
-light: stop! danger!), green with what's safe and trusted, and yellow and
-orange with things in the middle. This color scheme also extends to include
-blue and black, which are usually interpreted as indicating progressively more
-trusted domains than green, with black being ultimately trusted. Color and
-associated meanings are ultimately up to you, however. The system itself does
-not treat the colors differently. If you create two identical qubes --- black
+stop light signalling danger), green with what's safe and trusted, and yellow and
+orange with things in-between. This color scheme also includes
+blue and black, commonly interpreted as indicating progressively more
+trusted domains than green, with black being ultimately trusted. However, color and
+associated meanings are entirely up to you. The system itself does
+not treat the colors differently - they're all equally safe on their own. If you create two identical qubes --- black
 and red, say --- they'll be the same until you start using them differently.
-Feel free to use the colors in whatever way is most useful to you. For example,
+Feel free to use the colors in the way that best meets your needs. For example,
 you might decide to use three or four qubes for work activities and give them
-all the same color --- or all different colors. It's entirely up to you.
+all the same color --- or all different colors depending on the nature of the task they are used for.
 
 ### User Interface
 
@@ -104,27 +99,24 @@ the window managers [i3](/doc/i3/) and [AwesomeWM](/doc/awesomewm/).
 
 [![r4.0-taskbar.png](/attachment/doc/r4.0-taskbar.png)](/attachment/doc/r4.0-taskbar.png)
 
-The bar at the top of your screen in Qubes 4.0 includes the following XFCE
+The bar at the top of your screen in Qubes 4.2 includes the following XFCE
 component areas:
 
-- The **Tray**, where many functional widgets live.
+- The **App Menu**, where you go to open an application within a qube, to open
+  a dom0 terminal, to access administrative UI tools such as the Qube Manager,
+  or to access settings panels for your desktop environment.
+- The **Task Bar** where buttons for open and hidden windows live.
 - **Spaces**, an interface for [virtual
   desktops](https://en.wikipedia.org/wiki/Virtual_desktop). Virtual desktops do
   not have any inherent security isolation properties, but some users find them
   useful for organizing things.
-- The **Task Bar** where buttons for open and hidden windows live.
-- The **App Menu**, where you go to open an application within a qube, to open
-  a dom0 terminal, to access administrative UI tools such as the Qube Manager,
-  or to access settings panels for your desktop environment.
-
-To learn more about how to customize your desktop environment, we recommend you
-spend some time going through [XFCE's documentation](https://docs.xfce.org/).
+- The **Tray**, where many functional widgets live.
 
 There are several tray widgets that are unique to Qubes OS:
 
 - The **Whonix SDWDate** allows you to control the Tor connection in your
   [`sys-whonix`](https://www.whonix.org/wiki/Qubes) qube.
-- The **Qubes Clipboard** lets you easily copy text from dom0.
+- The **Qubes Clipboard** lets you easily [copy text](https://wwwpreview.qubes-os.org/doc/how-to-copy-and-paste-text/) between various qubes and from dom0.
 - The **Qubes Devices** widget allows you to attach and detach devices --- such
   as USB drives and cameras --- to qubes. 
 - The **Qubes Disk Space** widget shows you how much storage you're using.
@@ -136,50 +128,57 @@ There are several tray widgets that are unique to Qubes OS:
 
 [![r4.1-widgets.png](/attachment/doc/r4.1-widgets.png)](/attachment/doc/r4.1-widgets.png)
 
+To learn more about how to customize your desktop environment, we recommend you
+go through [XFCE's documentation](https://docs.xfce.org/).
+
 #### Qube Manager
 
-To see all of your qubes at the same time, you can use the **Qube Manager** (go
-to the App Menu → Qubes Tools → Qube Manager), which displays the states of
-all the qubes in your system, even the ones that aren't running.
+To see all of your qubes at the same time, you can use the **Qube Manager**. 
+It displays the states of all the qubes in your system, even the ones that aren’t running.
+
+To access Qube Manager go to:
+Qubes Icon (App Menu) → Settings Icon → Qubes Tools → **Qube Manager**
 
 [![r4.0-qubes-manager.png](/attachment/doc/r4.0-qubes-manager.png)](/attachment/doc/r4.0-qubes-manager.png)
 
 #### Command-line interface
 
-All aspects of Qubes OS can be controlled using command-line tools. Opening a
-terminal emulator in dom0 can be done in several ways:
+All aspects of Qubes OS can be controlled using command-line tools such as the terminal emulator. 
+The default terminal emulator in Qubes is Xfce Terminal. 
+Opening a terminal emulator in dom0 can be done in several ways:
 
-- Go to the App Menu and select **Terminal Emulator** at the top.
+- Go to the App Menu, click on the Settings icon, choose Other from the drop-down menu, and select **Xfce Terminal Emulator** at the bottom.
 - Press `Alt`+`F3` and search for `xfce terminal`.
 - Right-click on the desktop and select **Open Terminal Here**.
 
-Terminal emulators can also be run in other qubes as normal programs. Various
-command-line tools are described as part of this guide, and the whole reference
-can be found [here](/doc/tools/).
+Various command-line tools are described as part of this guide, and the whole reference can be found [here](/doc/tools/).
+Terminal emulators can also be run in other qubes as normal programs. 
 
 ## First boot
 
 When you install Qubes OS, a number of qubes are pre-configured for you:
 
-- **Templates:** `fedora-XX` (`XX` being the version number)
+- **App qubes** such as `work`, `personal`, `untrusted`, and `vault` are your "starter pack" qubes to compartmentalize tasks
+  and types of data to suit most basic needs. (There is nothing special about these pre-configured qubes - they are identical in nature to more specific ones you might wish to create later.)
+- **Templates:** `fedora-XX`, `debian-XX` (`XX` being the version number)
+- **Service qubes:** `sys-usb`, `sys-net`, `sys-firewall`, and `sys-whonix`)
 - **Admin qube:** `dom0`
-- **Service qubes:** `sys-usb`, `sys-net`, `sys-firewall`, and `sys-whonix`
-- **App qubes** configured to prioritize security by compartmentalizing tasks
-  and types of data: `work`, `personal`, `untrusted`, and `vault`. (There is
-  nothing special about these qubes. If you were to create a black qube and
-  name it `vault`, it would be the same as the pre-configured `vault` qube.
-  They're just suggestions to get you started. )
 
-A variety of open-source applications such as file managers, command-line
-terminals, printer managers, text editors, and "applets" used to configure
-different things like audio or parts of the user interface are also installed
-by default—most within the templates. Most are bundled with each template.
+Other software installed in Qubes OS by default includes open-source applications such as file managers, 
+command-line terminals, printer managers, text editors, and applets for configuring audio and user interface settings.
+Most of these applications are incorporated within each template.
 
 ### Adding, removing, and listing qubes
 
-You can easily create a new qube with the **Create Qubes VM** option in the App
-Menu. If you need to add or remove qubes, simply use the Qube Manager's **Add**
-and **Remove** buttons. You can also add, remove, and list qubes from the
+To create a new qube or remove one, use **Create Qubes VM** option in the App Menu.
+
+Creating a New Qube:
+Qubes Icon → Settings → Qubes Tools → Qube Manager → Create Qubes VM → **New Qube**
+
+Removing a qube:
+To remove a qube, use the **Delete qube button** as the final step instead.
+
+You can also add, remove, and list qubes from the
 command line using the following tools:
 
 - `qvm-create`
@@ -188,14 +187,8 @@ command line using the following tools:
 
 ### How many qubes do I need?
 
-That's a great question, but there's no one-size-fits-all answer. It depends on
-the structure of your digital life, and this is at least a little different for
-everyone. If you plan on using your system for work, then it also depends on
-what kind of job you do.
-
-It's a good idea to start out with the qubes created automatically by the
-installer: `work`, `personal`, `untrusted`, and `vault`. If and when you start
-to feel that some activity just doesn't fit into any of your existing qubes, or
+It's a good idea to start out with the pre-installed app qubes: `work`, `personal`, `untrusted`, and `vault`. 
+If you start to feel that some activity just doesn't fit into any of your existing qubes, or
 you want to partition some part of your life, you can easily create a new qube
 for it. You'll also be able to easily [copy any
 files](/doc/how-to-copy-and-move-files) you need to the newly-created qube.
@@ -252,5 +245,5 @@ GitHub](https://github.com/QubesOS).
 
 ## Documentation
 
-Peruse our extensive library of [documentation](/doc/) for users and developers
+Browse our extensive library of [documentation](/doc/) for users and developers
 of Qubes OS. You can even [help us improve it](/doc/how-to-edit-the-documentation/)!

From 4a9ab9fac587590027d8330dcc25e6a825d93182 Mon Sep 17 00:00:00 2001
From: chomiczosc <155738605+chomiczosc@users.noreply.github.com>
Date: Fri, 5 Jan 2024 15:45:08 +0100
Subject: [PATCH 29/87] Update getting-started.md

Fixes from review
---
 introduction/getting-started.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/introduction/getting-started.md b/introduction/getting-started.md
index 92409e27..4a02083c 100644
--- a/introduction/getting-started.md
+++ b/introduction/getting-started.md
@@ -24,7 +24,7 @@ You can have as many qubes as you want! Most of the time, you'll be using an [ap
 qube](/doc/glossary/#app-qube), a qube for running software
 programs like web browsers, email clients, and word processors. Each app qube
 is based on another type of qube called a [template](/doc/glossary/#template).
-The same template can be a base for various cubes. Importantly, a qube
+The same template can be a base for various qubes. Importantly, a qube
 cannot modify its template in any way. This means that, if a qube is ever
 compromised, its template and any other qubes based on that template will
 remain safe. This is what makes Qubes OS so secure. Even if an attack is
@@ -62,7 +62,7 @@ is used only for running the [desktop
 environment](https://en.wikipedia.org/wiki/Desktop_environment) and [window
 manager](https://en.wikipedia.org/wiki/Window_manager). Dom0 should never be
 used for anything else. In particular, you should never run user applications
-in dom0. (That's what your app qubes are for!) In short, do not interact directly with dom0 in any way, shape or form.
+in dom0. (That's what your app qubes are for!) In short, be very careful when interacting with dom0.
 
 ### Color & Security
 

From 3cec58bf7d108e4104c30c8b5e3942149e9e94d0 Mon Sep 17 00:00:00 2001
From: Piotr Bartman <prbartman@invisiblethingslab.com>
Date: Wed, 20 Mar 2024 22:20:01 +0100
Subject: [PATCH 30/87] q-dev: update docs

---
 developer/services/admin-api.md | 233 ++++++++++++++++++++------------
 1 file changed, 144 insertions(+), 89 deletions(-)

diff --git a/developer/services/admin-api.md b/developer/services/admin-api.md
index 0087bcaf..74314ed7 100644
--- a/developer/services/admin-api.md
+++ b/developer/services/admin-api.md
@@ -62,95 +62,98 @@ yet documented.
 The API should be implemented as a set of qrexec calls. This is to make it easy
 to set the policy using current mechanism.
 
-| call                                  | dest      | argument  | inside                                    | return                                                    | note |
-| ------------------------------------- | --------- | --------- | ----------------------------------------- | --------------------------------------------------------- | ---- |
-| `admin.vmclass.List`                   | `dom0`    | -         | -                                         | `<class>\n`                                               |
-| `admin.vm.List`                        | `dom0|<vm>` | -         | -                                         | `<name> class=<class> state=<state>\n`                    |
-| `admin.vm.Create.<class>`              | `dom0`    | template  | `name=<name> label=<label>`               | -                                                         |
-| `admin.vm.CreateInPool.<class>`        | `dom0`    | template  | `name=<name> label=<label> `<br/>`pool=<pool> pool:<volume>=<pool>`   | -                                                         | either use `pool=` to put all volumes there, <br/>or `pool:<volume>=` for individual volumes - both forms are not allowed at the same time
-| `admin.vm.CreateDisposable`            | template  | -         | -                                         | name                                                      | Create new DisposableVM, `template` is any AppVM with `dispvm_allowed` set to True, or `dom0` to use default defined in `default_dispvm` property of calling VM; VM created with this call will be automatically removed after its shutdown; the main difference from `admin.vm.Create.DispVM` is automatic (random) name generation.
-| `admin.vm.Remove`                      | vm        | -         | -                                         | -                                                         |
-| `admin.label.List`                     | `dom0`    | -         | -                                         | `<property>\n`                                            |
-| `admin.label.Create`                   | `dom0`    | label     | `0xRRGGBB`                                | -                                                         |
-| `admin.label.Get`                      | `dom0`    | label     | -                                         | `0xRRGGBB`                                                |
-| `admin.label.Index`                    | `dom0`    | label     | -                                         | `<label-index>`                                           |
-| `admin.label.Remove`                   | `dom0`    | label     | -                                         | -                                                         |
-| `admin.property.List`                  | `dom0`    | -         | -                                         | `<property>\n`                                            |
-| `admin.property.Get`                   | `dom0`    | property  | -                                         | `default={True|False} `<br/>`type={str|int|bool|vm|label|list} <value>`   | Type `list` is added in R4.1. Values are of type `str` and each entry is suffixed with newline character.
-| `admin.property.GetAll`                | `dom0`    | -         | -                                         | `<property-name> <full-value-as-in-property.Get>\n`       | Get all the properties in one call. Each property is returned on a separate line and use the same value encoding as property.Get method, with an exception that newlines are encoded as literal `\n` and literal `\` are encoded as `\\`.
-| `admin.property.GetDefault`            | `dom0`    | property  | -                                         | `type={str|int|bool|vm|label|list} <value>`               | Type `list` is added in R4.1. Values are of type `str` and each entry is suffixed with newline character.
-| `admin.property.Help`                  | `dom0`    | property  | -                                         | `help`                                                    |
-| `admin.property.HelpRst`               | `dom0`    | property  | -                                         | `help.rst`                                                |
-| `admin.property.Reset`                 | `dom0`    | property  | -                                         | -                                                         |
-| `admin.property.Set`                   | `dom0`    | property  | value                                     | -                                                         |
-| `admin.vm.property.List`               | vm        | -         | -                                         | `<property>\n`                                            |
-| `admin.vm.property.Get`                | vm        | property  | -                                         | `default={True|False} `<br/>`type={str|int|bool|vm|label|list} <value>`   | Type `list` is added in R4.1. Each list entry is suffixed with a newline character.
-| `admin.vm.property.GetAll`             | vm        | -         | -                                         | `<property-name> <full-value-as-in-property.Get>\n`       | Get all the properties in one call. Each property is returned on a separate line and use the same value encoding as property.Get method, with an exception that newlines are encoded as literal `\n` and literal `\` are encoded as `\\`.
-| `admin.vm.property.GetDefault`         | vm        | property  | -                                         | `type={str|int|bool|vm|label|type} <value>`               | Type `list` is added in R4.1. Each list entry is suffixed with a newline character.
-| `admin.vm.property.Help`               | vm        | property  | -                                         | `help`                                                    |
-| `admin.vm.property.HelpRst`            | vm        | property  | -                                         | `help.rst`                                                |
-| `admin.vm.property.Reset`              | vm        | property  | -                                         | -                                                         |
-| `admin.vm.property.Set`                | vm        | property  | value                                     | -                                                         |
-| `admin.vm.feature.List`                | vm        | -         | -                                         | `<feature>\n`                                             |
-| `admin.vm.feature.Get`                 | vm        | feature   | -                                         | value                                                     |
-| `admin.vm.feature.CheckWithTemplate`   | vm        | feature   | -                                         | value                                                     |
-| `admin.vm.feature.CheckWithNetvm`      | vm        | feature   | -                                         | value                                                     |
-| `admin.vm.feature.CheckWithAdminVM`    | vm        | feature   | -                                         | value                                                     |
-| `admin.vm.feature.CheckWithTemplateAndAdminVM`| vm | feature   | -                                         | value                                                     |
-| `admin.vm.feature.Remove`              | vm        | feature   | -                                         | -                                                         |
-| `admin.vm.feature.Set`                 | vm        | feature   | value                                     | -                                                         |
-| `admin.vm.tag.List`                    | vm        | -         | -                                         | `<tag>\n`                                                 |
-| `admin.vm.tag.Get`                     | vm        | tag       | -                                         | `0` or `1`                                                | retcode? |
-| `admin.vm.tag.Remove`                  | vm        | tag       | -                                         | -                                                         |
-| `admin.vm.tag.Set`                     | vm        | tag       | -                                         | -                                                         |
-| `admin.vm.firewall.Get`                | vm        | -         | -                                         | `<rule>\n`                                                | rules syntax as in [firewall interface](/doc/vm-interface/#firewall-rules-in-4x) with addition of `expire=` and `comment=` options; `comment=` (if present) must be the last option
-| `admin.vm.firewall.Set`                | vm        | -         | `<rule>\n`                                | -                                                         | set firewall rules, see `admin.vm.firewall.Get` for syntax
-| `admin.vm.firewall.Reload`             | vm        | -         | -                                         | -                                                         | force reload firewall without changing any rule
-| `admin.vm.deviceclass.List`            | `dom0`    | -         | -                                         | `<class>\n`                                               |
-| `admin.vm.device.<class>.Attach`       | vm        | device    | options                                   | -                                                         | `device` is in form `<backend-name>+<device-ident>` <br/>optional options given in `key=value` format, separated with spaces; <br/>options can include `persistent=True` to "persistently" attach the device (default is temporary)
-| `admin.vm.device.<class>.Detach`       | vm        | device    | -                                         | -                                                         | `device` is in form `<backend-name>+<device-ident>`
-| `admin.vm.device.<class>.Set.persistent`| vm       | device    | `True`\|`False`                            | -                                                         | `device` is in form `<backend-name>+<device-ident>`
-| `admin.vm.device.<class>.List`         | vm        | -         | -                                         | `<device> <options>\n`                                    | options can include `persistent=True` for "persistently" attached devices (default is temporary)
-| `admin.vm.device.<class>.Available`    | vm        | device-ident | -                                         | `<device-ident> <properties> description=<desc>\n`        | optional service argument may be used to get info about a single device, <br/>optional (device class specific) properties are in `key=value` form, <br/>`description` must be the last one and is the only one allowed to contain spaces
-| `admin.pool.List`                      | `dom0`    | -         | -                                         | `<pool>\n`                                                |
-| `admin.pool.ListDrivers`               | `dom0`    | -         | -                                         | `<pool-driver> <property> ...\n`                          | Properties allowed in `admin.pool.Add`
-| `admin.pool.Info`                      | `dom0`    | pool      | -                                         | `<property>=<value>\n`                                    |
-| `admin.pool.Add`                       | `dom0`    | driver    | `<property>=<value>\n`                    | -                                                         |
-| `admin.pool.Set.revisions_to_keep`     | `dom0`    | pool      | `<value>`                                 | -                                                         |
-| `admin.pool.Remove`                    | `dom0`    | pool      | -                                         | -                                                         |
-| `admin.pool.volume.List`               | `dom0`    | pool      | -                                         | volume id                                                 |
-| `admin.pool.volume.Info`               | `dom0`    | pool      | vid                                       | `<property>=<value>\n`                                    |
-| `admin.pool.volume.Set.revisions_to_keep`| `dom0`  | pool      | `<vid> <value>`                           | -                                                         |
-| `admin.pool.volume.ListSnapshots`      | `dom0`    | pool      | vid                                       | `<snapshot>\n`                                            |
-| `admin.pool.volume.Snapshot`           | `dom0`    | pool      | vid                                       | snapshot                                                  |
-| `admin.pool.volume.Revert`             | `dom0`    | pool      | `<vid> <snapshot>`                        | -                                                         |
-| `admin.pool.volume.Resize`             | `dom0`    | pool      | `<vid> <size_in_bytes>`                   | -                                                         |
-| `admin.pool.volume.Import`             | `dom0`    | pool      | `<vid>\n<raw volume data>`                | -                                                         |
-| `admin.pool.volume.CloneFrom`          | `dom0`    | pool      | vid                                       | token, to be used in `admin.pool.volume.CloneTo`          | obtain a token to copy volume `vid` in `pool`;<br/>the token is one time use only, it's invalidated by `admin.pool.volume.CloneTo`, even if the operation fails |
-| `admin.pool.volume.CloneTo`            | `dom0`    | pool      | `<vid> <token>`                           | -                                                         | copy volume pointed by a token to volume `vid` in `pool` |
-| `admin.vm.volume.List`                 | vm        | -         | -                                         | `<volume>\n`                                              | `<volume>` is per-VM volume name (`root`, `private`, etc), `<vid>` is pool-unique volume id
-| `admin.vm.volume.Info`                 | vm        | volume    | -                                         | `<property>=<value>\n`                                    |
-| `admin.vm.volume.Set.revisions_to_keep`| vm        | volume    | value                                     | -                                                         |
-| `admin.vm.volume.ListSnapshots`        | vm        | volume    | -                                         | snapshot                                                  | duplicate of `admin.pool.volume.`, but with other call params |
-| `admin.vm.volume.Snapshot`             | vm        | volume    | -                                         | snapshot                                                  | id. |
-| `admin.vm.volume.Revert`               | vm        | volume    | snapshot                                  | -                                                         | id. |
-| `admin.vm.volume.Resize`               | vm        | volume    | size_in_bytes                             | -                                                         | id. |
-| `admin.vm.volume.Import`               | vm        | volume    | raw volume data                           | -                                                         | id. |
-| `admin.vm.volume.ImportWithSize`       | vm        | volume    | `<size_in_bytes>\n<raw volume data>`      | -                                                         | new version of `admin.vm.volume.Import`, allows new volume to be different size |
-| `admin.vm.volume.Clear`                | vm        | volume    | -                                         | -                                                         | clear contents of volume |
-| `admin.vm.volume.CloneFrom`            | vm        | volume    | -                                         | token, to be used in `admin.vm.volume.CloneTo`            | obtain a token to copy `volume` of `vm`;<br/>the token is one time use only, it's invalidated by `admin.vm.volume.CloneTo`, even if the operation fails |
-| `admin.vm.volume.CloneTo`              | vm        | volume    | token, obtained with `admin.vm.volume.CloneFrom` | -                                                         | copy volume pointed by a token to `volume` of `vm` |
-| `admin.vm.CurrentState`                | vm        | -         | -                                         | `<state-property>=<value>\n`                              | state properties: `power_state`, `mem`, `mem_static_max`, `cputime`
-| `admin.vm.Start`                       | vm        | -         | -                                         | -                                                         |
-| `admin.vm.Shutdown`                    | vm        | -         | -                                         | -                                                         |
-| `admin.vm.Pause`                       | vm        | -         | -                                         | -                                                         |
-| `admin.vm.Unpause`                     | vm        | -         | -                                         | -                                                         |
-| `admin.vm.Kill`                        | vm        | -         | -                                         | -                                                         |
-| `admin.backup.Execute`                 | `dom0`    | config id | -                                         | -                                                         | config in `/etc/qubes/backup/<id>.conf`, only one backup operation of given `config id` can be running at once |
-| `admin.backup.Info`                    | `dom0`    | config id | -                                         | backup info                                               | info what would be included in the backup
-| `admin.backup.Cancel`                  | `dom0`    | config id | -                                         | -                                                         | cancel running backup operation
-| `admin.Events`                         | `dom0|vm` | -         | -                                         | events                                                    |
-| `admin.vm.Stats`                       | `dom0|vm` | -         | -                                         | `vm-stats` events, see below                              | emit VM statistics (CPU, memory usage) in form of events
+| call                                           | dest       | argument     | inside                                                              | return                                              | note |
+|------------------------------------------------|------------|--------------|---------------------------------------------------------------------|-----------------------------------------------------| ---- |
+| `admin.vmclass.List`                           | `dom0`     | -            | -                                                                   | `<class>\n`                                         |
+| `admin.vm.List`                                | `dom0      | <vm>`        | -                                                                   | -                                                   | `<name> class=<class> state=<state>\n`                    |
+| `admin.vm.Create.<class>`                      | `dom0`     | template     | `name=<name> label=<label>`                                         | -                                                   |
+| `admin.vm.CreateInPool.<class>`                | `dom0`     | template     | `name=<name> label=<label> `<br/>`pool=<pool> pool:<volume>=<pool>` | -                                                   | either use `pool=` to put all volumes there, <br/>or `pool:<volume>=` for individual volumes - both forms are not allowed at the same time
+| `admin.vm.CreateDisposable`                    | template   | -            | -                                                                   | name                                                | Create new DisposableVM, `template` is any AppVM with `dispvm_allowed` set to True, or `dom0` to use default defined in `default_dispvm` property of calling VM; VM created with this call will be automatically removed after its shutdown; the main difference from `admin.vm.Create.DispVM` is automatic (random) name generation.
+| `admin.vm.Remove`                              | vm         | -            | -                                                                   | -                                                   |
+| `admin.label.List`                             | `dom0`     | -            | -                                                                   | `<property>\n`                                      |
+| `admin.label.Create`                           | `dom0`     | label        | `0xRRGGBB`                                                          | -                                                   |
+| `admin.label.Get`                              | `dom0`     | label        | -                                                                   | `0xRRGGBB`                                          |
+| `admin.label.Index`                            | `dom0`     | label        | -                                                                   | `<label-index>`                                     |
+| `admin.label.Remove`                           | `dom0`     | label        | -                                                                   | -                                                   |
+| `admin.property.List`                          | `dom0`     | -            | -                                                                   | `<property>\n`                                      |
+| `admin.property.Get`                           | `dom0`     | property     | -                                                                   | `default={True                                      |False} `<br/>`type={str|int|bool|vm|label|list} <value>`   | Type `list` is added in R4.1. Values are of type `str` and each entry is suffixed with newline character.
+| `admin.property.GetAll`                        | `dom0`     | -            | -                                                                   | `<property-name> <full-value-as-in-property.Get>\n` | Get all the properties in one call. Each property is returned on a separate line and use the same value encoding as property.Get method, with an exception that newlines are encoded as literal `\n` and literal `\` are encoded as `\\`.
+| `admin.property.GetDefault`                    | `dom0`     | property     | -                                                                   | `type={str                                          |int|bool|vm|label|list} <value>`               | Type `list` is added in R4.1. Values are of type `str` and each entry is suffixed with newline character.
+| `admin.property.Help`                          | `dom0`     | property     | -                                                                   | `help`                                              |
+| `admin.property.HelpRst`                       | `dom0`     | property     | -                                                                   | `help.rst`                                          |
+| `admin.property.Reset`                         | `dom0`     | property     | -                                                                   | -                                                   |
+| `admin.property.Set`                           | `dom0`     | property     | value                                                               | -                                                   |
+| `admin.vm.property.List`                       | vm         | -            | -                                                                   | `<property>\n`                                      |
+| `admin.vm.property.Get`                        | vm         | property     | -                                                                   | `default={True                                      |False} `<br/>`type={str|int|bool|vm|label|list} <value>`   | Type `list` is added in R4.1. Each list entry is suffixed with a newline character.
+| `admin.vm.property.GetAll`                     | vm         | -            | -                                                                   | `<property-name> <full-value-as-in-property.Get>\n` | Get all the properties in one call. Each property is returned on a separate line and use the same value encoding as property.Get method, with an exception that newlines are encoded as literal `\n` and literal `\` are encoded as `\\`.
+| `admin.vm.property.GetDefault`                 | vm         | property     | -                                                                   | `type={str                                          |int|bool|vm|label|type} <value>`               | Type `list` is added in R4.1. Each list entry is suffixed with a newline character.
+| `admin.vm.property.Help`                       | vm         | property     | -                                                                   | `help`                                              |
+| `admin.vm.property.HelpRst`                    | vm         | property     | -                                                                   | `help.rst`                                          |
+| `admin.vm.property.Reset`                      | vm         | property     | -                                                                   | -                                                   |
+| `admin.vm.property.Set`                        | vm         | property     | value                                                               | -                                                   |
+| `admin.vm.feature.List`                        | vm         | -            | -                                                                   | `<feature>\n`                                       |
+| `admin.vm.feature.Get`                         | vm         | feature      | -                                                                   | value                                               |
+| `admin.vm.feature.CheckWithTemplate`           | vm         | feature      | -                                                                   | value                                               |
+| `admin.vm.feature.CheckWithNetvm`              | vm         | feature      | -                                                                   | value                                               |
+| `admin.vm.feature.CheckWithAdminVM`            | vm         | feature      | -                                                                   | value                                               |
+| `admin.vm.feature.CheckWithTemplateAndAdminVM` | vm         | feature      | -                                                                   | value                                               |
+| `admin.vm.feature.Remove`                      | vm         | feature      | -                                                                   | -                                                   |
+| `admin.vm.feature.Set`                         | vm         | feature      | value                                                               | -                                                   |
+| `admin.vm.tag.List`                            | vm         | -            | -                                                                   | `<tag>\n`                                           |
+| `admin.vm.tag.Get`                             | vm         | tag          | -                                                                   | `0` or `1`                                          | retcode? |
+| `admin.vm.tag.Remove`                          | vm         | tag          | -                                                                   | -                                                   |
+| `admin.vm.tag.Set`                             | vm         | tag          | -                                                                   | -                                                   |
+| `admin.vm.firewall.Get`                        | vm         | -            | -                                                                   | `<rule>\n`                                          | rules syntax as in [firewall interface](/doc/vm-interface/#firewall-rules-in-4x) with addition of `expire=` and `comment=` options; `comment=` (if present) must be the last option
+| `admin.vm.firewall.Set`                        | vm         | -            | `<rule>\n`                                                          | -                                                   | set firewall rules, see `admin.vm.firewall.Get` for syntax
+| `admin.vm.firewall.Reload`                     | vm         | -            | -                                                                   | -                                                   | force reload firewall without changing any rule
+| `admin.vm.device.<class>.Attach`               | vm         | device       | assignment-serialization                                            | -                                                   | `device` is in form `<backend-name>+<device-ident>` <br/>optional options given in `key=value` format, separated with spaces; <br/>options can include `persistent=True` to "persistently" attach the device (default is temporary)
+| `admin.vm.device.<class>.Detach`               | vm         | device       | -                                                                   | -                                                   | `device` is in form `<backend-name>+<device-ident>`.
+| `admin.vm.device.<class>.Assign`               | vm         | device       | assignment-serialization                                            | -                                                   | `device` is in form `<backend-name>+<device-ident>` <br/> `assignment-serialization` is specified in the section Device Serialization.
+| `admin.vm.device.<class>.Unassign`             | vm         | device       | -                                                                   | -                                                   | `device` is in form `<backend-name>+<device-ident>`.
+| `admin.vm.device.<class>.Set.required`         | vm         | device       | `True`\|`False`                                                     | -                                                   | `device` is in form `<backend-name>+<device-ident>`
+| `admin.vm.deviceclass.List`                    | `dom0`     | -            | -                                                                   | `<deviceclass>\n`                                   |
+| `admin.vm.device.<class>.Available`            | vm         | device-ident | -                                                                   | `<device-ident> <device-serialization>\n`           | optional service argument may be used to get info about a single device, <br/> `device-serialization` is specified in the section Device Serialization.
+| `admin.vm.device.<class>.Assigned`             | vm         | device-ident | -                                                                   | `<device-ident> <assignment-serialization>\n`       | optional service argument may be used to get info about a single device, <br/> `assignment-serialization` is specified in the section Device Serialization.
+| `admin.vm.device.<class>.Attached`             | vm         | device-ident | -                                                                   | `<device-ident> <assignment-serialization>\n`       | optional service argument may be used to get info about a single device, <br/> `assignment-serialization` is specified in the section Device Serialization.
+| `admin.pool.List`                              | `dom0`     | -            | -                                                                   | `<pool>\n`                                          |
+| `admin.pool.ListDrivers`                       | `dom0`     | -            | -                                                                   | `<pool-driver> <property> ...\n`                    | Properties allowed in `admin.pool.Add`
+| `admin.pool.Info`                              | `dom0`     | pool         | -                                                                   | `<property>=<value>\n`                              |
+| `admin.pool.Add`                               | `dom0`     | driver       | `<property>=<value>\n`                                              | -                                                   |
+| `admin.pool.Set.revisions_to_keep`             | `dom0`     | pool         | `<value>`                                                           | -                                                   |
+| `admin.pool.Remove`                            | `dom0`     | pool         | -                                                                   | -                                                   |
+| `admin.pool.volume.List`                       | `dom0`     | pool         | -                                                                   | volume id                                           |
+| `admin.pool.volume.Info`                       | `dom0`     | pool         | vid                                                                 | `<property>=<value>\n`                              |
+| `admin.pool.volume.Set.revisions_to_keep`      | `dom0`     | pool         | `<vid> <value>`                                                     | -                                                   |
+| `admin.pool.volume.ListSnapshots`              | `dom0`     | pool         | vid                                                                 | `<snapshot>\n`                                      |
+| `admin.pool.volume.Snapshot`                   | `dom0`     | pool         | vid                                                                 | snapshot                                            |
+| `admin.pool.volume.Revert`                     | `dom0`     | pool         | `<vid> <snapshot>`                                                  | -                                                   |
+| `admin.pool.volume.Resize`                     | `dom0`     | pool         | `<vid> <size_in_bytes>`                                             | -                                                   |
+| `admin.pool.volume.Import`                     | `dom0`     | pool         | `<vid>\n<raw volume data>`                                          | -                                                   |
+| `admin.pool.volume.CloneFrom`                  | `dom0`     | pool         | vid                                                                 | token, to be used in `admin.pool.volume.CloneTo`    | obtain a token to copy volume `vid` in `pool`;<br/>the token is one time use only, it's invalidated by `admin.pool.volume.CloneTo`, even if the operation fails |
+| `admin.pool.volume.CloneTo`                    | `dom0`     | pool         | `<vid> <token>`                                                     | -                                                   | copy volume pointed by a token to volume `vid` in `pool` |
+| `admin.vm.volume.List`                         | vm         | -            | -                                                                   | `<volume>\n`                                        | `<volume>` is per-VM volume name (`root`, `private`, etc), `<vid>` is pool-unique volume id
+| `admin.vm.volume.Info`                         | vm         | volume       | -                                                                   | `<property>=<value>\n`                              |
+| `admin.vm.volume.Set.revisions_to_keep`        | vm         | volume       | value                                                               | -                                                   |
+| `admin.vm.volume.ListSnapshots`                | vm         | volume       | -                                                                   | snapshot                                            | duplicate of `admin.pool.volume.`, but with other call params |
+| `admin.vm.volume.Snapshot`                     | vm         | volume       | -                                                                   | snapshot                                            | id. |
+| `admin.vm.volume.Revert`                       | vm         | volume       | snapshot                                                            | -                                                   | id. |
+| `admin.vm.volume.Resize`                       | vm         | volume       | size_in_bytes                                                       | -                                                   | id. |
+| `admin.vm.volume.Import`                       | vm         | volume       | raw volume data                                                     | -                                                   | id. |
+| `admin.vm.volume.ImportWithSize`               | vm         | volume       | `<size_in_bytes>\n<raw volume data>`                                | -                                                   | new version of `admin.vm.volume.Import`, allows new volume to be different size |
+| `admin.vm.volume.Clear`                        | vm         | volume       | -                                                                   | -                                                   | clear contents of volume |
+| `admin.vm.volume.CloneFrom`                    | vm         | volume       | -                                                                   | token, to be used in `admin.vm.volume.CloneTo`      | obtain a token to copy `volume` of `vm`;<br/>the token is one time use only, it's invalidated by `admin.vm.volume.CloneTo`, even if the operation fails |
+| `admin.vm.volume.CloneTo`                      | vm         | volume       | token, obtained with `admin.vm.volume.CloneFrom`                    | -                                                   | copy volume pointed by a token to `volume` of `vm` |
+| `admin.vm.CurrentState`                        | vm         | -            | -                                                                   | `<state-property>=<value>\n`                        | state properties: `power_state`, `mem`, `mem_static_max`, `cputime`
+| `admin.vm.Start`                               | vm         | -            | -                                                                   | -                                                   |
+| `admin.vm.Shutdown`                            | vm         | -            | -                                                                   | -                                                   |
+| `admin.vm.Pause`                               | vm         | -            | -                                                                   | -                                                   |
+| `admin.vm.Unpause`                             | vm         | -            | -                                                                   | -                                                   |
+| `admin.vm.Kill`                                | vm         | -            | -                                                                   | -                                                   |
+| `admin.backup.Execute`                         | `dom0`     | config id    | -                                                                   | -                                                   | config in `/etc/qubes/backup/<id>.conf`, only one backup operation of given `config id` can be running at once |
+| `admin.backup.Info`                            | `dom0`     | config id    | -                                                                   | backup info                                         | info what would be included in the backup
+| `admin.backup.Cancel`                          | `dom0`     | config id    | -                                                                   | -                                                   | cancel running backup operation
+| `admin.Events`                                 | `dom0      | vm`          | -                                                                   | -                                                   | events                                                    |
+| `admin.vm.Stats`                               | `dom0      | vm`          | -                                                                   | -                                                   | `vm-stats` events, see below                              | emit VM statistics (CPU, memory usage) in form of events
 
 Volume properties:
 
@@ -302,6 +305,58 @@ destination_vm: sys-net
 destination_path: ncftpput -u my-ftp-username -p my-ftp-pass -c my-ftp-server /directory/for/backups
 ```
 
+## Device Serialization
+
+Both device and assignment serialization is ASCII-encoded and contains 
+space-separated key-value pairs. The format includes an `=` between the key 
+and value, and the value is always enclosed in single quotes (`'`). 
+Values may contain spaces or even single quotes, which are escaped with a backslash. 
+If a value is not set (`None`), it is represented as `'unknown'`. 
+For boolean values, `True` is represented as `'yes'`, and `False` as `'no'`. 
+The order of key-value pairs is irrelevant. Keys starting with `_` 
+are considered extra properties and are saved in `data` or `options` 
+for device or assignment respectively.
+
+Information about the serialization format of specific properties can be found below.
+
+Format:
+```
+<ident> <property_1>='<value_1>' <property_2>='<value_2>' <property_3>='<value_3>'...
+```
+
+Detailed serialization format for a device:
+
+- `ident='<ident>'`
+- `backend_domain='<backend_domain.name>'`
+- `devclass='<devclass>'`
+- `vendor='<vendor>'`
+- `product='<product>'`
+- `manufacturer='<manufacturer>'`
+- `name='<name>'`
+- `serial='<serial>'`
+- `self_identity='<self_identity>'`
+- `interfaces='<interface1><interface2>...'`
+    Each device interface is represented with a 7-character length. Each device has at least one interface. Since the length of the interface representation is known, they are serialized as a single string with each interface representation concatenated one after another. The order is irrelevant.
+- `parent_ident='<parent.ident>' parent_devclass='<parent.devclass>'`
+- `attachment='<attachment.name>'`
+- `_<key1>='<value1>' _<key2>='<value2>' ...` (extra parameters)
+
+Detailed serialization format for an assignment:
+
+- `ident='<ident>'`
+- `backend_domain='<backend_domain.name>'`
+- `devclass='<devclass>'`
+- `frontend_domain='<frontend_domain.name>'`
+- `required='<yes/no>'` (default 'no')
+- `attach_automatically='<yes/no>'` (default 'no')
+- `_<key1>='<str(value1)>' _<key2>='<str(value2)>' ...` (options)
+
+Example device serialization:
+
+```
+1-1.1.1 manufacturer='unknown' self_identity='0000:0000::?******' serial='unknown' ident='1-1.1.1' product='Qubes' vendor='ITL' name='Some untrusted garbage' devclass='bus' backend_domain='vm' interfaces=' ******u03**01' _additional_info='' _date='06.12.23' parent_ident='1-1.1' parent_devclass='None'
+```
+
 ## General notes
 
 - there is no provision for `qvm-run`, but there already exists `qubes.VMShell` call

From 13b46e5c0c891c37370871f159d6ca3cdaa153c4 Mon Sep 17 00:00:00 2001
From: ooops <kennethrrosen@proton.me>
Date: Mon, 8 Jul 2024 15:11:44 -0400
Subject: [PATCH 31/87] Update split-gpg.md

---
 user/security-in-qubes/split-gpg.md | 37 ++++++++---------------------
 1 file changed, 10 insertions(+), 27 deletions(-)

diff --git a/user/security-in-qubes/split-gpg.md b/user/security-in-qubes/split-gpg.md
index 637b068f..b1c93963 100644
--- a/user/security-in-qubes/split-gpg.md
+++ b/user/security-in-qubes/split-gpg.md
@@ -42,24 +42,24 @@ This way it would be easy to spot unexpected requests to decrypt documents.
 
 ## Configuring Split GPG
 
-In dom0, make sure the `qubes-gpg-split-dom0` package is installed.
+In dom0, make sure the `split-gpg2-dom0` package is installed.
 
 ```
-[user@dom0 ~]$ sudo qubes-dom0-update qubes-gpg-split-dom0
+[user@dom0 ~]$ sudo qubes-dom0-update split-gpg2-dom0
 ```
 
-Make sure you have the `qubes-gpg-split` package installed in the template you will use for the GPG domain.
+Make sure you have the `split-gpg2` package installed in the template you will use for the GPG domain.
 
 For Debian or Whonix:
 
 ```
-[user@debian-10 ~]$ sudo apt install qubes-gpg-split
+[user@debian ~]$ sudo apt install split-gpg2
 ```
 
 For Fedora:
 
 ```
-[user@fedora-32 ~]$ sudo dnf install qubes-gpg-split
+[user@fedora ~]$ sudo dnf install split-gpg2
 ```
 
 ### Setting up the GPG backend domain
@@ -91,9 +91,7 @@ You can override it e.g. in `~/.profile`:
 [user@work-gpg ~]$ echo "export QUBES_GPG_AUTOACCEPT=86400" >> ~/.profile
 ```
 
-Please note that previously, this parameter was set in ~/.bash_profile.
-This will no longer work.
-If you have the parameter set in ~/.bash_profile you *must* update your configuration.
+Please note that previously, this parameter was set in ~/.bash_profile. This will no longer work. If you have the parameter set in ~/.bash_profile you *must* update your configuration.
 
 Please be aware of the caveat regarding passphrase-protected keys in the [Current limitations](#current-limitations) section.
 
@@ -118,11 +116,6 @@ ssb   4096R/30498E2A 2012-11-15
 
 Note that running normal `gpg -K` in the demo above shows no private keys stored in this app qube.
 
-A note on `gpg` and `gpg2`:
-
-Throughout this guide, we refer to `gpg`, but note that Split GPG uses `gpg2` under the hood for compatibility with programs like Enigmail (which now supports only `gpg2`).
-If you encounter trouble while trying to set up Split GPG, make sure you're using `gpg2` for your configuration and testing, since keyring data may differ between the two installations.
-
 ### Advanced Configuration
 
 The `qubes-gpg-client-wrapper` script sets the `QUBES_GPG_DOMAIN` variable automatically based on the content of the file `/rw/config/gpg-split-domain`, which should be set to the name of the GPG backend VM. This file survives the app qube reboot, of course.
@@ -132,21 +125,15 @@ The `qubes-gpg-client-wrapper` script sets the `QUBES_GPG_DOMAIN` variable autom
 [root@work-email ~]$ echo "work-gpg" > /rw/config/gpg-split-domain
 ```
 
-Split GPG's default qrexec policy requires the user to enter the name of the app qube containing GPG keys on each invocation. To improve usability for applications like Thunderbird with Enigmail, in `dom0` place the following line at the top of the file `/etc/qubes-rpc/policy/qubes.Gpg`:
+Split GPG's default qrexec policy requires the user to enter the name of the app qube containing GPG keys on each invocation. To improve usability for applications like Thunderbird with Enigmail, in `dom0` you can make additional changes to `/etc/qubes-rpc/policy.d/50-config-splitgpg.policy` or by using the CLI or GUI:
 
 ```
-work-email  work-gpg  allow
+sudo qubes-policy-editor
+sudo qubes-policy-editor-gui
 ```
 
-where `work-email` is the Thunderbird + Enigmail app qube and `work-gpg` contains your GPG keys.
+Documentation for syntax examples is included within the GUI. Note that, because this makes it easier to accept Split GPG's qrexec authorization prompts, it may decrease security if the user is not careful in reviewing presented prompts. This may also be inadvisable if there are multiple app qubes with Split GPG set up. 
 
-You may also edit the qrexec policy file for Split GPG in order to tell Qubes your default gpg vm (qrexec prompts will appear with the gpg vm preselected as the target, instead of the user needing to type a name in manually). To do this, append `default_target=<vmname>` to `ask` in `/etc/qubes-rpc/policy/qubes.Gpg`. For the examples given on this page:
-
-```
-@anyvm  @anyvm  ask default_target=work-gpg
-```
-
-Note that, because this makes it easier to accept Split GPG's qrexec authorization prompts, it may decrease security if the user is not careful in reviewing presented prompts. This may also be inadvisable if there are multiple app qubes with Split GPG set up.
 
 ## Using Thunderbird
 
@@ -378,10 +365,6 @@ As always, exercise caution and use your good judgment.)
 
 ## Current limitations
 
-* Current implementation requires importing of public keys to the vault domain.
-  This opens up an avenue to attack the gpg running in the backend domain via a hypothetical bug in public key importing code.
-  See ticket [#474](https://github.com/QubesOS/qubes-issues/issues/474) for more details and plans how to get around this problem, as well as the section on [using Split GPG with subkeys](#advanced-using-split-gpg-with-subkeys).
-
 * It doesn't solve the problem of allowing the user to know what is to be signed before the operation gets approved.
   Perhaps the GPG backend domain could start a disposable and have the to-be-signed document displayed there? To Be Determined.
 

From 2d5c636c05b1a8fd78eaaab59ea76307bc919b47 Mon Sep 17 00:00:00 2001
From: ooops <kennethrrosen@proton.me>
Date: Mon, 8 Jul 2024 15:33:48 -0400
Subject: [PATCH 32/87] Includes updated documentation from split-gpg2

Fixes QubesOS/qubes-issues/issues/9138
---
 user/security-in-qubes/split-gpg.md | 365 ++++++----------------------
 1 file changed, 73 insertions(+), 292 deletions(-)

diff --git a/user/security-in-qubes/split-gpg.md b/user/security-in-qubes/split-gpg.md
index b1c93963..f31d1552 100644
--- a/user/security-in-qubes/split-gpg.md
+++ b/user/security-in-qubes/split-gpg.md
@@ -37,342 +37,123 @@ Unfortunately this problem of signing reliability is not solvable by Split GPG.)
 With Qubes Split GPG this problem is drastically minimized, because each time the key is to be used the user is asked for consent (with a definable time out, 5 minutes by default), plus is always notified each time the key is used via a tray notification from the domain where GPG backend is running.
 This way it would be easy to spot unexpected requests to decrypt documents.
 
-[![r2-split-gpg-1.png](/attachment/doc/r2-split-gpg-1.png)](/attachment/doc/r2-split-gpg-1.png)
-[![r2-split-gpg-3.png](/attachment/doc/r2-split-gpg-3.png)](/attachment/doc/r2-split-gpg-3.png)
+## Configuration
 
-## Configuring Split GPG
-
-In dom0, make sure the `split-gpg2-dom0` package is installed.
+Create/Edit `/etc/qubes/policy.d/30-user-gpg2.policy` in dom0, and add a line like this:
 
 ```
-[user@dom0 ~]$ sudo qubes-dom0-update split-gpg2-dom0
+qubes.Gpg2 + gpg-client-vm @default allow target=gpg-server-vm
 ```
 
-Make sure you have the `split-gpg2` package installed in the template you will use for the GPG domain.
-
-For Debian or Whonix:
+Import/Generate your secret keys in the server domain.
+For example:
 
 ```
-[user@debian ~]$ sudo apt install split-gpg2
+gpg-server-vm$ gpg --import /path/to/my/secret-keys-export
+gpg-server-vm$ gpg --import-ownertrust /path/to/my/ownertrust-export
 ```
-
-For Fedora:
+or
 
 ```
-[user@fedora ~]$ sudo dnf install split-gpg2
+gpg-server-vm$ gpg --gen-key
 ```
 
-### Setting up the GPG backend domain
+In dom0 enable the `split-gpg2-client` service in the client domain, for example via the command-line:
 
-First, create a dedicated app qube for storing your keys (we will be calling it the GPG backend domain).
-It is recommended that this domain be network disconnected (set its netvm to `none`) and only used for this one purpose.
-In later examples this app qube is named `work-gpg`, but of course it might have any other name.
-
-Make sure that gpg is installed there.
-At this stage you can add the private keys you want to store there, or you can now set up Split GPG and add the keys later.
-To check which private keys are in your GPG keyring, use:
-
-```shell_session
-[user@work-gpg ~]$ gpg -K
-/home/user/.gnupg/secring.gpg
------------------------------
-sec   4096R/3F48CB21 2012-11-15
-uid                  Qubes OS Security Team <security@qubes-os.org>
-ssb   4096R/30498E2A 2012-11-15
-(...)
+```shell
+dom0$ qvm-service <SPLIT_GPG2_CLIENT_DOMAIN_NAME> split-gpg2-client on
 ```
 
-This is pretty much all that is required.
-However, you might want to modify the default timeout: this tells the backend for how long the user's approval for key access should be valid.
-(The default is 5 minutes.) You can change this via the `QUBES_GPG_AUTOACCEPT` environment variable.
-You can override it e.g. in `~/.profile`:
+To verify if this was done correctly:
 
-```shell_session
-[user@work-gpg ~]$ echo "export QUBES_GPG_AUTOACCEPT=86400" >> ~/.profile
+```shell
+dom0$ qvm-service <SPLIT_GPG2_CLIENT_DOMAIN_NAME>
 ```
 
-Please note that previously, this parameter was set in ~/.bash_profile. This will no longer work. If you have the parameter set in ~/.bash_profile you *must* update your configuration.
+Output should be:
 
-Please be aware of the caveat regarding passphrase-protected keys in the [Current limitations](#current-limitations) section.
-
-### Configuring the client apps to use Split GPG backend
-
-Normally it should be enough to set the `QUBES_GPG_DOMAIN` to the GPG backend domain name and use `qubes-gpg-client` in place of `gpg`, e.g.:
-
-```shell_session
-[user@work-email ~]$ export QUBES_GPG_DOMAIN=work-gpg
-[user@work-email ~]$ gpg -K
-[user@work-email ~]$ qubes-gpg-client -K
-/home/user/.gnupg/secring.gpg
------------------------------
-sec   4096R/3F48CB21 2012-11-15
-uid                  Qubes OS Security Team <security@qubes-os.org>
-ssb   4096R/30498E2A 2012-11-15
-(...)
-
-[user@work-email ~]$ qubes-gpg-client secret_message.txt.asc
-(...)
+```shell
+split-gpg2-client on
 ```
 
-Note that running normal `gpg -K` in the demo above shows no private keys stored in this app qube.
+Restart the client domain.
 
-### Advanced Configuration
-
-The `qubes-gpg-client-wrapper` script sets the `QUBES_GPG_DOMAIN` variable automatically based on the content of the file `/rw/config/gpg-split-domain`, which should be set to the name of the GPG backend VM. This file survives the app qube reboot, of course.
-
-```shell_session
-[user@work-email ~]$ sudo bash
-[root@work-email ~]$ echo "work-gpg" > /rw/config/gpg-split-domain
-```
-
-Split GPG's default qrexec policy requires the user to enter the name of the app qube containing GPG keys on each invocation. To improve usability for applications like Thunderbird with Enigmail, in `dom0` you can make additional changes to `/etc/qubes-rpc/policy.d/50-config-splitgpg.policy` or by using the CLI or GUI:
+Export the **public** part of your keys and import them in the client domain.
+Also import/set proper "ownertrust" values.
+For example:
 
 ```
-sudo qubes-policy-editor
-sudo qubes-policy-editor-gui
+gpg-server-vm$ gpg --export > public-keys-export
+gpg-server-vm$ gpg --export-ownertrust > ownertrust-export
+gpg-server-vm$ qvm-copy public-keys-export ownertrust-export
+
+gpg-client-vm$ gpg --import ~/QubesIncoming/gpg-server-vm/public-keys-export
+gpg-client-vm$ gpg --import-ownertrust ~/QubesIncoming/gpg-server-vm/ownertrust-export
 ```
 
-Documentation for syntax examples is included within the GUI. Note that, because this makes it easier to accept Split GPG's qrexec authorization prompts, it may decrease security if the user is not careful in reviewing presented prompts. This may also be inadvisable if there are multiple app qubes with Split GPG set up. 
-
-
-## Using Thunderbird
-
-### Thunderbird 78 and higher
-
-Starting with version 78, Thunderbird has a built-in PGP feature and no longer requires the Enigmail extension. For users coming from the Enigmail extension, the built-in functionality is more limited currently, including that **public keys must live in your `work-email` qube with Thunderbird rather than your offline `work-gpg` qube**.
-
-In `work-email`, use the Thunderbird config editor (found at the bottom of preferences/options), and search for `mail.openpgp.allow_external_gnupg`. Switch the value to true. Still in config editor, search for `mail.openpgp.alternative_gpg_path`. Set its value to `/usr/bin/qubes-gpg-client-wrapper`. Restart Thunderbird after this change.
-
-[![tb78-1.png](/attachment/doc/tb78-1.png)](/attachment/doc/tb78-1.png)
-[![tb78-2.png](/attachment/doc/tb78-2.png)](/attachment/doc/tb78-2.png)
-[![tb78-3.png](/attachment/doc/tb78-3.png)](/attachment/doc/tb78-3.png)
-
-You need to obtain your key ID which should be **exactly 16 characters**. Enter the command `qubes-gpg-client-wrapper -K --keyid-format long`:
-
+This should be enough to have it running:
 ```
-[user@work-email ~]$ qubes-gpg-client-wrapper -K --keyid-format long
+gpg-client-vm$ gpg -K
 /home/user/.gnupg/pubring.kbx
 -----------------------------
-sec   rsa2048/777402E6D301615C 2020-09-05 [SC] [expires: 2022-09-05]
-      F7D2D4E922DFB7B2589AF3E9777402E6D301615C
-uid                 [ultimate] Qubes test <user@localhost>
-ssb   rsa2048/370CE932085BA13B 2020-09-05 [E] [expires: 2022-09-05]
+sec#  rsa2048 2019-12-18 [SC] [expires: 2021-12-17]
+      50C2035AF57B98CD6E4010F1B808E4BB07BA9EFB
+uid           [ultimate] test
+ssb#  rsa2048 2019-12-18 [E]
 ```
 
-```
-[user@work-email ~]$ qubes-gpg-client-wrapper --armor --export 777402E6D301615C > 777402E6D301615C.asc
-```
+If you want change some server option copy `/usr/share/doc/split-gpg2/examples/qubes-split-gpg2.conf.example` to `~/.config/qubes-split-gpg2/qubes-split-gpg2.conf` and change it as desired, it will take precedence over other loaded files, such as the drop-in configuration files with the suffix `.conf` in `~/.config/qubes-split-gpg2/conf.d/`.
 
-Open the Account Settings and open the *End-to-End Encryption* tab of the respective email account. Click the *Add Key* button. You'll be offered the choice *Use your external key through GnuPG*. Select it and click Continue.
+If you have a passphrase on your keys and `gpg-agent` only shows the "keygrip" (something like the fingerprint of the private key) when asking for the passphrase, then make sure that you have imported the public key part in the server domain.
 
-[![tb78-4.png](/attachment/doc/tb78-4.png)](/attachment/doc/tb78-4.png)
-[![tb78-5.png](/attachment/doc/tb78-5.png)](/attachment/doc/tb78-5.png)
+## Subkeys vs primary keys
 
-The key ID reference you would need here is `777402E6D301615C`. Now paste or type the ID of the secret key that you would like to use. Be careful to enter it correctly, because your input isn't verified. Confirm to save this key ID. Now you can select the key ID to use.
+split-gpg2 only knows a hash of the data being signed.
+Therefore, it cannot differentiate between e.g. signatures of a piece of data or signatures of another key.
+This means that a client can use split-gpg2 to sign other keys, which split-gpg1 did not allow.
 
-[![tb78-6.png](/attachment/doc/tb78-6.png)](/attachment/doc/tb78-6.png)
-[![tb78-7.png](/attachment/doc/tb78-7.png)](/attachment/doc/tb78-7.png)
+To prevent this, split-gpg2 creates a new GnuPG home directory and imports the secret subkeys (**not** the primary key!) to it.
+Clients will be able to use the secret parts of the subkeys, but not of the primary key.
+If your primary key is able to sign data and certify other keys, and your only subkey can only perform encryption, this means that all signing will fail.
+To make signing work again, generate a subkey that is capable of signing but **not** certification.
+split-gpg2 does not generate this key for you, so you need to generate it yourself.
+If you want to generate a key in software, use the `addkey` command of `gpg2 --edit-key`.
+If you want to generate a key on a smartcard or other hardware token, use `addcardkey` instead.
 
-This key ID will be used to digitally sign or send an encrypted message with your account. For this to work, Thunderbird needs a copy of your public key. At this time, Thunderbird doesn't fetch the public key from `/usr/bin/qubes-gpg-client-wrapper`, you must manually import it. Export the key as follow (assuming the key ID would be `777402E6D301615C`):
+## Advanced usage
 
-[![tb78-8.png](/attachment/doc/tb78-8.png)](/attachment/doc/tb78-8.png)
-[![tb78-9.png](/attachment/doc/tb78-9.png)](/attachment/doc/tb78-9.png)
+There are a few option not described in this README.
+See the comments in the example (config and the source code)[https://github.com/QubesOS/qubes-app-linux-split-gpg2/blob/main/qubes-split-gpg2.conf.example].
 
-Use Thunderbird's Tools menu to open *OpenPGP Key Management*. In that window, use the File menu to access the *Import Public Key(s) From File* command. Open the file with your public key. After the import was successful, right click on the imported key in the list and select *Key Properties*. You must mark your own key as *Yes, I've verified in person this key has the correct fingerprint*.
+Similar to a smartcard, split-gpg2 only tries to protect the private key.
+For advanced usages, consider if a specialized RPC service would be better.
+It could do things like checking what data is singed, detailed logging, exposing the encrypted content only to a VM without network, etc.
 
-Once this is done, you should be able to send an encrypted and signed email by selecting *Require Encryption* or *Digitally Sign This Message* in the compose menu *Options* or *Security* toolbar button. You can try it by sending an email to yourself.
+Using split-gpg2 as the "backend" for split-gpg1 is known to work.
 
-[![tb78-10.png](/attachment/doc/tb78-10.png)](/attachment/doc/tb78-10.png)
+## Allow key generation
 
-For more details about using smart cards/Split GPG with Thunderbird PGP feature, please see [Thunderbird:OpenPGP:Smartcards](https://wiki.mozilla.org/Thunderbird:OpenPGP:Smartcards) from which the above documentation is inspired.
+By setting `allow_keygen = yes` in `qubes-split-gpg2.conf` you can allow the client to generate new keys.
+Normal usage should not need this.
 
-### Older Thunderbird versions
+**Warning**: This feature is new and not much tested.
+Therefore it's not security supported!
 
-For Thunderbird versions below 78, the traditional Enigmail + Split GPG setup is required.
-It is recommended to set up and use `/usr/bin/qubes-gpg-client-wrapper`, as discussed above, in Thunderbird through the Enigmail addon.
+## Copyright
 
-**Warning:** Before adding any account, configuring Enigmail with `/usr/bin/qubes-gpg-client-wrapper` is **required**. By default, Enigmail will generate a default GPG key in `work-email` associated with the newly created Thunderbird account. Generally, it corresponds to the email used in `work-gpg` associated to your private key. In consequence, a new, separate private key will be stored in `work-email` but it _does not_ correspond to your private key in `work-gpg`. Comparing the `fingerprint` or `expiration date` will show that they are not the same private key. In order to prevent Enigmail using this default generated local key in `work-email`, you can safely remove it.
+Copyright (C) 2014 HW42 <hw42@ipsumj.de>\
+Copyright (C) 2019 Marek Marczykowski-Górecki <marmarek@invisiblethingslab.com>
 
-On a fresh Enigmail install, your need to change the default `Enigmail Junior Mode`. Go to Thunderbird preferences and then privacy tab. Select `Force using S/MIME and Enigmail`. Then, in the preferences of Enigmail, make it point to `/usr/bin/qubes-gpg-client-wrapper` instead of the standard GnuPG binary:
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
 
-[![tb-enigmail-split-gpg-settings-2.png](/attachment/doc/tb-enigmail-split-gpg-settings-2.png)](/attachment/doc/tb-enigmail-split-gpg-settings-2.png)
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
 
-## Using Keybase with Split GPG
-
-Keybase, a security focused messaging and file-sharing app with GPG integration, can be configured to use Split GPG.
-
-The Keybase service does not preserve/pass the `QUBES_GPG_DOMAIN` environment variable through to underlying GPG processes, so it **must** be configured to use `/usr/bin/qubes-gpg-client-wrapper` (as discussed above) rather than `/usr/bin/qubes-gpg-client`.
-
-The following command will configure Keybase to use `/usr/bin/qubes-gpg-client-wrapper` instead of its built-in GPG client:
-
-```
-$ keybase config set gpg.command /usr/bin/qubes-gpg-client-wrapper
-```
-
-Now that Keybase is configured to use `qubes-gpg-client-wrapper`, you will be able to use `keybase pgp select` to choose a GPG key from your backend GPG app qube and link that key to your Keybase identity.
-
-## Using Git with Split GPG
-
-Git can be configured to utilize Split GPG, something useful if you would like to contribute to the Qubes OS Project as every commit is required to be signed.
-The most basic `~/.gitconfig` file enabling Split GPG looks something like this.
-
-```
-[user]
-	name = <YOUR_NAME>
-	email = <YOUR_EMAIL_ADDRESS>
-	signingKey = <YOUR_KEY_ID>
-
-[gpg]
-	program = qubes-gpg-client-wrapper
-```
-
-Your key id is the public id of your signing key, which can be found by running `qubes-gpg-client --list-keys`.
-In this instance, the key id is E142F75A6B1B610E0E8F874FB45589245791CACB.
-
-```shell_session
-[user@work-email ~]$ qubes-gpg-client --list-keys
-/home/user/.gnupg/pubring.kbx
------------------------------
-pub   ed25519 2022-08-16 [C]
-      E142F75A6B1B610E0E8F874FB45589245791CACB
-uid           [ultimate] Qubes User <user@example.com>
-sub   ed25519 2022-08-16 [S]
-sub   cv25519 2022-08-16 [E]
-sub   ed25519 2022-08-16 [A]
-```
-
-To sign commits, you now add the "-S" flag to your commit command, which should prompt for Split GPG usage.
-If you would like to automatically sign all commits, you can add the following snippet to `~/.gitconfig`.
-
-```
-[commit]
-	gpgSign = true
-```
-
-Lastly, if you would like to add aliases to sign and verify tags using the conventions the Qubes OS Project recommends, refer to the [code signing documentation](/doc/code-signing/#using-pgp-with-git).
-
-## Importing public keys
-
-Use `qubes-gpg-import-key` in the client app qube to import the key into the GPG backend VM.
-
-```shell_session
-[user@work-email ~]$ export QUBES_GPG_DOMAIN=work-gpg
-[user@work-email ~]$ qubes-gpg-import-key ~/Downloads/marmarek.asc
-```
-
-A safe, unspoofable user consent dialog box is displayed.
-
-[![r2-split-gpg-5.png](/attachment/doc/r2-split-gpg-5.png)](/attachment/doc/r2-split-gpg-5.png)
-
-Selecting "Yes to All" will add a line in the corresponding [RPC Policy](/doc/rpc-policy/) file.
-
-## Advanced: Using Split GPG with Subkeys
-
-Users with particularly high security requirements may wish to use Split GPG with [subkeys](https://wiki.debian.org/Subkeys).
-However, this setup comes at a significant cost: It will be impossible to sign other people's keys with the master secret key without breaking this security model.
-Nonetheless, if signing others' keys is not required, then Split GPG with subkeys offers unparalleled security for one's master secret key.
-
-### Setup Description
-
-In this example, the following keys are stored in the following locations (see below for definitions of these terms):
-
-| PGP Key(s) | VM Name      |
-| ---------- | ------------ |
-| `sec`      | `vault`      |
-| `ssb`      | `work-gpg`   |
-| `pub`      | `work-email` |
-
-* `sec` (master secret key)
-
-   Depending on your needs, you may wish to create this as a **certify-only (C)** key, i.e., a key which is capable only of signing (a.k.a., "certifying") other keys.
-   This key may be created *without* an expiration date.
-   This is for two reasons.
-   First, the master secret key is never to leave the `vault` VM, so it is extremely unlikely ever to be obtained by an adversary (see below).
-   Second, an adversary who *does* manage to obtain the master secret key either possesses the passphrase to unlock the key (if one is used) or does not.
-   An adversary who *does* possess the passphrase can simply use it to legally extend the expiration date of the key (or remove it entirely).
-   An adversary who does *not* possess the passphrase cannot use the key at all.
-   In either case, an expiration date provides no additional benefit.
-
-   By the same token, however, having a passphrase on the key is of little value.
-   An adversary who is capable of stealing the key from your `vault` would almost certainly also be capable of stealing the passphrase as you enter it.
-   An adversary who obtains the passphrase can then use it in order to change or remove the passphrase from the key.
-   Therefore, using a passphrase at all should be considered optional.
-   It is, however, recommended that a **revocation certificate** be created and safely stored in multiple locations so that the master keypair can be revoked in the (exceedingly unlikely) event that it is ever compromised.
-
-* `ssb` (secret subkey)
-
-   Depending on your needs, you may wish to create two different subkeys: one for **signing (S)** and one for **encryption (E)**.
-   You may also wish to give these subkeys reasonable expiration dates (e.g., one year).
-   Once these keys expire, it is up to you whether to *renew* these keys by extending the expiration dates or to create *new* subkeys when the existing set expires.
-
-   On the one hand, an adversary who obtains any existing encryption subkey (for example) will be able to use it in order to decrypt all emails (for example) which were encrypted to that subkey.
-   If the same subkey were to continue to be used--and its expiration date continually extended--only that one key would need to be stolen (e.g., as a result of the `work-gpg` VM being compromised; see below) in order to decrypt *all* of the user's emails.
-   If, on the other hand, each encryption subkey is used for at most approximately one year, then an adversary who obtains the secret subkey will be capable of decrypting at most approximately one year's worth of emails.
-
-   On the other hand, creating a new signing subkey each year without renewing (i.e., extending the expiration dates of) existing signing subkeys would mean that all of your old signatures would eventually read as "EXPIRED" whenever someone attempts to verify them.
-   This can be problematic, since there is no consensus on how expired signatures should be handled.
-   Generally, digital signatures are intended to last forever, so this is a strong reason against regularly retiring one's signing subkeys.
-
-* `pub` (public key)
-
-   This is the complement of the master secret key.
-   It can be uploaded to keyservers (or otherwise publicly distributed) and may be signed by others.
-
-* `vault`
-
-   This is a network-isolated VM.
-   The initial master keypair and subkeys are generated in this VM.
-   The master secret key *never* leaves this VM under *any* circumstances.
-   No files or text is *ever* [copied](/doc/how-to-copy-and-move-files/#security) or [pasted](/doc/how-to-copy-and-paste-text/#security) into this VM under *any* circumstances.
-
-* `work-gpg`
-
-   This is a network-isolated VM.
-   This VM is used *only* as the GPG backend for `work-email`.
-   The secret subkeys (but *not* the master secret key) are [copied](/doc/how-to-copy-and-move-files/#security) from the `vault` VM to this VM.
-   Files from less trusted VMs are *never* [copied](/doc/how-to-copy-and-move-files/#security) into this VM under *any* circumstances.
-
-* `work-email`
-
-   This VM has access to the mail server.
-   It accesses the `work-gpg` VM via the Split GPG protocol.
-   The public key may be stored in this VM so that it can be attached to emails and for other such purposes.
-
-### Security Benefits
-
-In the standard Split GPG setup, there are at least two ways in which the `work-gpg` VM might be compromised.
-First, an attacker who is capable of exploiting a hypothetical bug in `work-email`'s [MUA](https://en.wikipedia.org/wiki/Mail_user_agent) could gain control of the `work-email` VM and send a malformed request which exploits a hypothetical bug in the GPG backend (running in the `work-gpg` VM), giving the attacker control of the `work-gpg` VM.
-Second, a malicious public key file which is imported into the `work-gpg` VM might exploit a hypothetical bug in the GPG backend which is running there, again giving the attacker control of the `work-gpg` VM.
-In either case, such an attacker might then be able to leak both the master secret key and its passphrase (if any is used, it would regularly be input in the work-gpg VM and therefore easily obtained by an attacker who controls this VM) back to the `work-email` VM or to another VM (e.g., the `netvm`, which is always untrusted by default) via the Split GPG protocol or other [covert channels](/doc/data-leaks/).
-Once the master secret key is in the `work-email` VM, the attacker could simply email it to himself (or to the world).
-
-In the alternative setup described in this section (i.e., the subkey setup), even an attacker who manages to gain access to the `work-gpg` VM will not be able to obtain the user's master secret key since it is simply not there.
-Rather, the master secret key remains in the `vault` VM, which is extremely unlikely to be compromised, since nothing is ever copied or transferred into it.
-[^a-note] The attacker might nonetheless be able to leak the secret subkeys from the `work-gpg` VM in the manner described above, but even if this is successful, the secure master secret key can simply be used to revoke the compromised subkeys and to issue new subkeys in their place.
-(This is significantly less devastating than having to create a new *master* keypair.)
-
-[^a-note]: In order to gain access to the `vault` VM, the attacker would require the use of, e.g., a general Xen VM escape exploit or a [signed, compromised package which is already installed in the template](/doc/templates/#trusting-your-templates) upon which the `vault` VM is based.
-
-### Subkey Tutorials and Discussions
-
-(Note: Although the tutorials below were not written with Qubes Split GPG in mind, they can be adapted with a few commonsense adjustments.
-As always, exercise caution and use your good judgment.)
-
-* ["OpenPGP in Qubes OS" on the qubes-users mailing list](https://groups.google.com/d/topic/qubes-users/Kwfuern-R2U/discussion)
-* ["Creating the Perfect GPG Keypair" by Alex Cabal](https://alexcabal.com/creating-the-perfect-gpg-keypair/)
-* ["GPG Offline Master Key w/ smartcard" maintained by Abel Luck](https://gist.github.com/abeluck/3383449)
-* ["Using GnuPG with QubesOS" by Alex](https://apapadop.wordpress.com/2013/08/21/using-gnupg-with-qubesos/)
-
-## Current limitations
-
-* It doesn't solve the problem of allowing the user to know what is to be signed before the operation gets approved.
-  Perhaps the GPG backend domain could start a disposable and have the to-be-signed document displayed there? To Be Determined.
-
-* The Split GPG client will fail to sign or encrypt if the private key in the GnuPG backend is protected by a passphrase.
-  It will give an `Inappropriate ioctl for device` error.
-  Do not set passphrases for the private keys in the GPG backend domain.
-  Doing so won't provide any extra security anyway, as explained in the introduction and in [using Split GPG with subkeys](#advanced-using-split-gpg-with-subkeys).
-  If you are generating a new key pair, or if you have a private key that already has a passphrase, you can use `gpg2 --edit-key <key_id>` then `passwd` to set an empty passphrase.
-  Note that `pinentry` might show an error when you try to set an empty passphrase, but it will still make the change.
-  (See [this StackExchange answer](https://unix.stackexchange.com/a/379373) for more information.)
-  Note: The error shows only if you **do not** have graphical pinentry installed.
+You should have received a copy of the GNU General Public License along
+with this program; if not, write to the Free Software Foundation, Inc.,
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
\ No newline at end of file

From ec1f501c538d5775edb0d082581d58cc19f08d3b Mon Sep 17 00:00:00 2001
From: apparatius <151992958+apparatius@users.noreply.github.com>
Date: Fri, 12 Jul 2024 09:31:11 +0000
Subject: [PATCH 33/87] Update firewall.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The disappearance of the eth0 interface when you restart the net qube of the sys-firewall or set it’s net qube to none is causing `iif == "eth0"` to become `iif 2` and the rules won't work anymore.
It’s better to use `iifgroup 1` instead of `iif == "eth0"`.
Related discussion:
https://forum.qubes-os.org/t/iptables-not-available-in-sys-net-in-qubes-os-4-2-1/26706/26
---
 user/security-in-qubes/firewall.md | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/user/security-in-qubes/firewall.md b/user/security-in-qubes/firewall.md
index 95b28673..0fc9a2f8 100644
--- a/user/security-in-qubes/firewall.md
+++ b/user/security-in-qubes/firewall.md
@@ -297,13 +297,13 @@ nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority fi
 Second step, code a natting firewall rule to route traffic on the outside interface for the service to the sys-firewall VM
 
 ```
-nft add rule qubes custom-dnat-qubeDEST iif == "ens6" ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z
+nft add rule qubes custom-dnat-qubeDEST iifgroup 1 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z
 ```
 
 Third step, code the appropriate new filtering firewall rule to allow new connections for the service
 
 ```
-nft add rule qubes custom-forward iif == "ens6" ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept
+nft add rule qubes custom-forward iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept
 ```
 
 > Note: If you do not wish to limit the IP addresses connecting to the service, remove `ip saddr 192.168.x.y/24` from the rules
@@ -320,12 +320,12 @@ In this example, we can see 7 packets in the forward rule, and 3 packets in the
 
 ```
 chain custom-forward {
-  iif "ens6" ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter packets 7 bytes 448 accept
+  iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter packets 7 bytes 448 accept
 }
 
 chain custom-dnat-qubeDEST {
   type nat hook prerouting priority filter + 1; policy accept;
-  iif "ens6" ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter packets 3 bytes 192 dnat to 10.138.33.59
+  iifgroup 1 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter packets 3 bytes 192 dnat to 10.138.33.59
 }
 ```
 
@@ -351,10 +351,10 @@ Content of `/rw/config/qubes-firewall-user-script` in `sys-net`:
 if nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
 then
   # create the dnat rule
-  nft add rule qubes custom-dnat-qubeDEST iif == "ens6" saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z
+  nft add rule qubes custom-dnat-qubeDEST iifgroup 1 saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z
 
   # allow forwarded traffic
-  nft add rule qubes custom-forward iif == "ens6" ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept
+  nft add rule qubes custom-forward iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept
 fi
 ~~~
 
@@ -371,13 +371,13 @@ nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority fi
 Second step, code a natting firewall rule to route traffic on the outside interface for the service to the destination qube
 
 ```
-nft add rule qubes custom-dnat-qubeDEST iif == "eth0" ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.0.xx
+nft add rule qubes custom-dnat-qubeDEST iifgroup 1 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.0.xx
 ```
 
 Third step, code the appropriate new filtering firewall rule to allow new connections for the service
 
 ```
-nft add rule qubes custom-forward iif == "eth0" ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept
+nft add rule qubes custom-forward iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept
 ```
 
 > Note: If you do not wish to limit the IP addresses connecting to the service, remove `ip saddr 192.168.x.y/24` from the rules
@@ -398,10 +398,10 @@ Content of `/rw/config/qubes-firewall-user-script` in `sys-firewall`:
 if nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
 then
   # create the dnat rule
-  nft add rule qubes custom-dnat-qubeDEST iif == "eth0" tcp dport 443 ct state new,established,related counter dnat 10.137.0.xx
+  nft add rule qubes custom-dnat-qubeDEST iifgroup 1 tcp dport 443 ct state new,established,related counter dnat 10.137.0.xx
 
   # allow forwarded traffic
-  nft add rule qubes custom-forward iif == "eth0" ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept
+  nft add rule qubes custom-forward iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept
 fi
 ~~~
 

From 02508977273fa716ea8b0b55337a0aebd255c302 Mon Sep 17 00:00:00 2001
From: Demi Marie Obenour <demi@invisiblethingslab.com>
Date: Sun, 21 Jul 2024 15:01:31 -0400
Subject: [PATCH 34/87] Document how to update system firmware

This is a very important task, but it is often not done due to bad
tools.  Also correct some outdated information on the "how to update
software" page.
---
 user/how-to-guides/how-to-update.md | 69 +++++++++++++++++++++++++++--
 user/reference/glossary.md          |  7 +++
 2 files changed, 73 insertions(+), 3 deletions(-)

diff --git a/user/how-to-guides/how-to-update.md b/user/how-to-guides/how-to-update.md
index 2462bafb..f21cc385 100644
--- a/user/how-to-guides/how-to-update.md
+++ b/user/how-to-guides/how-to-update.md
@@ -17,6 +17,7 @@ Fully updating your Qubes OS system means updating:
 - [dom0](/doc/glossary/#dom0)
 - [templates](/doc/glossary/#template)
 - [standalones](/doc/glossary/#standalone) (if you have any)
+- [firmware](/doc/glossary/#firmware)
 
 ## Security updates
 
@@ -63,15 +64,19 @@ If you use [Anti Evil Maid (AEM)](/doc/anti-evil-maid/), you'll have to "reseal"
 
 <div class="alert alert-danger" role="alert">
   <i class="fa fa-exclamation-triangle"></i>
-  <b>Warning:</b> Updating with direct commands such as <code>qubes-dom0-update</code>, <code>dnf update</code>, and <code>apt update</code> is <b>not</b> recommended, since these bypass built-in Qubes OS update security measures. Instead, we strongly recommend using the <b>Qubes Update</b> tool or its command-line equivalents, as described below. (By contrast, <a href="/doc/how-to-install-software/">installing</a> packages using direct package manager commands is fine.)
+  <b>Warning:</b> Updating with direct commands such as <code>dnf update</code> and <code>apt update</code> is <b>not</b> recommended, since these bypass built-in Qubes OS update security measures. Instead, we strongly recommend using the <b>Qubes Update</b> tool or its command-line equivalents, as described below. (By contrast, <a href="/doc/how-to-install-software/">installing</a> packages using direct package manager commands is fine.)
 </div>
 
-Advanced users may wish to perform updates via the command-line interface. The recommended way to do this is by applying the following two Salt states. **Applying these two Salt states is the same as updating via the Qubes Update tool.**
+Advanced users may wish to perform updates via the command-line interface. There are two ways to do this:
+
+- If you are using Salt, one can use the following two Salt states.
 
  - [update.qubes-dom0](/doc/salt/#updatequbes-dom0)
  - [update.qubes-vm](/doc/salt/#updatequbes-vm)
 
-In your update qube, a terminal window opens that displays the progress of operations and output as it is logged. At the end of the process, logs are sent back to dom0. You answer any yes/no prompts in your dom0 terminal window.
+- Alternatively, use `qubes-dom0-update` to update dom0, and use `qubes-vm-update` to update domUs.
+
+Using either of these methods has the same effect as updating via the Qubes Update tool.
 
 Advanced users may also be interested in learning [how to enable the testing repos](/doc/testing/).
 
@@ -86,3 +91,61 @@ In the case of Qubes OS itself, we will make an [announcement](/news/categories/
 Periodic upgrades are also important for templates. For example, you might be using a [Fedora template](/doc/templates/fedora/). The [Fedora Project](https://getfedora.org/) is independent of the Qubes OS Project. They set their own [schedule](https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle#Maintenance_Schedule) for when each Fedora release reaches EOL. You can always find out when an OS reaches EOL from the upstream project that maintains it. We also pass along any EOL notices we receive for official template OSes as a convenience to Qubes users (see the [supported template releases](/doc/supported-releases/#templates)).
 
 The one exception to all this is the specific release used for dom0 (not to be confused with Qubes OS as a whole), which [doesn't have to be upgraded](/doc/supported-releases/#note-on-dom0-and-eol).
+
+## Microcode Updates
+
+x86\_64 CPUs contain special low-level software called **microcode**, which
+is used to implement certain instructions and runs on various processors that
+are outside of Qubes OS's control.  Most microcode is in an on-CPU ROM, but
+CPU vendors provide patches that modify small parts of this microcode.  These
+patches can be loaded from the BIOS or by the OS.
+
+The fixes for some QSBs require a microcode update to work. Furthermore,
+microcode updates will sometimes fix vulnerabilities "silently". This means
+that the vulnerability impacts the security of Qubes OS, but the Qubes OS
+Security Team is not informed that a vulnerability exists, so no QSB is ever
+issued. Therefore, it is critical to update microcode.
+
+Intel provides microcode updates for all of their CPUs in a public Git
+repository, and allows OS vendors (such as Qubes OS) to distribute the updates
+free of charge.  AMD, however, only provides microcode for server CPUs.
+AMD client CPUs can only receive microcode updates via a system firmware
+update.  Worse, there is often a significant delay between when a vulnerability
+becomes public and when firmware that includes updated microcode is available
+to Qubes OS users.  This is why Qubes OS recommends Intel CPUs instead of
+AMD CPUs.
+
+## Firmware updates
+
+Modern computers have many processors other than those that run Qubes OS.
+Furthermore, the main processor cores also run firmware, which is used to
+boot the system and often provides some services at runtime.  Both kinds
+of firmware can have bugs and vulnerabilities, so it is critical to keep
+them updated.
+
+Some firmware is loaded by the OS at runtime.
+Such firmware is provided by the `linux-firmware` package and can be updated the usual way.
+Other devices have persistent firmware that must be updated manually.
+
+Qubes OS supports updating system firmware in three different ways.
+Which one to use depends on the device whose firmware is being updated.
+
+- If a device is attached to a domU, it should be updated using **fwupd**.
+  fwupd is included in both Debian and Fedora repositories.
+  It requires Internet access to use, but you can use the updates proxy if you
+  need to update firmware from an offline VM.  You can use either the
+  command-line `fwupdmgr` tool or any of the graphical interfaces to fwupd.
+
+- If a device is attached to dom0, use the `qubes-fwupdmgr` command-line tool.
+  This tool uses fwupd internally, but it fetches firmware and metadata over
+  qrexec from the dom0 UpdateVM, rather than fetching them from the Internet.
+  Unfortunately, their is no graphical interface for this tool yet.
+
+- System76 systems use a special update tool which is simpler than fwupd.
+  Support for this tool is currently in progress.  Once it is finished,
+  users will be able to use the **system76-firmware-cli** command-line
+  tool to update the firmware.
+
+Firmware updates are important on all systems, but they are especially
+important on AMD client systems.  These doesn't support loading microcode from
+the OS, so firmware updates are the **only** way to obtain microcode updates.
diff --git a/user/reference/glossary.md b/user/reference/glossary.md
index 98649dd4..df3009b6 100644
--- a/user/reference/glossary.md
+++ b/user/reference/glossary.md
@@ -88,6 +88,13 @@ domUs lack direct hardware access.
 * Sometimes the term [VM](#vm) is used as a synonym for domU. This is
   technically inaccurate, as [dom0](#dom0) is also a VM in Xen.
 
+## firmware
+
+Software that runs outside the control of the operating system.
+Some firmware executes on the same CPU cores as Qubes OS does, but
+all computers have many additional processors that the operating system
+does not run on, and these computers also run firmware.
+
 ## HVM
 
 Hardware-assisted Virtual Machine. Any fully virtualized, or hardware-assisted,

From 9218f2316760612376313fc7a126b13ded1e6fc4 Mon Sep 17 00:00:00 2001
From: "Dr. Gerhard Weck" <GerhardWeck@online.de>
Date: Sun, 25 Aug 2024 10:12:11 +0200
Subject: [PATCH 35/87] Describe Move user profiles without QWT installation

---
 user/templates/windows/windows-qubes-4-1.md | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/user/templates/windows/windows-qubes-4-1.md b/user/templates/windows/windows-qubes-4-1.md
index 4d38a4bb..62210c0a 100644
--- a/user/templates/windows/windows-qubes-4-1.md
+++ b/user/templates/windows/windows-qubes-4-1.md
@@ -231,7 +231,16 @@ For additional information on configuring a Windows qube, see the [Customizing W
 
 ## Windows as a template
 
-As described above Windows 7, 8.1, 10 and 11 can be installed as TemplateVM. To have the user data stored in AppVMs depending on this template, the option `Move User Profiles` has to be selected on installation of Qubes Windows Tools. For Windows 7, before installing QWT, the private disk `D:` has to be renamed to `Q:`, see the QWT installation documentation in [Qubes Windows Tools](/doc/templates/windows/qubes-windows-tools-4-1).
+As described above Windows 7, 8.1, 10, and 11 can be installed as TemplateVM. To have the user data stored in AppVMs depending on this template, the user data have to be stored on a private disk named `Q:`. If there is already a disk for user data, possibly called `D:`, it has to be renamed to `Q:`. Otherwise, this disk has to be created via the Windows `diskpart` utility, or the Disk Management administrative function by formatting the qube's private volume and associating the letter `Q:` with it. The volume name is of no importance.
+
+Moving the user data is not directly possible under Windows, because the directory `C:\Users` is permanently open and thus locked. Qubes Windows Tools provides a function to move these data on Windows reboot when the directory is not yet locked. To use this function, a working version of QWT has to be used (see the documentation on QWT installation). For Qubes R4.2, this is currently the version 4.1.69. There are two possibilities to move the user data to this volume `Q:`.
+
+- If Qubes Windows Tools is installed, the option `Move User Profiles` has to be selected on the installation. In this case, the user files are moved to the new disk during the reboot at the end of the installation.
+
+- This can also be accomplished without QWT installation, avoiding the installation of the Xen PV drivers, if the risk of a compromised version of these drivers according to QSB-091 is considered too severe. In this case, the file `relocate_dir.exe` has to be extracted from the QWT installer kit `qubes-tools-x64.msi`, which will be shown as the content of the CDROM made available by starting the Windows qube with the additional option `--install-windows-tools` (see the QWT installation documentation). The installer kit is a specially formatted archive, from which the file `relocate_dir.exe` can be extracted using a utility like 7-Zip. The file has then to be copied to `%windir%\system32`, i.e. usually `C:\Windows\system32`. Furthermore, locate the registry key `HKLM\SYSTEM\CurrentControlSet\Control\Session Manager`, and add the text `relocate_dir.exe C:\Users Q:\Users` as a new line to the REG_MULTI_SZ-value `\BootExecute` in this key. On rebooting the Windows qube, the user files will be moved to the disk `Q:`, and the additional registry entry will be removed, such that this action occurs only once.
+
+If the user data have been moved to `Q:`, be sure not to user the option `Move User Profeiles`on subsequent installations of Qubes Windows tools.
+
 
 AppVMs based on these templates can be created the normal way by using the Qube Manager or by specifying
 ~~~

From 63bf921aa6179d0d96215a8a252daaaa3ef5d3ca Mon Sep 17 00:00:00 2001
From: "Dr. Gerhard Weck" <GerhardWeck@online.de>
Date: Sat, 21 Sep 2024 13:27:20 +0200
Subject: [PATCH 36/87] Formal change

---
 user/templates/windows/windows-qubes-4-1.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/user/templates/windows/windows-qubes-4-1.md b/user/templates/windows/windows-qubes-4-1.md
index 62210c0a..84bf67ff 100644
--- a/user/templates/windows/windows-qubes-4-1.md
+++ b/user/templates/windows/windows-qubes-4-1.md
@@ -237,7 +237,7 @@ Moving the user data is not directly possible under Windows, because the directo
 
 - If Qubes Windows Tools is installed, the option `Move User Profiles` has to be selected on the installation. In this case, the user files are moved to the new disk during the reboot at the end of the installation.
 
-- This can also be accomplished without QWT installation, avoiding the installation of the Xen PV drivers, if the risk of a compromised version of these drivers according to QSB-091 is considered too severe. In this case, the file `relocate_dir.exe` has to be extracted from the QWT installer kit `qubes-tools-x64.msi`, which will be shown as the content of the CDROM made available by starting the Windows qube with the additional option `--install-windows-tools` (see the QWT installation documentation). The installer kit is a specially formatted archive, from which the file `relocate_dir.exe` can be extracted using a utility like 7-Zip. The file has then to be copied to `%windir%\system32`, i.e. usually `C:\Windows\system32`. Furthermore, locate the registry key `HKLM\SYSTEM\CurrentControlSet\Control\Session Manager`, and add the text `relocate_dir.exe C:\Users Q:\Users` as a new line to the REG_MULTI_SZ-value `\BootExecute` in this key. On rebooting the Windows qube, the user files will be moved to the disk `Q:`, and the additional registry entry will be removed, such that this action occurs only once.
+- This can also be accomplished without QWT installation, avoiding the installation of the Xen PV drivers, if the risk of a compromised version of these drivers according to QSB-091 is considered too severe. In this case, the file `relocate_dir.exe` has to be extracted from the QWT installer kit `qubes-tools-x64.msi`, which will be shown as the content of the CDROM made available by starting the Windows qube with the additional option `--install-windows-tools` (see the QWT installation documentation). The installer kit is a specially formatted archive, from which the file `relocate_dir.exe` can be extracted using a utility like 7-Zip. The file has then to be copied to `%windir%\system32`, i.e. usually `C:\Windows\system32`. Furthermore, locate the registry key `HKLM\SYSTEM\CurrentControlSet\Control\Session Manager`, and add the text `relocate_dir.exe C:\Users Q:\Users` as a new line to the `REG_MULTI_SZ` value `\BootExecute` in this key. On rebooting the Windows qube, the user files will be moved to the disk `Q:`, and the additional registry entry will be removed, such that this action occurs only once.
 
 If the user data have been moved to `Q:`, be sure not to user the option `Move User Profeiles`on subsequent installations of Qubes Windows tools.
 

From 8ae7c2495886fa33c0b7fa63c5329bbc7fb796c2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?=
 <marmarek@invisiblethingslab.com>
Date: Sun, 20 Oct 2024 00:41:01 +0200
Subject: [PATCH 37/87] Update docs about /rw/config/rc.local* scripts

Specify that files needs to be executable.
Add info about `/rw/config/rc.local.d/*.rc`.
Add info about `/rw/config/rc.local-early.d/*.rc` and
`/rw/config/rc.local-early`
(https://github.com/QubesOS/qubes-core-agent-linux/pull/386)
---
 user/advanced-topics/config-files.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/user/advanced-topics/config-files.md b/user/advanced-topics/config-files.md
index 3ffdfd55..db8a7f07 100644
--- a/user/advanced-topics/config-files.md
+++ b/user/advanced-topics/config-files.md
@@ -19,7 +19,7 @@ That way, they can be used to customize a single VM instead of all VMs based on
 The scripts here all run as root.
 
 - `/rw/config/rc.local` - script runs at VM startup.
-    Good place to change some service settings, replace config files with its copy stored in `/rw/config`, etc.
+    Good place to change some service settings, replace config files with its copy stored in `/rw/config`, etc. The script need to have the executable permission set to be executed.
     Example usage:
 
     ~~~
@@ -33,6 +33,8 @@ The scripts here all run as root.
     echo '127.0.0.1 example.com' >> /etc/hosts
     ~~~
 
+- `/rw/config/rc.local.d/*.rc` - scripts run at VM startup just before `/rw/config/rc.local`
+- `/rw/config/rc.local-early.d/*.rc`, `/rw/config/rc.local-early` - scripts similar to `/rw/config/rc.local`, but running earlier in the system startup sequence - just before `sysinit.target`, and setting up the network.
 - `/rw/config/qubes-ip-change-hook` - script runs in NetVM after every external IP change and on "hardware" link status change.
 
 - In ProxyVMs (or app qubes with `qubes-firewall` service enabled), scripts placed in the following directories will be executed in the listed order followed by `qubes-firewall-user-script` at start up.

From d1cb9bd2fb45c76fcd59a3b538b0f2c6497442b3 Mon Sep 17 00:00:00 2001
From: Rowen S <ro@freedom.press>
Date: Mon, 25 Nov 2024 13:56:59 -0500
Subject: [PATCH 38/87] Add documentation on qubes-fwupdmgr usage

---
 user/how-to-guides/how-to-update.md | 54 +++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/user/how-to-guides/how-to-update.md b/user/how-to-guides/how-to-update.md
index 2462bafb..e736e750 100644
--- a/user/how-to-guides/how-to-update.md
+++ b/user/how-to-guides/how-to-update.md
@@ -17,6 +17,7 @@ Fully updating your Qubes OS system means updating:
 - [dom0](/doc/glossary/#dom0)
 - [templates](/doc/glossary/#template)
 - [standalones](/doc/glossary/#standalone) (if you have any)
+- your computer's [firmware](https://en.wikipedia.org/wiki/Firmware)
 
 ## Security updates
 
@@ -86,3 +87,56 @@ In the case of Qubes OS itself, we will make an [announcement](/news/categories/
 Periodic upgrades are also important for templates. For example, you might be using a [Fedora template](/doc/templates/fedora/). The [Fedora Project](https://getfedora.org/) is independent of the Qubes OS Project. They set their own [schedule](https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle#Maintenance_Schedule) for when each Fedora release reaches EOL. You can always find out when an OS reaches EOL from the upstream project that maintains it. We also pass along any EOL notices we receive for official template OSes as a convenience to Qubes users (see the [supported template releases](/doc/supported-releases/#templates)).
 
 The one exception to all this is the specific release used for dom0 (not to be confused with Qubes OS as a whole), which [doesn't have to be upgraded](/doc/supported-releases/#note-on-dom0-and-eol).
+
+## Firmware updates
+
+As of Qubes 4.2, firmware updates can be performed from within Qubes for [fwupd-supported computers](https://fwupd.org/).
+
+### In dom0
+
+First, ensure that your [UpdateVM](/doc/Software/UpdateVM/)
+contains the `fwupd-qubes-vm` package. This package is installed
+by default for qubes with `qubes-vm-recommended` packages.
+
+In a dom0 terminal, install the `fwupd-qubes-dom0` package:
+
+  ```
+  $ sudo qubes-dom0-update fwupd-qubes-dom0
+  ```
+
+Once the package is installed:
+
+   ```
+   $ sudo qubes-fwupdmgr get-devices
+   ```
+
+Examine the terminal output for warnings or errors.
+You may see the following warning:
+
+   ```
+   WARNING: UEFI capsule updates not available or enabled
+   ```
+If so, [adjust your BIOS settings](https://github.com/fwupd/fwupd/wiki/PluginFlag:capsules-unsupported) to enable UEFI updates. This setting is sometimes named "Windows UEFI Firmware Update."
+
+Once resolved, in a dom0 terminal:
+
+  ```
+  $ sudo qubes-fwupdmgr get-devices
+  $ sudo qubes-fwupdmgr refresh
+  $ sudo qubes-fwupdmgr update
+  ```
+
+A numbered list of devices with available updates will be presented. Ensure your computer is plugged in to a stable power source, then type the list number of the device you wish to update. If a reboot is required, you will be prompted at the console to confirm.
+
+Repeat the update process for any additional devices on your computer.
+
+### In other qubes
+
+Devices that are attached to non-dom0 qubes can be updated via a graphical tool for `fwupd`, or via the `fwupdmgr` commandline tool.
+
+To update the firmware of offline qubes, use the [Updates
+proxy](/doc/how-to/install/software/#updates-proxy).
+
+### Computers without fwupd support
+
+For computers that do not have firmware update support via `fwupd`, follow the firmware update instructions on the manufacturer's website. Verify the authenticity of any firmware updates you apply.

From 7c7911177f2709dce43ce937949ad9895e302c3e Mon Sep 17 00:00:00 2001
From: b90g <63392812+b90g@users.noreply.github.com>
Date: Fri, 29 Nov 2024 20:21:29 +0100
Subject: [PATCH 39/87] Update windows-qubes-4-1.md

evading microsoft account enforcement.
---
 user/templates/windows/windows-qubes-4-1.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/user/templates/windows/windows-qubes-4-1.md b/user/templates/windows/windows-qubes-4-1.md
index 4d38a4bb..a89fd2ae 100644
--- a/user/templates/windows/windows-qubes-4-1.md
+++ b/user/templates/windows/windows-qubes-4-1.md
@@ -172,7 +172,15 @@ These parameters are set for the following reasons:
     - Click `Next`. A screen appears saying "Who's going to use this device?" This is the local account creation screen.
     - Enter the username you want to use and click `Next`.
     - Enter a password and click `Next`. You can leave the field blank but it's not recommended.
+   
+    For Windows 11 version 24H2, the following sequence of actions to use a local account instead of a Microsoft account has been proved working:
 
+    - Boot with a disconnected machine.
+    - When you reach the “Let’s Connect You To A Network” page, type Shift-F10 to open a console window.
+    - Enter `oobe\bypassnro` and hit enter.
+    - The machine will restart and then lets you setup a local account.
+    - Machine then can go online again if desired.
+   
 - On systems shipped with a Windows license, the product key may be read from flash via root in dom0:
 
     `strings < /sys/firmware/acpi/tables/MSDM`

From ae26177e4d01d180a959b99ec02d94fc7e265747 Mon Sep 17 00:00:00 2001
From: Christian Tramnitz <ctr49@users.noreply.github.com>
Date: Sun, 1 Dec 2024 12:39:23 +0100
Subject: [PATCH 40/87] add known issues to gui-domain docs

Although sys-gui (and its variants sys-gui-gpu and sys-gui-vnc) are clearly marked to be used by advanced users only, there are some limitations that may go beyond the expectations of an advanced user.

This updates the documentation to contain some known issues that probably don't have a quick fix.
---
 user/advanced-topics/gui-domain.md | 28 ++++++++++++++++++++++------
 1 file changed, 22 insertions(+), 6 deletions(-)

diff --git a/user/advanced-topics/gui-domain.md b/user/advanced-topics/gui-domain.md
index c9aa6f58..6c18d51f 100644
--- a/user/advanced-topics/gui-domain.md
+++ b/user/advanced-topics/gui-domain.md
@@ -120,13 +120,33 @@ A VNC server session is running on `localhost:5900` in `sys-gui-vnc`. In order t
 > **WARNING**: This setup raises multiple security issues: 1) Anyone who can reach the `VNC` server, can take over the control of the Qubes OS machine, 2) A second client can connect even if a connection is already active and potentially get disconnected, 3) You can get disconnected by some unrelated network issues. Generally, if this `VNC` server is exposed to open network, it must be protected with some other (cryptographic) layer like `VPN`. The setup as is, is useful only for purely testing machine.
 
 
-### Troubleshooting
+### Known issues
 
 #### Application menu lacks qubes entries in a fresh GUI domain
 
 See [QubesOS/qubes-issues#5804](https://github.com/QubesOS/qubes-issues/issues/5804)
 
-#### Delete GUI domain
+#### Cannot update dom0 from sys-gui
+
+See [QubesOS/qubes-issues#8934](https://github.com/QubesOS/qubes-issues/issues/8934)
+
+#### GUI of HVM qubes not visible
+
+See [QubesOS/qubes-issues#9385](https://github.com/QubesOS/qubes-issues/issues/9385)
+
+### Power saving/screensaver issues
+
+See [QubesOS/qubes-issues#9033](https://github.com/QubesOS/qubes-issues/issues/9033), [QubesOS/qubes-issues#9384](https://github.com/QubesOS/qubes-issues/issues/9384), [QubesOS/qubes-issues#7989](https://github.com/QubesOS/qubes-issues/issues/7989)
+
+#### Qube startup order (sys-usb and sys-gui)
+
+See [QubesOS/qubes-issues#7954](https://github.com/QubesOS/qubes-issues/issues/7954)
+
+#### Other GUI domain issues
+
+see existing issues `QubesOS/qubes-issues` under [C: gui-domain](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+gui-domain%22) label.
+
+### Reverting sys-gui
 
 The following commands have to be run in `dom0`.
 
@@ -149,7 +169,3 @@ You are now able to delete the GUI domain, for example `sys-gui-gpu`:
 ```bash
 qvm-remove -f sys-gui-gpu
 ```
-
-#### General issues
-
-For any general GUI domain issues, please take a loot at existing issues `QubesOS/qubes-issues` under [C: gui-domain](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+gui-domain%22) label.

From 4cc913b6b0f54583ab632c86a9c7608f39d023af Mon Sep 17 00:00:00 2001
From: Darekisgit <dgrzelinski@mail.de>
Date: Wed, 4 Dec 2024 12:21:25 +0100
Subject: [PATCH 41/87] Update mfa.md

---
 user/security-in-qubes/mfa.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/user/security-in-qubes/mfa.md b/user/security-in-qubes/mfa.md
index 62a72e17..559f09a9 100644
--- a/user/security-in-qubes/mfa.md
+++ b/user/security-in-qubes/mfa.md
@@ -66,7 +66,7 @@ Now we are going to add the authenticator as a login requirement:
 
 1. `sudo authselect create-profile mfa --base-on sssd`
 
-2. Edit the custom system authentication template with `sudo nanois encouraged /etc/authselect/custom/mfa/system-auth`.
+2. Edit the custom system authentication template with `sudo nanois encouraged /etc/authselect/custom/mfa/system-auth`. there is an error in this line
 
    Add the following line right after `auth required pam_faildelay.so delay=2000000`:
 

From 1fca26ce44e4613fb9e15ec47fa724545dc737c7 Mon Sep 17 00:00:00 2001
From: ghijg <70027324+ghijg@users.noreply.github.com>
Date: Tue, 10 Dec 2024 00:13:35 +0100
Subject: [PATCH 42/87] Syntax changed due to dnf5/Fedora41

Syntax changed for enabling repositories with dnf5 which is used by default from Fedora 41 on.

https://dnf5.readthedocs.io/en/latest/changes_from_dnf4.7.html
---
 user/how-to-guides/how-to-install-software.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/user/how-to-guides/how-to-install-software.md b/user/how-to-guides/how-to-install-software.md
index da7aae0e..83c70701 100644
--- a/user/how-to-guides/how-to-install-software.md
+++ b/user/how-to-guides/how-to-install-software.md
@@ -227,10 +227,10 @@ depending on which RPM Fusion repositories you wish to enable (see [RPM
 Fusion](https://rpmfusion.org/) 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 config-manager setopt rpmfusion-free.enabled=1
+sudo dnf config-manager setopt rpmfusion-free-updates.enabled=1
+sudo dnf config-manager setopt rpmfusion-nonfree.enabled=1
+sudo dnf config-manager setopt rpmfusion-nonfree-updates.enabled=1
 sudo dnf upgrade --refresh
 ~~~
 

From cc001965399ce3ac66c9f854e6e776aa16ff6906 Mon Sep 17 00:00:00 2001
From: Rusty Bird <rustybird@net-c.com>
Date: Fri, 20 Dec 2024 19:29:36 +0000
Subject: [PATCH 43/87] luksFormat: add --sector-size=512 argument

---
 user/advanced-topics/secondary-storage.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/user/advanced-topics/secondary-storage.md b/user/advanced-topics/secondary-storage.md
index 24d97e2c..391e3059 100644
--- a/user/advanced-topics/secondary-storage.md
+++ b/user/advanced-topics/secondary-storage.md
@@ -65,10 +65,12 @@ In theory, you can still use file-based disk images ("file" pool driver), but it
 Assuming the secondary hard disk is at /dev/sdb (it will be completely erased), you can set it up for encryption by doing in a dom0 terminal (use the same passphrase as the main Qubes disk to avoid a second password prompt at boot):
 
 ```
-sudo cryptsetup luksFormat --hash=sha512 --key-size=512 --cipher=aes-xts-plain64 --verify-passphrase /dev/sdb
+sudo cryptsetup luksFormat --sector-size=512 --hash=sha512 --key-size=512 --cipher=aes-xts-plain64 --verify-passphrase /dev/sdb
 sudo blkid /dev/sdb
 ```
 
+(The `--sector-size=512` argument can sometimes work around an incompatibility of storage hardware with LVM thin pools on Qubes. If this does not apply to your hardware, the argument will make no difference.)
+
 Note the device's UUID (in this example "b209..."), we will use it as its luks name for auto-mounting at boot, by doing:
 
 ```

From 4fb0f0c851a44aeecd0778bca3c9babeebc79ec6 Mon Sep 17 00:00:00 2001
From: Rusty Bird <rustybird@net-c.com>
Date: Fri, 20 Dec 2024 19:29:37 +0000
Subject: [PATCH 44/87] luksFormat: drop arguments that are already the default

---
 user/advanced-topics/secondary-storage.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/user/advanced-topics/secondary-storage.md b/user/advanced-topics/secondary-storage.md
index 391e3059..3e2e8cf9 100644
--- a/user/advanced-topics/secondary-storage.md
+++ b/user/advanced-topics/secondary-storage.md
@@ -65,7 +65,7 @@ In theory, you can still use file-based disk images ("file" pool driver), but it
 Assuming the secondary hard disk is at /dev/sdb (it will be completely erased), you can set it up for encryption by doing in a dom0 terminal (use the same passphrase as the main Qubes disk to avoid a second password prompt at boot):
 
 ```
-sudo cryptsetup luksFormat --sector-size=512 --hash=sha512 --key-size=512 --cipher=aes-xts-plain64 --verify-passphrase /dev/sdb
+sudo cryptsetup luksFormat --sector-size=512 --hash=sha512 /dev/sdb
 sudo blkid /dev/sdb
 ```
 

From 65e0511d1521be509a5226296ce9912b39d2eac8 Mon Sep 17 00:00:00 2001
From: Rusty Bird <rustybird@net-c.com>
Date: Fri, 20 Dec 2024 19:29:38 +0000
Subject: [PATCH 45/87] luksFormat: drop --hash=sha512 argument

The default (sha256) seems fine for LUKS2 where the hash algorithm has a
limited role anyway - it's not used for key stretching like in LUKS1.
---
 user/advanced-topics/secondary-storage.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/user/advanced-topics/secondary-storage.md b/user/advanced-topics/secondary-storage.md
index 3e2e8cf9..d541c3c3 100644
--- a/user/advanced-topics/secondary-storage.md
+++ b/user/advanced-topics/secondary-storage.md
@@ -65,7 +65,7 @@ In theory, you can still use file-based disk images ("file" pool driver), but it
 Assuming the secondary hard disk is at /dev/sdb (it will be completely erased), you can set it up for encryption by doing in a dom0 terminal (use the same passphrase as the main Qubes disk to avoid a second password prompt at boot):
 
 ```
-sudo cryptsetup luksFormat --sector-size=512 --hash=sha512 /dev/sdb
+sudo cryptsetup luksFormat --sector-size=512 /dev/sdb
 sudo blkid /dev/sdb
 ```
 

From cc13bd9ee82c128c132663709c48824305accc0a Mon Sep 17 00:00:00 2001
From: Demi Marie Obenour <demi@invisiblethingslab.com>
Date: Thu, 3 Oct 2024 17:16:07 -0400
Subject: [PATCH 46/87] Provide evidence that AMD is slow to ship client
 microcode

The claims in the documentation are corrrect, but no sources were
provided.  Add links to sources.

Fixes: QubesOS/qubes-issues#9485
---
 user/hardware/system-requirements.md | 24 +++++++++++++++++++-----
 1 file changed, 19 insertions(+), 5 deletions(-)

diff --git a/user/hardware/system-requirements.md b/user/hardware/system-requirements.md
index ffe39f7c..bd279ed7 100644
--- a/user/hardware/system-requirements.md
+++ b/user/hardware/system-requirements.md
@@ -114,16 +114,16 @@ We recommend consulting these resources when selecting hardware for Qubes OS:
   other security updates directly to users. By contrast, on AMD client (as
   opposed to server) platforms, microcode updates are typically shipped only as
   part of system firmware and generally cannot be loaded from the operating
-  system. This means that AMD users typically must wait for:
-  
+  system [^1]. This means that AMD users typically must wait for:
+
   1. AMD to distribute microcode updates to original equipment manufacturers
   (OEMs), original design manufacturers (ODMs), and motherboard manufacturers
   (MB); and
   2. The user's OEM, ODM, or MB to provide a suitable BIOS or (U)EFI update for
   the user's system.
-  
+
   Historically, AMD has often been slow to complete step (1), at least for its
-  client (as opposed to server) platforms. In some cases, AMD has made fixes
+  client (as opposed to server) platforms [^2]. In some cases, AMD has made fixes
   available for its server platforms very shortly after a security embargo was
   lifted, but it did not make fixes available for client platforms facing the
   same vulnerability until weeks or months later. (A "security embargo" is the
@@ -134,7 +134,7 @@ We recommend consulting these resources when selecting hardware for Qubes OS:
 
   Step (2) varies by vendor. Many vendors fail to complete step (2) at all,
   while some others take a very long time to complete it.
-  
+
   The bottom line is that Qubes OS **can** run on AMD systems, and the Qubes and
   Xen security teams do their best to provide security support for AMD systems.
   However, without the ability to ship microcode updates, there is only so much
@@ -163,3 +163,17 @@ We recommend consulting these resources when selecting hardware for Qubes OS:
 
 - You can check whether an Intel processor has VT-x and VT-d on
   [ark.intel.com](https://ark.intel.com/content/www/us/en/ark.html#@Processors).
+
+[^1]: There is an `amd-ucode-firmware` package, but it only contains
+      microcode for servers and outdated microcode for Chromebooks.  Also,
+      the [AMD security website](https://www.amd.com/en/resources/product-security.html)
+      only lists microcode as a mitigation for data center CPUs.
+
+[^2]: As shown on [the AMD page for Speculative Return Stack Overflow](https://www.amd.com/en/resources/product-security/bulletin/amd-sb-7005.html),
+      updated AGESA™ firmware for AMD Ryzen™ Threadripper™ 5000WX Processors
+      was not available until 2024-01-11, even though the vulnerability became
+      public on 2023-08-08.  AMD did not provide updated firmware for other client
+      processors until a date between 2023-08-22 to 2023-08-25.
+
+      For Zenbleed, firmware was not available until 2024 for most client parts,
+      even though server parts got microcode on 2023-06-06.

From 06e37e444b7d2745caf7e6cbf5e5854c26c3e722 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marta=20Marczykowska-G=C3=B3recka?=
 <marmarta@invisiblethingslab.com>
Date: Tue, 2 Jul 2024 16:37:26 +0200
Subject: [PATCH 47/87] Add intro for Builder v2

---
 developer/building/development-workflow.md    |  53 +++---
 developer/building/qubes-builder-v2.md        | 160 ++++++++++++++++++
 developer/debugging/automated-tests.md        |   2 +-
 developer/debugging/test-bench.md             |   5 +-
 developer/general/gsoc.md                     |   4 +-
 introduction/faq.md                           |   2 +-
 .../testing.md                                |   2 +-
 user/templates/templates.md                   |   7 +-
 8 files changed, 192 insertions(+), 43 deletions(-)
 create mode 100644 developer/building/qubes-builder-v2.md

diff --git a/developer/building/development-workflow.md b/developer/building/development-workflow.md
index dd72699a..e4967756 100644
--- a/developer/building/development-workflow.md
+++ b/developer/building/development-workflow.md
@@ -12,14 +12,14 @@ title: Development workflow
 
 A workflow for developing Qubes OS+
 
-First things first, setup [QubesBuilder](/doc/qubes-builder/). This guide
-assumes you're using qubes-builder to build Qubes.
+First things first, setup [QubesBuilder](/doc/qubes-builder-v2/). This guide
+assumes you're using qubes-builder v2 to build Qubes.
 
 ## Repositories and committing Code
 
 Qubes is split into a bunch of git repos. These are all contained in the
-`qubes-src` directory under qubes-builder. Subdirectories there are separate
-components, stored in separate git repositories.
+`artifacts/sources` directory under qubes-builder. Subdirectories there are
+separate components, stored in separate git repositories.
 
 The best way to write and contribute code is to create a git repo somewhere
 (e.g., github) for the repo you are interested in editing (e.g.,
@@ -29,7 +29,7 @@ of Qubes, cd to the repo directory and add your repository as a remote in git
 **Example:**
 
 ~~~
-$ cd qubes-builder/qubes-src/qubes-manager
+$ cd qubes-builder/artifacts/sources/qubes-manager
 $ git remote add abel git@github.com:abeluck/qubes-manager.git
 ~~~
 
@@ -47,7 +47,7 @@ include your public PGP key you use to sign your tags.
 
 #### Prepare fresh version of kernel sources, with Qubes-specific patches applied
 
-In qubes-builder/qubes-src/linux-kernel:
+In qubes-builder/artifacts/sources/linux-kernel:
 
 ~~~
 make prep
@@ -66,7 +66,7 @@ drwxr-xr-x  6 user user 4096 Nov 21 20:48 kernel-3.4.18/linux-obj
 
 #### Go to the kernel tree and update the version
 
-In qubes-builder/qubes-src/linux-kernel:
+In qubes-builder/artifacts/sources/linux-kernel:
 
 ~~~
 cd kernel-3.4.18/linux-3.4.18
@@ -117,8 +117,6 @@ vi series.conf
 
 #### Building RPMs
 
-TODO: Is this step generic for all subsystems?
-
 Now it is a good moment to make sure you have changed kernel release name in
 rel file. For example, if you change it to '1debug201211116c' the
 resulting RPMs will be named
@@ -131,34 +129,23 @@ your changes locally.
 To actually build RPMs, in qubes-builder:
 
 ~~~
-make linux-kernel
+./qb -c linux-kernel package fetch prep build
 ~~~
 
-RPMs will appear in qubes-src/linux-kernel/pkgs/fc20/x86\_64:
+RPMs will appear in
+`artifacts/repository/destination_name/package_name`
+(for example `artifacts/repository/host-fc37/linux-kernel-6.6.31-1.1/`
 
-~~~
--rw-rw-r-- 1 user user 42996126 Nov 17 04:08 kernel-3.4.18-1debug20121116c.pvops.qubes.x86_64.rpm
--rw-rw-r-- 1 user user 43001450 Nov 17 05:36 kernel-3.4.18-1debug20121117a.pvops.qubes.x86_64.rpm
--rw-rw-r-- 1 user user  8940138 Nov 17 04:08 kernel-devel-3.4.18-1debug20121116c.pvops.qubes.x86_64.rpm
--rw-rw-r-- 1 user user  8937818 Nov 17 05:36 kernel-devel-3.4.18-1debug20121117a.pvops.qubes.x86_64.rpm
--rw-rw-r-- 1 user user 54490741 Nov 17 04:08 kernel-qubes-vm-3.4.18-1debug20121116c.pvops.qubes.x86_64.rpm
--rw-rw-r-- 1 user user 54502117 Nov 17 05:37 kernel-qubes-vm-3.4.18-1debug20121117a.pvops.qubes.x86_64.rpm
-~~~
+### Useful [QubesBuilder](/doc/qubes-builder-v2/) commands
 
-### Useful [QubesBuilder](/doc/qubes-builder/) commands
-
-1. `make check` - will check if all the code was committed into repository and
-if all repository are tagged with signed tag.
-2. `make show-vtags` - show version of each component (based on git tags) -
-mostly useful just before building ISO. **Note:** this will not show version
-for components containing changes since last version tag.
-3. `make push` - push change from **all** repositories to git server. You must
-set proper remotes (see above) for all repositories first.
-4. `make prepare-merge` - fetch changes from remote repositories (can be
-specified on commandline via GIT\_SUBDIR or GIT\_REMOTE vars), (optionally)
-verify tags and show the changes. This do not merge the changes - there are
-left for review as FETCH\_HEAD ref. You can merge them using `git merge
-FETCH_HEAD` (in each repo directory). Or `make do-merge` to merge all of them.
+1. `./qb package diff` - show uncommitted changes
+2. ` ./qb repository check-release-status-for-component` and
+`./qb repository check-release-status-for-template`- show version of each
+   component/template (based on git tags)
+3. `./qb package sign` -  sign built packages
+4. `./qb package publish` and `./qb package upload` - publish signed packages
+   and upload published
+   repository
 
 ## Copying Code to dom0
 
diff --git a/developer/building/qubes-builder-v2.md b/developer/building/qubes-builder-v2.md
new file mode 100644
index 00000000..79d85e21
--- /dev/null
+++ b/developer/building/qubes-builder-v2.md
@@ -0,0 +1,160 @@
+---
+lang: en
+layout: doc
+permalink: /doc/qubes-builder-v2/
+redirect_from:
+- /en/doc/qubes-builder-v2/
+- /doc/QubesBuilder2/
+- /wiki/QubesBuilder2/
+ref: 311
+title: Qubes builder v2
+---
+
+This is a brief introduction of using Qubes Builder v2 to work with Qubes OS
+sources. It will walk you through installing and configuring Builder v2 and
+using it to fetch and build Qubes OS packages.
+
+For details and customization, use [Qubes OS v2 builder documentation](https://github.com/QubesOS/qubes-builderv2/).
+
+# Overview
+
+In the second generation of Qubes OS builder, container or disposable qube
+isolation is used to perform every stage of the build and release process.
+From fetching sources to building, everything is executed inside an isolated
+*cage* (either a disposable or a container) using an *executor*. For every
+command that needs to perform an action on sources, like cloning and
+verifying Git repos, rendering a SPEC file, generating SRPM or Debian
+source packages, a new cage is used. Only the signing, publishing, and
+uploading stages are executed locally outside a cage.
+
+
+# Setup
+
+This is a simple setup for using a docker executor (a good default choice,
+if you don't know which executor to use, use docker).
+
+1. First, decide what qube are you going to use for working with Qubes
+   Builder v2. It can be an AppVM or a Standalone qube, with some steps
+   different between the two.
+
+2. Then, clone the qubes-builder v2 repository into a location of your
+   choice:
+    ```shell
+    git clone https://github.com/QubesOS/qubes-builderv2
+    cd qubes-builderv2/
+    ```
+
+3. Installing dependencies
+
+   Dependencies need to be installed for the qube you want to be developing
+   using Qubes Builder v2 - either in its template, or in the qube itself,
+   if it's a standalone.
+    Dependencies are specified in `dependencies-*.
+   txt` files in the main builder directory, and you can install them easily
+   in the following ways:
+   1. for Fedora, use:
+    ```shell
+    $ sudo dnf install $(cat dependencies-fedora.txt)
+    $ test -f /usr/share/qubes/marker-vm && sudo dnf install qubes-gpg-split
+   ```
+   2. for Debian (note: some Debian packages require Debian version 13 or
+      later), use:
+    ```shell
+    $ sudo apt install $(cat dependencies-debian.txt)
+    $ test -f /usr/share/qubes/marker-vm && sudo apt install qubes-gpg-split
+   ```
+
+4. If you haven't used docker in the current qube, you need also to set up
+   some permissions. In particular, the user has to be added to the `docker`
+   group:
+    ```shell
+   $ sudo usermod -aG docker user
+    ```
+    Next, **restart the qube**.
+
+5. Finally, you need to generate a docker image:
+    ```shell
+   $ tools/generate-container-image.sh docker
+    ```
+
+   In an AppVM, as `/var/lib/docker` is not persistent by default, you also
+   need to use bind-dirs to avoid repeating this step after reboot, adding
+   the following to the `/rw/config/qubes-bind-dirs.d/docker.conf` file in
+   this qube:
+
+   ```
+   binds+=( '/var/lib/docker' )
+   ```
+
+# Configuration
+
+To use Qubes OS Builder v2, you need to have a `builder.yml` configuration file.
+You can use one of the sample files from the `example-configs/` directory; for a
+more readable `builder.yml`, you can also include one of the files from that
+directory in your `builder.yml`. An example `builder.yml` is:
+
+```yaml
+# include configuration relevant for the current release
+include:
+- example-configs/qubes-os-r4.2.yml
+
+# which repository to use to fetch sources
+use-qubes-repo:
+  version: 4.2
+  testing: true
+
+# each package built will have local build number appended to package release
+# number. It makes it easier to update in testing environment
+increment-devel-versions: true
+
+# reduce output
+debug: false
+
+# this can be set to true if you do not want sources to be automatically
+# fetched from git
+skip-git-fetch: false
+
+# executor configuration
+executor:
+  type: docker
+  options:
+    image: "qubes-builder-fedora:latest"
+
+```
+
+
+# Using Builder v2
+
+To fetch sources - in this example, for the `core-admin-client` package, you
+can use the following command:
+
+```shell
+$ ./qb -c core-admin-client package fetch
+```
+
+This will fetch the sources for the listed package and place them in
+`artifacts/sources` directory.
+
+To build a package (from sources in the `artifacts/sources` directory), use:
+
+```shell
+$ ./qb -c core-admin-client package fetch prep build
+```
+
+or, if you want to build for a specific target (`host-fc37` is a `dom0`
+using Fedora 37, `vm-fc40` would be a qube using Fedora 40 etc.), use:
+
+```shell
+$ ./qb -c core-admin-client -d host-fc37 package fetch prep build
+```
+
+If you want to fetch entire Qubes OS sources (caution: some repositories might
+have additional requirements; you can disable repositories that are not
+needed in the `example-configs/*.yml` file you are using by commenting them
+out. In particular, `python-fido2`, `lvm` and `windows`-related repositories
+have
+special requirements), use the following:
+
+```shell
+$ ./qb package fetch
+```
diff --git a/developer/debugging/automated-tests.md b/developer/debugging/automated-tests.md
index 38e4aca2..1f72ede8 100644
--- a/developer/debugging/automated-tests.md
+++ b/developer/debugging/automated-tests.md
@@ -132,7 +132,7 @@ Whereas integration tests are mostly stored in the [qubes-core-admin](https://gi
 To for example run the `qubes-core-admin` unit tests, you currently have to clone at least [qubes-core-admin](https://github.com/QubesOS/qubes-core-admin) and
 its dependency [qubes-core-qrexec](https://github.com/QubesOS/qubes-core-qrexec) repository in the branches that you want to test.
 
-The below example however will assume that you set up a build environment as described in the [Qubes Builder documentation](/doc/qubes-builder/).
+The below example however will assume that you set up a build environment as described in the [Qubes Builder documentation](/doc/qubes-builder-v2/).
 
 Assuming you cloned the `qubes-builder` repository to your home directory inside a fedora VM, you can use the following commands to run the unit tests:
 
diff --git a/developer/debugging/test-bench.md b/developer/debugging/test-bench.md
index ca48a5ea..66a072c5 100644
--- a/developer/debugging/test-bench.md
+++ b/developer/debugging/test-bench.md
@@ -205,9 +205,10 @@ pushd ${HOME}/builder >/dev/null
 
 # the following are needed only if you have sources outside builder
 #rm -rf qubes-src/core-admin
-#make COMPONENTS=core-admin get-sources
+#qb -c core-admin package fetch
 
-make core-admin
+qb -c core-admin -d host-fc41 prep build
+# update your dom0 fedora distribution as appropriate
 qtb-install qubes-src/core-admin/rpm/x86_64/qubes-core-dom0-*.rpm
 qtb-runtests
 ```
diff --git a/developer/general/gsoc.md b/developer/general/gsoc.md
index e49d66d9..a2990cd9 100644
--- a/developer/general/gsoc.md
+++ b/developer/general/gsoc.md
@@ -31,7 +31,7 @@ You should start learning the components that you plan on working on before the
 
 Coming up with an interesting idea that you can realistically achieve in the time available to you (one summer) is probably the most difficult part. We strongly recommend getting involved in advance of the beginning of GSoC, and we will look favorably on applications from prospective contributors who have already started to act like free and open source developers.
 
-Before the summer starts, there are some preparatory tasks which are highly encouraged. First, if you aren't already, definitely start using Qubes as your primary OS as soon as possible! Also, it is encouraged that you become familiar and comfortable with the Qubes development workflow sooner than later. A good way to do this (and also a great way to stand out as an awesome applicant and make us want to accept you!) might be to pick up some issues from [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) (our issue-tracking repo) and submit some patches addressing them. Some suitable issues might be those with tags ["help wanted" and "P: minor"](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22P%3A%20minor%22%20label%3A%22help%20wanted%22) (although more significant things are also welcome, of course). Doing this will get you some practice with [qubes-builder](/doc/qubes-builder/), our code-signing policies, and some familiarity with our code base in general so you are ready to hit the ground running come summer.
+Before the summer starts, there are some preparatory tasks which are highly encouraged. First, if you aren't already, definitely start using Qubes as your primary OS as soon as possible! Also, it is encouraged that you become familiar and comfortable with the Qubes development workflow sooner than later. A good way to do this (and also a great way to stand out as an awesome applicant and make us want to accept you!) might be to pick up some issues from [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) (our issue-tracking repo) and submit some patches addressing them. Some suitable issues might be those with tags ["help wanted" and "P: minor"](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22P%3A%20minor%22%20label%3A%22help%20wanted%22) (although more significant things are also welcome, of course). Doing this will get you some practice with [qubes-builder](/doc/qubes-builder-v2/), our code-signing policies, and some familiarity with our code base in general so you are ready to hit the ground running come summer.
 
 ### Contributor proposal guidelines
 
@@ -422,7 +422,7 @@ for more information and qubes-specific background.
 
 **Difficulty**: medium
 
-**Knowledge prerequisite**: qubes-builder [[1]](/doc/qubes-builder/) [[2]](/doc/qubes-builder-details/) [[3]](https://github.com/QubesOS/qubes-builder/tree/master/doc), and efficient at introspecting complex systems: comfortable with tracing and debugging tools, ability to quickly identify and locate issues within a large codebase (upstream build tools), etc.
+**Knowledge prerequisite**: qubes-builder [[1]](/doc/qubes-builder-v2/) [[2]](https://github.com/QubesOS/qubes-builderv2), and efficient at introspecting complex systems: comfortable with tracing and debugging tools, ability to quickly identify and locate issues within a large codebase (upstream build tools), etc.
 
 **Size of the project**: 350 hours
 
diff --git a/introduction/faq.md b/introduction/faq.md
index 2258ee1b..f869f760 100644
--- a/introduction/faq.md
+++ b/introduction/faq.md
@@ -678,7 +678,7 @@ Any rpm-based, 64-bit environment, the preferred OS being Fedora.
 
 ### How do I build Qubes from sources?
 
-See [these instructions](/doc/qubes-builder/).
+See [these instructions](/doc/qubes-builder-v2/).
 
 ### How do I submit a patch?
 
diff --git a/user/downloading-installing-upgrading/testing.md b/user/downloading-installing-upgrading/testing.md
index d6e6339d..4353262f 100644
--- a/user/downloading-installing-upgrading/testing.md
+++ b/user/downloading-installing-upgrading/testing.md
@@ -17,7 +17,7 @@ How to test upcoming Qubes OS releases:
 
 - Test the latest release candidate (RC) on the [downloads](/downloads/) page, if one is currently available. (Or try an older RC from our [FTP server](https://ftp.qubes-os.org/iso/).)
 - Try the [signed weekly builds](https://qubes.notset.fr/iso/). ([Learn more](https://forum.qubes-os.org/t/16929) and [track their status](https://github.com/fepitre/updates-status-iso/issues).)
-- Use [qubes-builder](/doc/qubes-builder/) to build the latest release yourself.
+- Use [qubes-builder](/doc/qubes-builder-v2/) to build the latest release yourself.
 - (No support) Experiment with developer alpha ISOs found from time to time at [Qubes OpenQA](https://openqa.qubes-os.org/).
 
 Please make sure to [report any bugs you encounter](/doc/issue-tracking/).
diff --git a/user/templates/templates.md b/user/templates/templates.md
index 2f7ac64a..681a4951 100644
--- a/user/templates/templates.md
+++ b/user/templates/templates.md
@@ -429,8 +429,9 @@ this context: the same as their template filesystem, of course.
 
 * Some templates are available in ready-to-use binary form, but some of them
   are available only as source code, which can be built using the [Qubes
-  Builder](/doc/qubes-builder/). In particular, some template "flavors" are
-  available in source code form only. For the technical details of the template
+  Builder](https://github.com/QubesOS/qubes-builderv2/). In particular, some
+  template "flavors" are  available in source code form only. For the
+  technical details of the template
   system, please see [Template Implementation](/doc/template-implementation/).
-  Take a look at the [Qubes Builder](/doc/qubes-builder/) documentation for
+  Take a look at the [Qubes Builder](/doc/qubes-builder-v2/) documentation for
   instructions on how to compile them.

From f71614efd9a581b6cb8a242a30b4fee567ed05d2 Mon Sep 17 00:00:00 2001
From: 3np <3np@example.com>
Date: Sun, 23 Mar 2025 02:16:21 +0000
Subject: [PATCH 48/87] how-to-install-software: clarify updates-proxy usage

- makes it less likely to get the false impression that
  the updates proxy does not allow arbitrary outbound connections
- add example of how to download software in templates without
  enabling direct networking
---
 user/how-to-guides/how-to-install-software.md | 49 +++++++++++++------
 user/how-to-guides/how-to-update.md           |  2 +-
 user/templates/templates.md                   |  2 +-
 3 files changed, 37 insertions(+), 16 deletions(-)

diff --git a/user/how-to-guides/how-to-install-software.md b/user/how-to-guides/how-to-install-software.md
index be3ee664..094f526e 100644
--- a/user/how-to-guides/how-to-install-software.md
+++ b/user/how-to-guides/how-to-install-software.md
@@ -69,17 +69,38 @@ will appear in the Applications Menu. (If you encounter problems, see
 ## Installing software from other sources
 
 **Warning:** This method gives your template direct network access, which is
-[risky](#why-dont-templates-have-network-access). This method is **not**
+[risky](#why-dont-templates-have-normal-network-access). This method is **not**
 recommended for trusted templates. Moreover, depending on how you install this
 software, it may not get updated automatically when you [update Qubes
 normally](/doc/how-to-update/), which means you may have to update it manually
 yourself.
 
 Some software is not available from the default repositories and must be
-downloaded and installed from another source. This method assumes that you're
-trying to follow the instructions to install some piece of software in a normal
-operating system, except that operating system is running as a template in
-Qubes OS.
+downloaded and installed from another source. Depending on the installation method,
+you may either use the updates proxy or direct networking.
+
+### Using the updates proxy
+
+If you are still using the distribution package manager, updates will likely still
+work over the updates proxy without needing to give the TemplateVM direct network access.
+
+If you are using another installation method fetching remote resources, you might still
+be able to use the updates proxy by making the tools aware of the proxy. For many tools,
+it is enough to export the following environment variables in your shell session before
+proceeding:
+
+```sh
+$ export HTTP_PROXY=http://127.0.0.1:8082 http_proxy=$HTTP_PROXY \
+         HTTPS_PROXY=$HTTP_PROXY https_proxy=$HTTPS_PROXY \
+         ALL_PROXY=$HTTP_PROXY all_proxy=$ALL_PROXY \
+         NO_PROXY=127.0.0.1 no_proxy=$NO_PROXY
+```
+
+### Using direct networking
+
+This method assumes that you're trying to follow the instructions to install some piece
+of software in a normal operating system, except that operating system is running as a
+template in Qubes OS.
 
 1. (Recommended) Clone the desired template (since this new template will
    probably be less trusted than the original).
@@ -140,18 +161,18 @@ If things are still not working as expected:
 Please see [How to Update](/doc/how-to-update/).
 
 
-## Why don't templates have network access?
+## Why don't templates have normal network access?
 
 In order to protect you from performing risky activities in templates, they do
 not have normal network access by default. Instead, templates use an [updates
-proxy](#updates-proxy) that allows you to install and update software using
-the distribution package manager without giving the template direct network
-access.**The updates proxy is already setup to work automatically
-out-of-the-box and requires no special action from you.** Most users should
-simply follow the normal instructions for [installing software from default
-repositories](#installing-software-from-default-repositories) and
-[updating](/doc/how-to-update/) software. If your software is not available in
-the default repositories, see [installing software from other
+proxy](#updates-proxy) which allows you to install and update software using
+the distribution package manager over the proxy connection.
+**The updates proxy is already set up to work automatically out-of-the-box and
+requires no special action from you.**
+Most users should simply follow the normal instructions for [installing software
+from default repositories](#installing-software-from-default-repositories)
+and [updating](/doc/how-to-update/) software. If your software is not available
+in the default repositories, see [installing software from other
 sources](#installing-software-from-other-sources).
 
 
diff --git a/user/how-to-guides/how-to-update.md b/user/how-to-guides/how-to-update.md
index 8e865234..5a6a7b4f 100644
--- a/user/how-to-guides/how-to-update.md
+++ b/user/how-to-guides/how-to-update.md
@@ -32,7 +32,7 @@ However, you can also start the tool manually by selecting it in the Application
 
 <div class="alert alert-info" role="alert">
   <i class="fa fa-question-circle"></i>
-  For information about how templates download updates, please see <a href="/doc/how-to-install-software/#why-dont-templates-have-network-access">Why don't templates have network access?</a> and the <a href="/doc/how-to-install-software/#updates-proxy">Updates proxy</a>.
+  For information about how templates download updates, please see <a href="/doc/how-to-install-software/#why-dont-templates-have-normal-network-access">Why don't templates have normal network access?</a> and the <a href="/doc/how-to-install-software/#updates-proxy">Updates proxy</a>.
 </div>
 
 By default, most qubes that are connected to the internet will periodically check for updates for their parent templates. You can check the date of the last update check in the "last checked" column. If updates are available for any qube, you will receive a notification as described above, and in the "Updates available" column you will see "YES" for that qube(s). If the update check did not find any new updates, "NO" will appear in the column. Respectively, for qubes that are no longer supported, "OBSOLETE" will be displayed. However, if you have any templates that do *not* have any online child qubes, you will *not* receive update notifications for them. By default, after a week, if updates for a given qube have not been checked, the value in the "Updates available" column will be set to "MAYBE". 
diff --git a/user/templates/templates.md b/user/templates/templates.md
index d12e5585..20328164 100644
--- a/user/templates/templates.md
+++ b/user/templates/templates.md
@@ -140,7 +140,7 @@ After installing a fresh template, we recommend performing the following steps:
 
 For information about how templates access the network, please see [Why don’t
 templates have network
-access?](/doc/how-to-install-software/#why-dont-templates-have-network-access)
+access?](/doc/how-to-install-software/#why-dont-templates-have-normal-network-access)
 and the [Updates proxy](/doc/how-to-install-software/#updates-proxy).
 
 ## Updating

From e86436d0234228b5dce32b9d35f12045eb634494 Mon Sep 17 00:00:00 2001
From: Francis King <francis.king@burohappold.com>
Date: Mon, 24 Mar 2025 16:08:35 +0000
Subject: [PATCH 49/87] Added  some extra text and an example

In a discussion on Qubes OS forum, it was decided that I should add some extra text about the netmask, and an example  for Network Manager. The purpose being to make the procedure much clearer.

There are two images to go into the text, but I don't understand how to do that yet. I have used '>' at those points. Please advise.

Francis.
---
 user/advanced-topics/standalones-and-hvms.md | 29 +++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/user/advanced-topics/standalones-and-hvms.md b/user/advanced-topics/standalones-and-hvms.md
index 198dab42..6c344b47 100644
--- a/user/advanced-topics/standalones-and-hvms.md
+++ b/user/advanced-topics/standalones-and-hvms.md
@@ -175,11 +175,38 @@ seen, e.g., in the Qube Manager in the qube's properties:
 ![r4.0-manager-networking-config.png](/attachment/doc/r4.0-manager-networking-config.png)
 
 Alternatively, one can use the `qvm-ls -n` command to obtain the same
-information (IP/netmask/gateway).
+information (IP/netmask/gateway). The netmask required is that for your own network, 
+so for example, if your IPv4 network has a subnet mask of /24 then the actual netmask to 
+use is 255.255.255.0 - even if the Qube Manager suggests 255.255.255.255  
 
 The DNS IP addresses are `10.139.1.1` and `10.139.1.2`. There is [opt-in
 support](/doc/networking/#ipv6) for IPv6 forwarding.
 
+### An example of setting up a network - Network Manager on KDE
+
+Every guest operating system has its own way of handling networking, and the user is 
+referred to the documentation that comes with that operating system. However, 
+Network Manager is widely used on Linux systems, and so hopefully a worked example will 
+prove useful. The worked example is for a HVM running EndeavourOS. 
+
+> Image of Qubes Manager - is this what it's called??
+
+In this example, Network Manager on KDE, the network had the following values:
+
+1. IPv4 networking
+2. IP address 10.137.0.17
+3. Netmask 255.255.255.255 (but in the network the netmask is actually 255.255.255.0)
+4. Gateway 10.138.24.248
+5. Virtual DNS 10.139.1.1 and 10.139.1.2
+
+> Image of Network Manager, annotated by numbers for reference below
+
+The network was set up by entering Network Manager, tab Wi-Fi & Networking, clicking on the Wired Ethernet
+item, and selecting tab IPv4 (1). The Manual method is selected (2), which reveals areas for data entry. The DNS 
+Servers takes a comma-separated list, here 10.139.1.1,10.1.139.2 (3). At the bottom of the tab (4), click on '+ Add', 
+and enter the IP address of 10.137.0.17 under column 'Address', the Netmask of 25.255.255.0  (to match the network) 
+under column 'Netmask', and the Gateway of 10.138.24.248 under column 'Gateway'. Apply these changes.
+
 ## Using template-based HVMs
 
 Qubes allows HVMs to share a common root filesystem from a select template.

From e529345e72d4732daac512abb470950e38e680e1 Mon Sep 17 00:00:00 2001
From: garindean <31627216+garindean@users.noreply.github.com>
Date: Wed, 2 Apr 2025 01:10:15 -0400
Subject: [PATCH 50/87] Update how-to-organize-your-qubes.md

grammar
---
 user/how-to-guides/how-to-organize-your-qubes.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/user/how-to-guides/how-to-organize-your-qubes.md b/user/how-to-guides/how-to-organize-your-qubes.md
index 677a3b1b..947312b9 100644
--- a/user/how-to-guides/how-to-organize-your-qubes.md
+++ b/user/how-to-guides/how-to-organize-your-qubes.md
@@ -89,7 +89,7 @@ the other. Alice's setup looks like this:
   [bind-dirs](/doc/bind-dirs/) to make those changes persistent, but sometimes
   she doesn't want to get bogged down doing with all that and figures it
   wouldn't be worth it just for this one qube. She's secretly glad that Qubes
-  OS doesn't judge her this and just gives her the freedom to do things however
+  OS doesn't judge her for this and just gives her the freedom to do things however
   she likes while keeping everything securely compartmentalized. At times like
   these, she takes comfort in knowing that things can be messy and disorganized
   *within* a qube while her overall digital life remains well-organized.

From c4129f8852ed279b73ba76ea8d122570c9f17d94 Mon Sep 17 00:00:00 2001
From: Andrew David Wong <adw@qubes-os.org>
Date: Wed, 9 Apr 2025 15:02:04 -0700
Subject: [PATCH 51/87] Fix dead links

---
 .../certified-hardware/certified-hardware.md  | 26 +++++++++----------
 .../dasharo-fidelisguard-z690.md              | 12 ++++-----
 2 files changed, 19 insertions(+), 19 deletions(-)

diff --git a/user/hardware/certified-hardware/certified-hardware.md b/user/hardware/certified-hardware/certified-hardware.md
index a98835a8..3067080b 100644
--- a/user/hardware/certified-hardware/certified-hardware.md
+++ b/user/hardware/certified-hardware/certified-hardware.md
@@ -25,19 +25,19 @@ Qubes-certified computers are certified for a [major release](/doc/version-schem
 
 The current Qubes-certified models are listed below in reverse chronological order of certification.
 
-| Brand                                  | Model                                                                                                                  | Certification details                                                       |
-| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
-| [NovaCustom](https://novacustom.com/)  | [V54 Series](https://novacustom.com/product/v54-series/)                                                               | [Certification details](/doc/certified-hardware/novacustom-v54-series/)     |
-| [Nitrokey](https://www.nitrokey.com/)  | [NitroPad V56](https://shop.nitrokey.com/shop/nitropad-v56-684)                                                        | [Certification details](/doc/certified-hardware/nitropad-v56/)              |
-| [NovaCustom](https://novacustom.com/)  | [V56 Series](https://novacustom.com/product/v56-series/)                                                               | [Certification details](/doc/certified-hardware/novacustom-v56-series/)     |
-| [Nitrokey](https://www.nitrokey.com/)  | [NitroPC Pro 2](https://shop.nitrokey.com/shop/nitropc-pro-2-523)                                                      | [Certification details](/doc/certified-hardware/nitropc-pro-2/)             |
-| [Star Labs](https://starlabs.systems/) | [StarBook](https://starlabs.systems/pages/starbook)                                                                    | [Certification details](/doc/certified-hardware/starlabs-starbook/)         |
-| [Nitrokey](https://www.nitrokey.com/)  | [NitroPC Pro](https://shop.nitrokey.com/shop/product/nitropc-pro-523)                                                  | [Certification details](/doc/certified-hardware/nitropc-pro/)               |
-| [NovaCustom](https://novacustom.com/)  | [NV41 Series](https://novacustom.com/product/nv41-series/)                                                             | [Certification details](/doc/certified-hardware/novacustom-nv41-series/)    |
-| [3mdeb](https://3mdeb.com/)            | [Dasharo FidelisGuard Z690](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) | [Certification details](/doc/certified-hardware/dasharo-fidelisguard-z690/) |
-| [Nitrokey](https://www.nitrokey.com/)  | [NitroPad T430](https://shop.nitrokey.com/shop/product/nitropad-t430-119)                                              | [Certification details](/doc/certified-hardware/nitropad-t430/)             |
-| [Nitrokey](https://www.nitrokey.com/)  | [NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67)                                               | [Certification details](/doc/certified-hardware/nitropad-x230/)             |
-| [Insurgo](https://insurgo.ca/)         | [PrivacyBeast X230](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/)         | [Certification details](/doc/certified-hardware/insurgo-privacybeast-x230/) |
+| Brand                                  | Model                                                                                                                                                                  | Certification details                                                       |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| [NovaCustom](https://novacustom.com/)  | [V54 Series](https://novacustom.com/product/v54-series/)                                                                                                               | [Certification details](/doc/certified-hardware/novacustom-v54-series/)     |
+| [Nitrokey](https://www.nitrokey.com/)  | [NitroPad V56](https://shop.nitrokey.com/shop/nitropad-v56-684)                                                                                                        | [Certification details](/doc/certified-hardware/nitropad-v56/)              |
+| [NovaCustom](https://novacustom.com/)  | [V56 Series](https://novacustom.com/product/v56-series/)                                                                                                               | [Certification details](/doc/certified-hardware/novacustom-v56-series/)     |
+| [Nitrokey](https://www.nitrokey.com/)  | [NitroPC Pro 2](https://shop.nitrokey.com/shop/nitropc-pro-2-523)                                                                                                      | [Certification details](/doc/certified-hardware/nitropc-pro-2/)             |
+| [Star Labs](https://starlabs.systems/) | [StarBook](https://starlabs.systems/pages/starbook)                                                                                                                    | [Certification details](/doc/certified-hardware/starlabs-starbook/)         |
+| [Nitrokey](https://www.nitrokey.com/)  | [NitroPC Pro](https://shop.nitrokey.com/shop/product/nitropc-pro-523)                                                                                                  | [Certification details](/doc/certified-hardware/nitropc-pro/)               |
+| [NovaCustom](https://novacustom.com/)  | [NV41 Series](https://novacustom.com/product/nv41-series/)                                                                                                             | [Certification details](/doc/certified-hardware/novacustom-nv41-series/)    |
+| [3mdeb](https://3mdeb.com/)            | [Dasharo FidelisGuard Z690](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) | [Certification details](/doc/certified-hardware/dasharo-fidelisguard-z690/) |
+| [Nitrokey](https://www.nitrokey.com/)  | [NitroPad T430](https://shop.nitrokey.com/shop/product/nitropad-t430-119)                                                                                              | [Certification details](/doc/certified-hardware/nitropad-t430/)             |
+| [Nitrokey](https://www.nitrokey.com/)  | [NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67)                                                                                               | [Certification details](/doc/certified-hardware/nitropad-x230/)             |
+| [Insurgo](https://insurgo.ca/)         | [PrivacyBeast X230](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/)                                                         | [Certification details](/doc/certified-hardware/insurgo-privacybeast-x230/) |
 
 ## Become hardware certified
 
diff --git a/user/hardware/certified-hardware/dasharo-fidelisguard-z690.md b/user/hardware/certified-hardware/dasharo-fidelisguard-z690.md
index 88a10507..6c85d154 100644
--- a/user/hardware/certified-hardware/dasharo-fidelisguard-z690.md
+++ b/user/hardware/certified-hardware/dasharo-fidelisguard-z690.md
@@ -6,11 +6,11 @@ title: Dasharo FidelisGuard Z690
 image: /attachment/posts/dasharo-fidelisguard-z690_2.jpg
 ---
 
-The [Dasharo FidelisGuard Z690](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.
+The [Dasharo FidelisGuard Z690](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.
 
 [![Photo of MSI PRO Z690-A DDR4 motherboard](/attachment/posts/dasharo-fidelisguard-z690_1.jpg)](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
 
-The [Dasharo FidelisGuard Z690](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is a full desktop PC build that brings the [Dasharo](https://dasharo.com/) open-source firmware distribution to the MSI PRO Z690-A DDR4 motherboard with Qubes OS preinstalled. The full configuration includes:
+The [Dasharo FidelisGuard Z690](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is a full desktop PC build that brings the [Dasharo](https://dasharo.com/) open-source firmware distribution to the MSI PRO Z690-A DDR4 motherboard with Qubes OS preinstalled. The full configuration includes:
 
 | Part         | Model Name                                                     |
 |------------- | -------------------------------------------------------------- |
@@ -21,7 +21,7 @@ The [Dasharo FidelisGuard Z690](https://3mdeb.com/shop/open-source-hardware/dash
 | Storage      | SSD Intel 670p 512 GB M.2 2280 PCI-E x4 Gen3 NVMe              |
 | Enclosure	   | SilentiumPC Armis AR1                                          |
 
-[![Photo of Dasharo FidelisGuard Z690 with open case](/attachment/posts/dasharo-fidelisguard-z690_2.jpg)](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
+[![Photo of Dasharo FidelisGuard Z690 with open case](/attachment/posts/dasharo-fidelisguard-z690_2.jpg)](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
 
 This computer comes with a "Dasharo Supporters Entrance Subscription," which includes the following:
 
@@ -31,8 +31,8 @@ This computer comes with a "Dasharo Supporters Entrance Subscription," which inc
 - Dasharo Premier Support through an invite-only Matrix channel
 - Influence on the Dasharo feature roadmap
 
-[![Photo of Dasharo FidelisGuard Z690 with open case](/attachment/posts/dasharo-fidelisguard-z690_3.jpg)](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
+[![Photo of Dasharo FidelisGuard Z690 with open case](/attachment/posts/dasharo-fidelisguard-z690_3.jpg)](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
 
-For further details, please see the [Dasharo FidelisGuard Z690](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) product page.
+For further details, please see the [Dasharo FidelisGuard Z690](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) product page.
 
-[![Photo of the outside of the Dasharo FidelisGuard Z690](/attachment/posts/dasharo-fidelisguard-z690_4.jpg)](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
+[![Photo of the outside of the Dasharo FidelisGuard Z690](/attachment/posts/dasharo-fidelisguard-z690_4.jpg)](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)

From 187db01576953444c708b5e3cea3edb2b88ddaa3 Mon Sep 17 00:00:00 2001
From: Andrew David Wong <adw@qubes-os.org>
Date: Wed, 9 Apr 2025 15:43:48 -0700
Subject: [PATCH 52/87] Fix dead link

---
 user/hardware/certified-hardware/dasharo-fidelisguard-z690.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/user/hardware/certified-hardware/dasharo-fidelisguard-z690.md b/user/hardware/certified-hardware/dasharo-fidelisguard-z690.md
index 6c85d154..0ded8346 100644
--- a/user/hardware/certified-hardware/dasharo-fidelisguard-z690.md
+++ b/user/hardware/certified-hardware/dasharo-fidelisguard-z690.md
@@ -8,7 +8,7 @@ image: /attachment/posts/dasharo-fidelisguard-z690_2.jpg
 
 The [Dasharo FidelisGuard Z690](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.
 
-[![Photo of MSI PRO Z690-A DDR4 motherboard](/attachment/posts/dasharo-fidelisguard-z690_1.jpg)](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
+[![Photo of MSI PRO Z690-A DDR4 motherboard](/attachment/posts/dasharo-fidelisguard-z690_1.jpg)](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
 
 The [Dasharo FidelisGuard Z690](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is a full desktop PC build that brings the [Dasharo](https://dasharo.com/) open-source firmware distribution to the MSI PRO Z690-A DDR4 motherboard with Qubes OS preinstalled. The full configuration includes:
 

From 674f9b6dd20e8290ae9aa6031c1b615a47010238 Mon Sep 17 00:00:00 2001
From: unman <unman@thirdeyesecurity.org>
Date: Thu, 10 Apr 2025 13:37:18 +0000
Subject: [PATCH 53/87] Fix dead link to Micah's video

---
 introduction/video-tours.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/introduction/video-tours.md b/introduction/video-tours.md
index 575ba8af..94739397 100644
--- a/introduction/video-tours.md
+++ b/introduction/video-tours.md
@@ -22,7 +22,7 @@ Watch all the talks from Qubes OS Summit 2022, which took place September 9-11,
 
 ## Micah Lee presents "Qubes OS: The Operating System That Can Protect You Even If You Get Hacked"
 
-[Micah Lee](https://micahflee.com/), a long-time Qubes [advocate](/endorsements/), presented [Qubes OS: The Operating System That Can Protect You Even If You Get Hacked](https://www.hope.net/schedule.html#-qubes-os-the-operating-system-that-can-protect-you-even-if-you-get-hacked-) at the [Circle of HOPE](https://www.hope.net/index.html) conference, which took place July 20-22, 2018 in New York City.
+[Micah Lee](https://micahflee.com/), a long-time Qubes [advocate](/endorsements/), presented [Qubes OS: The Operating System That Can Protect You Even If You Get Hacked](https://archive.org/details/QubesOSTheOperatingSystemThatCanProtectYouEvenIfYouGetHackedTalkByMicahLee) at the Circle of HOPE conference, which took place July 20-22, 2018 in New York City.
 
 <div class="video more-bottom">
   <iframe class="responsive" referrerpolicy="no-referrer" scrolling="no" allowfullscreen src="https://livestream.com/accounts/9197973/events/8286152/videos/178431606/player?autoPlay=false"></iframe>

From 81e4abc4160d56179f3229f2d7067b8907c207a4 Mon Sep 17 00:00:00 2001
From: unman <unman@thirdeyesecurity.org>
Date: Sun, 13 Apr 2025 12:55:19 +0000
Subject: [PATCH 54/87] Minor changes to workflow.md using Builder v2

---
 developer/building/development-workflow.md | 29 +++++++++++-----------
 1 file changed, 14 insertions(+), 15 deletions(-)

diff --git a/developer/building/development-workflow.md b/developer/building/development-workflow.md
index e4967756..f125533f 100644
--- a/developer/building/development-workflow.md
+++ b/developer/building/development-workflow.md
@@ -12,17 +12,17 @@ title: Development workflow
 
 A workflow for developing Qubes OS+
 
-First things first, setup [QubesBuilder](/doc/qubes-builder-v2/). This guide
+To begin, setup [QubesBuilder](/doc/qubes-builder-v2/). This guide
 assumes you're using qubes-builder v2 to build Qubes.
 
 ## Repositories and committing Code
 
-Qubes is split into a bunch of git repos. These are all contained in the
+Qubes source code is split into many git repos. These are all contained in the
 `artifacts/sources` directory under qubes-builder. Subdirectories there are
 separate components, stored in separate git repositories.
 
 The best way to write and contribute code is to create a git repo somewhere
-(e.g., github) for the repo you are interested in editing (e.g.,
+(e.g., GitHub) for the repo you are interested in editing (e.g.,
 `qubes-manager`, `core-agent-linux`, etc). To integrate your repo with the rest
 of Qubes, cd to the repo directory and add your repository as a remote in git
 
@@ -30,18 +30,17 @@ of Qubes, cd to the repo directory and add your repository as a remote in git
 
 ~~~
 $ cd qubes-builder/artifacts/sources/qubes-manager
-$ git remote add abel git@github.com:abeluck/qubes-manager.git
+$ git remote add abel git@GitHub.com:abeluck/qubes-manager.git
 ~~~
 
 You can then proceed to easily develop in your own branches, pull in new
-commits from the dev branches, merge them, and eventually push to your own repo
-on github.
+commits from the dev branches, merge them, and eventually push to your own repo.
 
 When you are ready to submit your changes to Qubes to be merged, push your
 changes, then create a signed git tag (using `git tag -s`). Finally, send a
-letter to the Qubes listserv describing the changes and including the link to
-your repository. You can also create pull request on github. Don't forget to
-include your public PGP key you use to sign your tags.
+letter to the Qubes listserv describing the changes, and including a link to
+your repository. If you are using GitHub you can instead create a pull request.
+Don't forget to include the public PGP key you use to sign your tags.
 
 ### Kernel-specific notes
 
@@ -117,7 +116,7 @@ vi series.conf
 
 #### Building RPMs
 
-Now it is a good moment to make sure you have changed kernel release name in
+Now is a good moment to make sure you have changed the kernel release name in
 rel file. For example, if you change it to '1debug201211116c' the
 resulting RPMs will be named
 'kernel-3.4.18-1debug20121116c.pvops.qubes.x86\_64.rpm'. This will help
@@ -284,12 +283,12 @@ if [ "$1" = "tb" ]; then
     exit $?
 fi
 
-git remote add $1 git@github.com:$1/qubes-`basename $PWD`
+git remote add $1 git@GitHub.com:$1/qubes-`basename $PWD`
 ~~~
 
 It should be executed from component top level directory. This script takes one
 argument - remote name. If it is `tb`, then it creates qrexec-based git remote
-to `testbuilder` VM. Otherwise it creates remote pointing at github account of
+to `testbuilder` VM. Otherwise it creates remote pointing at GitHub account of
 the same name. In any case it points at repository matching current directory
 name.
 
@@ -308,7 +307,7 @@ current and current-testing).
 
 ### RPM packages - yum repo
 
-In source VM, grab [linux-yum](https://github.com/QubesOS/qubes-linux-yum) repository (below is assumed you've made it in
+In source VM, grab [linux-yum](https://GitHub.com/QubesOS/qubes-linux-yum) repository (below is assumed you've made it in
 `~/repo-yum-upload` directory) and replace `update_repo.sh` script with:
 
 ~~~
@@ -324,7 +323,7 @@ find -type f -name '*.rpm' -delete
 qrexec-client-vm $VMNAME local.UpdateYum
 ~~~
 
-In target VM, setup actual yum repository (also based on [linux-yum](https://github.com/QubesOS/qubes-linux-yum), this time
+In target VM, setup actual yum repository (also based on [linux-yum](https://GitHub.com/QubesOS/qubes-linux-yum), this time
 without modifications). You will also need to setup some gpg key for signing
 packages (it is possible to force yum to install unsigned packages, but it
 isn't possible for `qubes-dom0-update` tool). Fill `~/.rpmmacros` with
@@ -404,7 +403,7 @@ Remember to also import gpg public key using `rpm --import`.
 
 Steps are mostly the same as in the case of yum repo. The only details that differ:
 
-- use [linux-deb](https://github.com/QubesOS/qubes-linux-deb) instead of [linux-yum](https://github.com/QubesOS/qubes-linux-yum) as a base - both in source and target VM
+- use [linux-deb](https://GitHub.com/QubesOS/qubes-linux-deb) instead of [linux-yum](https://GitHub.com/QubesOS/qubes-linux-yum) as a base - both in source and target VM
 - use different `update_repo.sh` script in source VM (below)
 - use `local.UpdateApt` qrexec service in target VM (code below)
 - in target VM additionally place `update-local-repo.sh` script in repository dir (code below)

From 63ad8ab1c1f094ae2cabbc55f5282952cbda887f Mon Sep 17 00:00:00 2001
From: unman <unman@thirdeyesecurity.org>
Date: Sun, 13 Apr 2025 12:57:18 +0000
Subject: [PATCH 55/87] Minor changes to description of qubes-builder-v2

---
 developer/building/qubes-builder-v2.md | 52 +++++++++++++-------------
 1 file changed, 27 insertions(+), 25 deletions(-)

diff --git a/developer/building/qubes-builder-v2.md b/developer/building/qubes-builder-v2.md
index 79d85e21..1210910b 100644
--- a/developer/building/qubes-builder-v2.md
+++ b/developer/building/qubes-builder-v2.md
@@ -10,8 +10,8 @@ ref: 311
 title: Qubes builder v2
 ---
 
-This is a brief introduction of using Qubes Builder v2 to work with Qubes OS
-sources. It will walk you through installing and configuring Builder v2 and
+This is a brief introduction to using Qubes Builder v2 to work with Qubes OS
+sources. It will walk you through installing and configuring Builder v2, and
 using it to fetch and build Qubes OS packages.
 
 For details and customization, use [Qubes OS v2 builder documentation](https://github.com/QubesOS/qubes-builderv2/).
@@ -30,25 +30,17 @@ uploading stages are executed locally outside a cage.
 
 # Setup
 
-This is a simple setup for using a docker executor (a good default choice,
-if you don't know which executor to use, use docker).
+This is a simple setup using a docker executor. This is a good default choice;
+if you don't know which executor to use, use docker.
 
-1. First, decide what qube are you going to use for working with Qubes
+1. First, decide what qube you are going to use when working with Qubes
    Builder v2. It can be an AppVM or a Standalone qube, with some steps
    different between the two.
 
-2. Then, clone the qubes-builder v2 repository into a location of your
-   choice:
-    ```shell
-    git clone https://github.com/QubesOS/qubes-builderv2
-    cd qubes-builderv2/
-    ```
+2. Installing dependencies
 
-3. Installing dependencies
-
-   Dependencies need to be installed for the qube you want to be developing
-   using Qubes Builder v2 - either in its template, or in the qube itself,
-   if it's a standalone.
+   If you want to use an app qube for developing, install dependencies in the template.
+   If you are using a standalone, install them in the qube itself.
     Dependencies are specified in `dependencies-*.
    txt` files in the main builder directory, and you can install them easily
    in the following ways:
@@ -64,7 +56,16 @@ if you don't know which executor to use, use docker).
     $ test -f /usr/share/qubes/marker-vm && sudo apt install qubes-gpg-split
    ```
 
-4. If you haven't used docker in the current qube, you need also to set up
+    If you have installed dependencies in the template, close it, and
+    (re)start the development qube.
+
+3. Clone the qubes-builder v2 repository into a location of your choice:
+    ```shell
+    git clone https://github.com/QubesOS/qubes-builderv2
+    cd qubes-builderv2/
+    ```
+
+4. If you haven't previously used docker in the current qube, you need to set up
    some permissions. In particular, the user has to be added to the `docker`
    group:
     ```shell
@@ -77,8 +78,8 @@ if you don't know which executor to use, use docker).
    $ tools/generate-container-image.sh docker
     ```
 
-   In an AppVM, as `/var/lib/docker` is not persistent by default, you also
-   need to use bind-dirs to avoid repeating this step after reboot, adding
+   In an app qube, as `/var/lib/docker` is not persistent by default, you also
+   need to use [bind-dirs](/doc/bind-dirs/) to avoid repeating this step after reboot, adding
    the following to the `/rw/config/qubes-bind-dirs.d/docker.conf` file in
    this qube:
 
@@ -148,13 +149,14 @@ using Fedora 37, `vm-fc40` would be a qube using Fedora 40 etc.), use:
 $ ./qb -c core-admin-client -d host-fc37 package fetch prep build
 ```
 
-If you want to fetch entire Qubes OS sources (caution: some repositories might
-have additional requirements; you can disable repositories that are not
-needed in the `example-configs/*.yml` file you are using by commenting them
-out. In particular, `python-fido2`, `lvm` and `windows`-related repositories
-have
-special requirements), use the following:
+If you want to fetch the entire Qubes OS source use the following:
 
 ```shell
 $ ./qb package fetch
 ```
+
+**caution**: some repositories might have additional requirements. You can
+disable repositories that are not needed in the `example-configs/*.yml`
+file you are using by commenting them out. In particular, `python-fido2`,
+`lvm` and `windows`-related repositories have special requirements.
+

From b9bec14ae44273d6fcac0f0294ca038122aa2d43 Mon Sep 17 00:00:00 2001
From: unman <unman@thirdeyesecurity.org>
Date: Sun, 13 Apr 2025 14:37:15 +0000
Subject: [PATCH 56/87] Update firewall page to make sure sys-net rules are
 correctly specified

---
 user/security-in-qubes/firewall.md | 35 ++++++++++++++++++------------
 1 file changed, 21 insertions(+), 14 deletions(-)

diff --git a/user/security-in-qubes/firewall.md b/user/security-in-qubes/firewall.md
index 1289db7a..5af06ec4 100644
--- a/user/security-in-qubes/firewall.md
+++ b/user/security-in-qubes/firewall.md
@@ -269,7 +269,8 @@ As an example we can take the use case of qube QubeDest running a web server lis
 
 **1. Identify the IP addresses you will need to use for sys-net, sys-firewall and the destination qube.**
 
-You can get this information using various methods, but only the first one can be used for `sys-net` outside world IP:
+You can get this information using various methods.
+Only the first method can be used for `sys-net` to find the external IP:
 
 - by running this command in each qube: `ip -4 -br a | grep UP`
 - using `qvm-ls -n`
@@ -284,7 +285,12 @@ Note the IP addresses you will need, they will be required in the next steps.
 
 For the following example, we assume that the physical interface ens6 in sys-net is on the local network 192.168.x.y with the IP 192.168.x.n, and that the IP address of sys-firewall is 10.137.1.z.
 
-In the sys-net VM's Terminal, the first step is to define an ntables chain that will receive DNAT rules to relay the network traffic on a given port to the qube NetVM, we recommend to define a new chain for each destination qube to ease rules management:
+When writing rules in sys-net, you can use `iif` or `iifname`.
+`iif` is faster, but can change where interfaces are dynamically created and destroyed, eg. ppp0.
+In that case use `iifname`, like this `iifname ens6`.
+`iifname` can also match wildcards - `iifname "eth*"`
+
+In the sys-net VM's Terminal, the first step is to define an nftables chain that will receive DNAT rules to relay the network traffic on a given port to the qube NetVM, we recommend to define a new chain for each destination qube to ease rules management:
 
 ```
 nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
@@ -292,25 +298,24 @@ nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority fi
 
 > Note: the name `custom-dnat-qubeDST` is arbitrary
 
-> Note: while we use a DNAT chain for a single qube, it's totally possible to have a single DNAT chain for multiple qubes
+> Note: while we use a DNAT chain for a single qube, it's possible to have a single DNAT chain for multiple qubes
 
 Second step, code a natting firewall rule to route traffic on the outside interface for the service to the sys-firewall VM
 
 ```
-nft add rule qubes custom-dnat-qubeDEST iifgroup 1 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z
+nft add rule qubes custom-dnat-qubeDEST iifname ens6 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z
 ```
 
 Third step, code the appropriate new filtering firewall rule to allow new connections for the service
 
 ```
-nft add rule qubes custom-forward iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept
+nft add rule qubes custom-forward iifname ens6 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept
 ```
 
 > Note: If you do not wish to limit the IP addresses connecting to the service, remove `ip saddr 192.168.x.y/24` from the rules
+> If you want to expose the service on multiple interfaces, repeat steps 2 and 3 above, for each interface. Alternatively, you can leave out the interface completely.
 
-> If you want to expose the service on multiple interfaces, repeat the steps 2 and 3 described above, for each interface. Alternatively, you can leave out the interface completely.
-
-Verify the rules on sys-net firewall correctly match the packets you want by looking at its counters, check for the counter lines in the chains `custom-forward` and `custom-dnat-qubeDEST`:
+Verify the rules on the sys-net firewall correctly match the packets you want by looking at the counters: check for the counter lines in the chains `custom-forward` and `custom-dnat-qubeDEST`:
 
 ```
 nft list table ip qubes
@@ -320,12 +325,12 @@ In this example, we can see 7 packets in the forward rule, and 3 packets in the
 
 ```
 chain custom-forward {
-  iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter packets 7 bytes 448 accept
+  iifname ens6 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter packets 7 bytes 448 accept
 }
 
 chain custom-dnat-qubeDEST {
   type nat hook prerouting priority filter + 1; policy accept;
-  iifgroup 1 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter packets 3 bytes 192 dnat to 10.138.33.59
+  iifname ens6 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter packets 3 bytes 192 dnat to 10.138.33.59
 }
 ```
 
@@ -351,18 +356,20 @@ Content of `/rw/config/qubes-firewall-user-script` in `sys-net`:
 if nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
 then
   # create the dnat rule
-  nft add rule qubes custom-dnat-qubeDEST iifgroup 1 saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z
+  nft add rule qubes custom-dnat-qubeDEST iifname ens6 saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z
 
   # allow forwarded traffic
-  nft add rule qubes custom-forward iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept
+  nft add rule qubes custom-forward iifname ens6 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept
 fi
 ~~~
 
 **3. Route packets from the FirewallVM to the VM**
 
-For the following example, we use the fact that the physical interface of sys-firewall, facing sys-net, is eth0. Furthermore, we assume that the target VM running the web server has the IP address 10.137.0.xx and that the IP address of sys-firewall is 10.137.1.z.
+For the following example, we use the fact that the interface of sys-firewall facing sys-net, is eth0.
+This is allocated to iifgroup 1.
+Furthermore, we assume that the IP address of sys-firewall is 10.137.1.z, and the target VM running the web server has the IP address 10.137.0.xx.
 
-In the sys-firewall VM's Terminal, add a DNAT chain that will contain routing rules:
+In the sys-firewall Terminal, add a DNAT chain that will contain routing rules:
 
 ```
 nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'

From c6b0237db645672220e1629775dea7a4aa3909da Mon Sep 17 00:00:00 2001
From: unman <unman@thirdeyesecurity.org>
Date: Sat, 19 Apr 2025 14:03:45 +0000
Subject: [PATCH 57/87] Update networking page to make it clear that the ipv6
 feature only affects qubes-configured networking

---
 developer/system/networking.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/developer/system/networking.md b/developer/system/networking.md
index 76a88de4..c67fdfe3 100644
--- a/developer/system/networking.md
+++ b/developer/system/networking.md
@@ -62,9 +62,12 @@ Such configuration can be expressed by enabling `ipv6` feature only on some subs
 
 ![ipv6-2](/attachment/doc/ipv6-2.png)
 
-Besides enabling IPv6 forwarding, standard Qubes firewall can be used to limit what network resources are available to each qube. Currently only `qvm-firewall` command support adding IPv6 rules, GUI firewall editor will have this ability later.
+Besides enabling IPv6 forwarding, the standard Qubes firewall can be used to limit what network resources are available to each qube. Currently only the `qvm-firewall` command supports adding IPv6 rules, the GUI firewall editor will have this ability later.
+
+**Note:** Setting or unsetting the `ipv6` feature only affects qubes-configured networking. It does not affect e.g. external interfaces. If you want to restrict IPv6 on these interfaces change the settings in Network Manager. Alternatively, disable IPv6 support using methods appropriate to the underlying template.
 
 ### Limitations
 
 Currently only IPv4 DNS servers are configured, regardless of `ipv6` feature state. It is done this way to avoid reconfiguring all connected qubes whenever IPv6 DNS becomes available or not. Configuring qubes to always use IPv6 DNS and only fallback to IPv4 may result in relatively long timeouts and poor usability.
 But note that DNS using IPv4 does not prevent to return IPv6 addresses. In practice this is only a problem for IPv6-only networks.
+

From 5cb2a1e404bd415f35727b1cced9659f3226bb68 Mon Sep 17 00:00:00 2001
From: "Dr. Gerhard Weck" <GerhardWeck@online.de>
Date: Fri, 25 Apr 2025 13:56:11 +0200
Subject: [PATCH 58/87] Describe installation changes for Windows 11

---
 user/templates/windows/windows-qubes-4-1.md | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/user/templates/windows/windows-qubes-4-1.md b/user/templates/windows/windows-qubes-4-1.md
index 4d38a4bb..829a1087 100644
--- a/user/templates/windows/windows-qubes-4-1.md
+++ b/user/templates/windows/windows-qubes-4-1.md
@@ -146,18 +146,17 @@ These parameters are set for the following reasons:
   - Install on first disk.
   - **For Windows 11 only**: Windows 11 requires TPM 2.0, which currently is not supported from Xen. In Order to install Windows 11 under Qubes, the check for TPM in the Windows installer has to be disabled:
  
-    -  When you start setup without having a TPM, you get an error message like *This PC does not fulfil the minimum requirements for Windows 11*.
-    -  Typing Shift-F10 then opens a console window.
+    -  When the window allowing you to select a Windows version is displayed, **do not select a version and close this window**, but instead type Shift-F10 to open a console window.
     -  Here you type `regedit` to start the registry editor.
     -  There you position to the key `HKEY_LOCAL_MACHINE\SYSTEM\Setup`.
     -  Now create the key `LabConfig`.
     -  Position to this key and create 3 DWORD values called `BypassTPMCheck`, `BypassSecureBootCheck` and `BypassRAMCheck` and set each value to `1`.
     -  Close the registry editor and console windows.
-    -  In the setup window, hit the left arrow in the left upper corner. You will then return into the setup, which will continue normally and install Windows 11 without TPM 2.0.
+    -  You will then return to the setup, which will continue normally and install Windows 11 without TPM 2.0.
    
-    :warning: **Caution:** This temporary patch may cease to work if it so pleases Microsoft some time.
+    :warning: **Caution:** This temporary patch may cease to work if it so pleases Microsoft sometime. With version 24H2 it is still working.
     
-    The installation of Windows 11 may require an internet connection to grab a Microsoft ID. This is currently true only for the home addition, but will probably extend to the Pro edition, too. A workaround to bypass the internet connection requirements of the Windows 11 setup has been published that currently works for version 21H2 but may be blocked some time in the future by Microsoft:
+    The installation of Windows 11 may require an internet connection to grab a Microsoft ID. Previously, this was true only for the home edition, but since version 24H2, it extends to the Pro edition, too. A workaround to bypass the internet connection requirements of the Windows 11 setup has been published that works for version 21H2 but may be blocked for newer versions:
     
     - When you reach the “Let’s Connect You To A Network” page, type Shift-F10 to open a console window.
     - Here you type `taskmgr` to start the Task Manager window so you can see all running processes.
@@ -173,6 +172,15 @@ These parameters are set for the following reasons:
     - Enter the username you want to use and click `Next`.
     - Enter a password and click `Next`. You can leave the field blank but it's not recommended.
 
+    For version 24H2, the following actions allow you to install Windows 11 with a local account, if the VM is defined, at least temporarily, without a netVM:
+     - After some reboots, the VM will show a window allowing the selection of an installation country. In this window, type  Shift-F10 to open a console window.
+     - In this window, type `oobe\bypassnro`. The VM will then reboot and return to the country selection window. The network connection window will now show an option "I don't have internet", allowing you to define a local account.
+
+    In new preview builds of Windows (26120 and beyond, and eventually the next release version), the `oobe\bypassnro` command has been erased and no longer works. Instead, there's a new command called start `ms-chx:localonly` that does something similar. In this case, proceed as follows:
+     - Follow the Windows 11 install process until you get to the Sign in screen. Here, type  Shift-F10 to open a console window.
+     - Enter start `ms-cxh:localonly` at the command prompt.
+     - A "Create a user for this PC" dialog window appears, allowing you to define a local account.
+
 - On systems shipped with a Windows license, the product key may be read from flash via root in dom0:
 
     `strings < /sys/firmware/acpi/tables/MSDM`

From 5bd45751f962ce485cacb3bf376991dc2e27b398 Mon Sep 17 00:00:00 2001
From: PixelPilot <161360836+PixelPil0t1@users.noreply.github.com>
Date: Sun, 27 Apr 2025 09:06:44 +0200
Subject: [PATCH 59/87] Update release-notes.md

---
 developer/releases/4_0/release-notes.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/developer/releases/4_0/release-notes.md b/developer/releases/4_0/release-notes.md
index b80a1959..ca97ac0d 100644
--- a/developer/releases/4_0/release-notes.md
+++ b/developer/releases/4_0/release-notes.md
@@ -9,7 +9,7 @@ title: Qubes R4.0 release notes
 New features since 3.2
 ----------------------
 
-* Core management scripts rewrite with better structure and extensibility, [API documentation](https://dev.qubes-os.org/projects/qubes-core-admin/en/latest/)
+* Core management scripts rewrite with better structure and extensibility, [API documentation](https://dev.qubes-os.org/en/latest/index.html)
 * [Admin API](/news/2017/06/27/qubes-admin-api/) allowing strictly controlled managing from non-dom0
 * All `qvm-*` command-line tools rewritten, some options have changed
 * Renaming VM directly is prohibited, there is GUI to clone under new name and remove old VM

From bd8a41941247969c2251b72d068bde25c0fef15c Mon Sep 17 00:00:00 2001
From: unman <unman@thirdeyesecurity.org>
Date: Tue, 29 Apr 2025 12:35:08 +0000
Subject: [PATCH 60/87] Slight change to comment on use of color. Fix minor
 spelling mistake.

---
 introduction/getting-started.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/introduction/getting-started.md b/introduction/getting-started.md
index 4a02083c..34ed98a2 100644
--- a/introduction/getting-started.md
+++ b/introduction/getting-started.md
@@ -67,8 +67,9 @@ in dom0. (That's what your app qubes are for!) In short, be very careful when in
 ### Color & Security
 
 You'll choose a **color** for each of your qubes out of a predefined set of
-colors. The color of the frame of each window on your desktop will correspond to the color of that cube. 
-These colored frames help you keep track of which qube you're currently using and how trustworthy it is. This is especially helpful
+colors. The color of the frame of each window on your desktop will correspond to the color of that qube. 
+These colored frames help you keep track of which qube you're currently using.
+You may use them to show how trustworthy it is. This is especially helpful
 when you have the same program running in multiple qubes at the same time. For
 example, if you're logged in to your bank account in one qube while doing some
 random web surfing in a different qube, you wouldn't want to accidentally enter

From 7870666de371d924021449f8886e1e99d4b110b2 Mon Sep 17 00:00:00 2001
From: unman <unman@thirdeyesecurity.org>
Date: Wed, 30 Apr 2025 11:42:31 +0000
Subject: [PATCH 61/87] Clarified that main method relates to finding
 controller for attached device. Moved QubeManager method to separate section

---
 user/how-to-guides/how-to-use-usb-devices.md | 45 ++++++++++----------
 1 file changed, 22 insertions(+), 23 deletions(-)

diff --git a/user/how-to-guides/how-to-use-usb-devices.md b/user/how-to-guides/how-to-use-usb-devices.md
index f845f89e..58d704ce 100644
--- a/user/how-to-guides/how-to-use-usb-devices.md
+++ b/user/how-to-guides/how-to-use-usb-devices.md
@@ -13,7 +13,7 @@ title: How to use USB devices
 
 If you are looking to handle USB *storage* devices (thumbdrives or USB-drives), please have a look at the [block device](/doc/how-to-use-block-storage-devices/) page.
 
-**Note:** Attaching USB devices to VMs requires a [USB qube](/doc/usb-qubes/).
+**Note:** Attaching USB devices to qubes requires a [USB qube](/doc/usb-qubes/).
 
 **Important security warning:** USB passthrough comes with many security implications.
 Please make sure you carefully read and understand the **[security considerations](/doc/device-handling-security/#usb-security)**.
@@ -36,7 +36,7 @@ Click the device-manager-icon: ![device manager icon](/attachment/doc/media-remo
 A list of available devices appears.
 USB-devices have a USB-icon to their right: ![usb icon](/attachment/doc/generic-usb.png)
 
-Hover on one device to display a list of VMs you may attach it to.
+Hover on one device to display a list of qubes you may attach it to.
 
 Click one of those.
 The USB device will be attached to it.
@@ -44,7 +44,7 @@ You're done.
 
 After you finished using the USB-device, you can detach it the same way by clicking on the Devices Widget.
 You will see an entry in bold for your device such as **`sys-usb:2-5 - 058f_USB_2.0_Camera`**.
-Hover on the attached device to display a list of running VMs.
+Hover on the attached device to display a list of running qubes
 The one to which your device is connected will have an eject button ![eject icon](/attachment/doc/media-eject.png) next to it.
 Click that and your device will be detached.
 
@@ -74,7 +74,7 @@ sys-usb:2-1     03f0:0641 PixArt_Optical_Mouse
 ```
 
 Now, you can use your USB device (camera in this case) in the `work` qube.
-If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section](#installation-of-qubes-usb-proxy).
+If you see the error `ERROR: qubes-usb-proxy not installed in the qube` instead, please refer to the [Installation Section](#installation-of-qubes-usb-proxy).
 
 When you finish, detach the device.
 
@@ -100,7 +100,7 @@ To use this feature, the `qubes-usb-proxy` package needs to be installed in the
 This section exists for reference or in case something broke and you need to reinstall `qubes-usb-proxy`.
 Under normal conditions, `qubes-usb-proxy` should already be installed and good to go.
 
-If you receive this error: `ERROR: qubes-usb-proxy not installed in the VM`, you can install the `qubes-usb-proxy` with the package manager in the VM you want to attach the USB device to.
+If you receive this error: `ERROR: qubes-usb-proxy not installed in the qube`, you can install the `qubes-usb-proxy` with the package manager in the qube you want to attach the USB device to.
 
 - Fedora: 
   ```
@@ -121,12 +121,9 @@ Mouse and keyboard setup are part of [setting up a USB qube](/doc/usb-qubes/).
 
 Some USB devices are not compatible with the USB pass-through method Qubes employs.
 In situations like these, you can try to pass through the entire USB controller to a qube as PCI device.
-However, with this approach one cannot attach single USB devices but has to attach the whole USB controller with whatever USB devices are connected to it.
-
-You can find your controller and its BDF address using either of two methods described below. Using the command-line tools lsusb and readlink or by using the Qube Manager GUI. It is possible that on some system configurations the readlink method produces output which is different from the example below, while the Qube Manager method allows one to easily determine the correct controller and BDF address.
-
-#### Method 1: Using lsusb and readlink
+However, with this approach you cannot attach single *USB devices* but have to attach the whole *USB controller* with whatever USB devices are connected to it.
 
+You can find your controller and its BDF address using the method described below, using the command-line tools `lsusb` and `readlink`.
 If you have multiple USB controllers, you must first figure out which PCI device is the right controller.
 
 First, find out which USB bus the device is connected to (note that these steps need to be run from a terminal inside your USB qube):
@@ -145,7 +142,7 @@ Bus 003 Device 003: ID 413c:818d Dell Computer Corp.
 (In this case, the device isn't fully identified)
 
 The device is connected to USB bus \#3.
-Check which other devices are connected to the same bus, since *all* of them will be attach to the same VM.
+Check which other devices are connected to the same bus, since *all* of them will be attached to the target qube.
 
 To find the right controller, follow the usb bus:
 
@@ -158,27 +155,29 @@ This should output something like:
 ```
 ../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
 ```
-
-If the output format does not match this example, or you are unsure if it contains the correct BDF address, you can try finding the address using method 2 using the Qube Manager instead.
-
-Now you see the path and the text between `/pci0000:00/0000:` and `/usb3` i.e. `00:1a.0` is the BDF address. Strip the address and pass it to the [`qvm-pci` tool](/doc/how-to-use-pci-devices/) to attach the controller to the targetVM.
-
-For example, On R 4.0 the command would look something like
-
+Now you see the path: the text between `/pci0000:00/0000:` and `/usb3` i.e. `00:1a.0` is the BDF address. Strip the address and pass it to the [`qvm-pci` tool](/doc/how-to-use-pci-devices/) to attach the controller to the target qube, like this:
 ```
 qvm-pci attach --persistent personal dom0:00_1a.0
 ```
 
-#### Method 2: Using the Qube Manager
+It is possible that on some system configurations the readlink method produces output which is different from the example above,
+For example, you might see output like this:
+```
+../../../devices/pci0000:00/0000:00:1c.0/0000:01:00.0/usb1
+```
+In this case, there is a PCI bridge, and the BDF address of the controller is the *last* item, 01:00.0
 
-Open the Qube Manager, then right click on one of the VMs and open the settings. Go to the tab "Devices".
+If the output format does not match this example, or you are unsure if it contains the correct BDF address, you can try finding the address using method 2 using the Qube Manager instead.
 
+#### Identifying controllers using the Qube Manager
+Using Qube Manager you can quickly determine the controllers on your system and their BDF addresses.
+
+Open the Qube Manager, then right click on one of the qubes and open the settings. Go to the tab "Devices".
 Here you should see your available devices along with their BDF addresses. Look for the lines containing "USB controller".
-
 They should look something like: `01:00.0 USB controller: Name of manufacturer`
 
 The first part is the BDF address, in this example: `01:00.0`
 
-If, for example, you have 2 USB controllers in your system because you added one you should see 2 such lines and you can probably guess which controller is the one on the mainboard and which one you added. For example, if you have a mainboard with an Intel chipset, it is possible that all of the mainboard devices show as "Intel Corporation" while the added controller shows another name of manufacturer.
+If, for example, you have 2 USB controllers in your system because you added one you should see 2 such lines and you can probably guess which controller is the one on the mainboard and which one you added. For example, if you have a mainboard with an Intel chipset, it is possible that all of the mainboard devices show as "Intel Corporation", while the added controller shows another manufacturer's name.
 
-Now you should be able to tell which is the correct BDF address of the mainboard USB controller or the added USB controller.
+Now you should be able to tell which is the BDF address of the mainboard USB controller or the added USB controller.

From 4a91a742fec5baacf6e338e96631d934759e2f7c Mon Sep 17 00:00:00 2001
From: unman <unman@thirdeyesecurity.org>
Date: Wed, 30 Apr 2025 12:05:15 +0000
Subject: [PATCH 62/87] Minor changes to How to use USB devices page.

---
 user/how-to-guides/how-to-use-usb-devices.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/user/how-to-guides/how-to-use-usb-devices.md b/user/how-to-guides/how-to-use-usb-devices.md
index cdcb7f54..b47c4c14 100644
--- a/user/how-to-guides/how-to-use-usb-devices.md
+++ b/user/how-to-guides/how-to-use-usb-devices.md
@@ -167,10 +167,10 @@ For example, you might see output like this:
 ```
 In this case, there is a PCI bridge, and the BDF address of the controller is the *last* item, 01:00.0
 
-If the output format does not match this example, or you are unsure if it contains the correct BDF address, you can try finding the address using method 2 using the Qube Manager instead.
+If the output format does not match this example, or you are unsure if it contains the correct BDF address, you can try finding the address using using the Qube Manager instead.
 
-#### Identifying controllers using the Qube Manager
-Using Qube Manager you can quickly determine the controllers on your system and their BDF addresses.
+### Identifying controllers using the Qube Manager
+Using Qube Manager you can quickly determine the controllers on your system and their BDF addresses, but not which controller a particular device is attached to.
 
 Open the Qube Manager, then right click on one of the qubes and open the settings. Go to the tab "Devices".
 Here you should see your available devices along with their BDF addresses. Look for the lines containing "USB controller".

From ef37a8c68b16f8b560e47341471ba6e68c9e0ba6 Mon Sep 17 00:00:00 2001
From: unman <unman@thirdeyesecurity.org>
Date: Wed, 30 Apr 2025 13:15:08 +0000
Subject: [PATCH 63/87] Update page on standalones with informatin about
 virtualization modes. Closes
 https://github.com/QubesOS/qubes-issues/issues/7517

---
 user/advanced-topics/standalones-and-hvms.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/user/advanced-topics/standalones-and-hvms.md b/user/advanced-topics/standalones-and-hvms.md
index 198dab42..2eae8b0c 100644
--- a/user/advanced-topics/standalones-and-hvms.md
+++ b/user/advanced-topics/standalones-and-hvms.md
@@ -50,6 +50,21 @@ is about the virtualization mode. In practice, however, it is most common for
 standalones to be HVMs and for HVMs to be standalones. Hence, this page covers
 both topics.
 
+## Understanding Virtualization Modes
+
+PVH has both better performance and better security than either PV or HVM:
+
+PVH has less attack surface than PV, as it relies on Second Level Address Translation (SLAT) hardware. Guests modify their own page tables natively, without hypervisor involvement. Xen does not need to perform complex checks to ensure that a guest cannot obtain write access to its own page tables, as is necessary for PV. Flaws in these checks have been a source of no fewer than four guest ⇒ host escapes: XSA-148, XSA-182, XSA-212, and XSA-213.
+
+PVH also has less attack surface than HVM, as it does not require QEMU to provide device emulation services. While QEMU is confined in a stubdomain, and again in a seccomp based sandbox, the stubdomain has significant attack surface against the hypervisor. Not only does it have the full attack surface of a PV domain, it also has access to additional hypercalls that allow it to control the guest it is providing emulation services for. XSA-109 was a vulnerability in one of these hypercalls.
+
+PVH has better performance than HVM, as the stubdomain iin HVM consumes resources (both memory and a small amount of CPU). There is little difference in the I/O path at runtime, as both PVH and HVM guests usually use paravirtualized I/O protocols.
+
+Surprisingly, PVH often has better performance than PV. This is because PVH does not require hypercalls for page table updates, which are expensive. SLAT does raise the cost of TLB misses, but this is somewhat mitigated by a second-level TLB in recent hardware.
+
+
+
+
 ## Creating a standalone
 
 You can create a standalone in the Qube Manager by selecting the "Type" of

From 55441615bfc082426c4f3b57e45c106afbedbd7e Mon Sep 17 00:00:00 2001
From: unman <unman@thirdeyesecurity.org>
Date: Fri, 2 May 2025 00:24:26 +0000
Subject: [PATCH 64/87] Fix reference to /var/logs/syslog, and add journalctl.
 Update link from Qubes-Community to Forum guides. Minor changes.

---
 user/troubleshooting/vpn-troubleshooting.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/user/troubleshooting/vpn-troubleshooting.md b/user/troubleshooting/vpn-troubleshooting.md
index 4671066c..dbf2ccd4 100644
--- a/user/troubleshooting/vpn-troubleshooting.md
+++ b/user/troubleshooting/vpn-troubleshooting.md
@@ -30,11 +30,11 @@ After suspend/resume, OpenVPN may not automatically reconnect. In order to get i
 
 After setting up OpenVPN and restarting the VM, you may be repeatedly getting the popup "Ready to start link", but the VPN isn't connected.
 
-To figure out the root of the problem, check the VPN logs in `/var/logs/syslog`. The log may reveal issues like missing OpenVPN libraries, which you can then install.
+To figure out the root of the problem, check the VPN logs in `/var/log/syslog` or use `journalctl`. The logs may reveal issues like missing OpenVPN libraries, which you can then install.
 
 ## `notify-send` induced failure
-[Some VPN guides](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md) use complex scripts that by themselves include call of `notify-send`, yet some images may not contain this tool or may not have it working properly.
-For instance calling `notify-send` on `fedora-36` template VM gives:
+[Some VPN guides](https://forum.qubes-os.org/t/configuring-a-proxyvm-vpn-gateway/19061) use complex scripts that include a call to `notify-send`, yet some images may not contain this tool or may not have it working properly.
+For instance calling `notify-send` on a `fedora-36` template VM gives:
 ```
 Failed to execute child process “dbus-launch” (No such file or directory)
 ```
@@ -43,8 +43,8 @@ To check this tool is working properly run:
 ```bash
 sudo notify-send "$(hostname): Test notify-send OK" --icon=network-idle
 ```
-You should see `info` message appear on the top of your screen.
-If that is the case then, `notify-send` is not the issue.
+You should see the `info` message appear on the top of your screen.
+If that is the case then `notify-send` is not the issue.
 If it is not, and you have an error of some sort you can:
-1. Remove all calls of `notify-send` from scripts you are using to start VPN
-2. Use other template VM that have `notify-send` working or find proper guide and make your current template VM run `notify-send` work properly.
+1. Remove all calls to `notify-send` from scripts you are using to start VPN
+2. Use another template qube that has a working `notify-send` or find proper guide and make your current template run `notify-send` work properly.

From 0c4d924d2152cc0179e75557bb5739c2c48929a3 Mon Sep 17 00:00:00 2001
From: unman <unman@thirdeyesecurity.org>
Date: Fri, 2 May 2025 15:00:25 +0000
Subject: [PATCH 65/87] Update release notes link to head API

---
 developer/releases/4_0/release-notes.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/developer/releases/4_0/release-notes.md b/developer/releases/4_0/release-notes.md
index ca97ac0d..56b99d64 100644
--- a/developer/releases/4_0/release-notes.md
+++ b/developer/releases/4_0/release-notes.md
@@ -9,7 +9,7 @@ title: Qubes R4.0 release notes
 New features since 3.2
 ----------------------
 
-* Core management scripts rewrite with better structure and extensibility, [API documentation](https://dev.qubes-os.org/en/latest/index.html)
+* Core management scripts rewrite with better structure and extensibility, [API documentation](https://dev.qubes-os.org/projects/core-admin/en/latest/index.html)
 * [Admin API](/news/2017/06/27/qubes-admin-api/) allowing strictly controlled managing from non-dom0
 * All `qvm-*` command-line tools rewritten, some options have changed
 * Renaming VM directly is prohibited, there is GUI to clone under new name and remove old VM

From 690d2898862903c6151031d27ec135c77e2fb658 Mon Sep 17 00:00:00 2001
From: unman <unman@thirdeyesecurity.org>
Date: Sun, 4 May 2025 12:16:00 +0000
Subject: [PATCH 66/87] Update Debian page to make it clear that the Debian
 template from 4.2.4 cannot be used for salting other qubes.

---
 user/templates/debian/debian.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/user/templates/debian/debian.md b/user/templates/debian/debian.md
index 9fa94cdf..c070791d 100644
--- a/user/templates/debian/debian.md
+++ b/user/templates/debian/debian.md
@@ -60,7 +60,9 @@ This section contains notes about specific Debian releases.
 
 ### Debian 12
 
-If you want to use a Debian 12 template for salting Qubes, you **must** stop the salt-common and salt-ssh packages from being upgraded.
+The Debian-12 templates that ship with release 4.2.4 cannot be used for salting Fedora templates. You must change the template used by `default-mgmt-dvm` to a Fedora template. You can do this in the Qubes Template Switcher tool, or at the command line using `qvm-prefs default-mgmt-dvm template`.
+
+If you have a Debian template from an earlier release that you want to use for salting Qubes, you **must** stop the salt-common and salt-ssh packages from being upgraded.
 Do this by marking these packages on hold *before* updating the template.
 
 ```

From b7dd717ee7ac19df7a510451a1e72c5d7aa38c7d Mon Sep 17 00:00:00 2001
From: Woolfgm <160153877+Dahka2321@users.noreply.github.com>
Date: Sun, 11 May 2025 13:01:27 +0200
Subject: [PATCH 67/87] Update insurgo-privacybeast-x230.md

---
 user/hardware/certified-hardware/insurgo-privacybeast-x230.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/user/hardware/certified-hardware/insurgo-privacybeast-x230.md b/user/hardware/certified-hardware/insurgo-privacybeast-x230.md
index 0e1a0f67..1826f7a3 100644
--- a/user/hardware/certified-hardware/insurgo-privacybeast-x230.md
+++ b/user/hardware/certified-hardware/insurgo-privacybeast-x230.md
@@ -19,7 +19,7 @@ The [Insurgo PrivacyBeast X230](https://insurgo.ca/produit/qubesos-certified-pri
 
 - [coreboot](https://www.coreboot.org/) initialization for the x230 is binary-blob-free, including native graphic initialization. Built with the [Heads](https://github.com/osresearch/heads/) payload, it delivers an [Anti Evil Maid (AEM)](/doc/anti-evil-maid/)-like solution built into the firmware. (Even though our [requirements](/doc/certified-hardware/#hardware-certification-requirements) provide an exception for CPU-vendor-provided blobs for silicon and memory initialization, Insurgo exceeds our requirements by insisting that these be absent from its machines.)
 
-- [Intel ME](https://libreboot.org/faq.html#intelme) is neutered through the AltMeDisable bit, while all modules other than ROMP and BUP, which are required to initialize main CPU, have been [deleted](https://github.com/osresearch/heads-wiki/blob/master/Clean-the-ME-firmware.md#how-to-disabledeactive-most-of-it).
+- [Intel ME](https://libreboot.org/faq.html#intelme) is neutered through the AltMeDisable bit, while all modules other than ROMP and BUP, which are required to initialize main CPU, have been [deleted](https://github.com/linuxboot/heads-wiki/blob/master/Installing-and-Configuring/Flashing-Guides/Clean-the-ME-firmware.md#how-to-disabledeactive-most-of-it).
 
 - A re-ownership process that allows it to ship pre-installed with Qubes OS, including full-disk encryption already in place, but where the final disk encryption key is regenerated only when the machine is first powered on by the user, so that the OEM doesn't know it.
 

From fa23b34a246fee969841be607bb42d660a583e3c Mon Sep 17 00:00:00 2001
From: unman <unman@thirdeyesecurity.org>
Date: Sun, 11 May 2025 11:46:13 +0000
Subject: [PATCH 68/87] Revert "Update documentation on split-gpg2"

This reverts commit 0062dfaa37923d87449073daa9f59775e4f78514, reversing
changes made to 7167897d71f4b84abf52798605bd98396d1628d4.

Retain documentation on split-gpg and add page on split-gpg-v2 as well,
until latter page is fully functional.
---
 user/security-in-qubes/split-gpg.md | 408 ++++++++++++++++++++++------
 1 file changed, 322 insertions(+), 86 deletions(-)

diff --git a/user/security-in-qubes/split-gpg.md b/user/security-in-qubes/split-gpg.md
index f31d1552..637b068f 100644
--- a/user/security-in-qubes/split-gpg.md
+++ b/user/security-in-qubes/split-gpg.md
@@ -37,123 +37,359 @@ Unfortunately this problem of signing reliability is not solvable by Split GPG.)
 With Qubes Split GPG this problem is drastically minimized, because each time the key is to be used the user is asked for consent (with a definable time out, 5 minutes by default), plus is always notified each time the key is used via a tray notification from the domain where GPG backend is running.
 This way it would be easy to spot unexpected requests to decrypt documents.
 
-## Configuration
+[![r2-split-gpg-1.png](/attachment/doc/r2-split-gpg-1.png)](/attachment/doc/r2-split-gpg-1.png)
+[![r2-split-gpg-3.png](/attachment/doc/r2-split-gpg-3.png)](/attachment/doc/r2-split-gpg-3.png)
 
-Create/Edit `/etc/qubes/policy.d/30-user-gpg2.policy` in dom0, and add a line like this:
+## Configuring Split GPG
+
+In dom0, make sure the `qubes-gpg-split-dom0` package is installed.
 
 ```
-qubes.Gpg2 + gpg-client-vm @default allow target=gpg-server-vm
+[user@dom0 ~]$ sudo qubes-dom0-update qubes-gpg-split-dom0
 ```
 
-Import/Generate your secret keys in the server domain.
-For example:
+Make sure you have the `qubes-gpg-split` package installed in the template you will use for the GPG domain.
+
+For Debian or Whonix:
 
 ```
-gpg-server-vm$ gpg --import /path/to/my/secret-keys-export
-gpg-server-vm$ gpg --import-ownertrust /path/to/my/ownertrust-export
-```
-or
-
-```
-gpg-server-vm$ gpg --gen-key
+[user@debian-10 ~]$ sudo apt install qubes-gpg-split
 ```
 
-In dom0 enable the `split-gpg2-client` service in the client domain, for example via the command-line:
-
-```shell
-dom0$ qvm-service <SPLIT_GPG2_CLIENT_DOMAIN_NAME> split-gpg2-client on
-```
-
-To verify if this was done correctly:
-
-```shell
-dom0$ qvm-service <SPLIT_GPG2_CLIENT_DOMAIN_NAME>
-```
-
-Output should be:
-
-```shell
-split-gpg2-client on
-```
-
-Restart the client domain.
-
-Export the **public** part of your keys and import them in the client domain.
-Also import/set proper "ownertrust" values.
-For example:
+For Fedora:
 
 ```
-gpg-server-vm$ gpg --export > public-keys-export
-gpg-server-vm$ gpg --export-ownertrust > ownertrust-export
-gpg-server-vm$ qvm-copy public-keys-export ownertrust-export
-
-gpg-client-vm$ gpg --import ~/QubesIncoming/gpg-server-vm/public-keys-export
-gpg-client-vm$ gpg --import-ownertrust ~/QubesIncoming/gpg-server-vm/ownertrust-export
+[user@fedora-32 ~]$ sudo dnf install qubes-gpg-split
 ```
 
-This should be enough to have it running:
+### Setting up the GPG backend domain
+
+First, create a dedicated app qube for storing your keys (we will be calling it the GPG backend domain).
+It is recommended that this domain be network disconnected (set its netvm to `none`) and only used for this one purpose.
+In later examples this app qube is named `work-gpg`, but of course it might have any other name.
+
+Make sure that gpg is installed there.
+At this stage you can add the private keys you want to store there, or you can now set up Split GPG and add the keys later.
+To check which private keys are in your GPG keyring, use:
+
+```shell_session
+[user@work-gpg ~]$ gpg -K
+/home/user/.gnupg/secring.gpg
+-----------------------------
+sec   4096R/3F48CB21 2012-11-15
+uid                  Qubes OS Security Team <security@qubes-os.org>
+ssb   4096R/30498E2A 2012-11-15
+(...)
 ```
-gpg-client-vm$ gpg -K
+
+This is pretty much all that is required.
+However, you might want to modify the default timeout: this tells the backend for how long the user's approval for key access should be valid.
+(The default is 5 minutes.) You can change this via the `QUBES_GPG_AUTOACCEPT` environment variable.
+You can override it e.g. in `~/.profile`:
+
+```shell_session
+[user@work-gpg ~]$ echo "export QUBES_GPG_AUTOACCEPT=86400" >> ~/.profile
+```
+
+Please note that previously, this parameter was set in ~/.bash_profile.
+This will no longer work.
+If you have the parameter set in ~/.bash_profile you *must* update your configuration.
+
+Please be aware of the caveat regarding passphrase-protected keys in the [Current limitations](#current-limitations) section.
+
+### Configuring the client apps to use Split GPG backend
+
+Normally it should be enough to set the `QUBES_GPG_DOMAIN` to the GPG backend domain name and use `qubes-gpg-client` in place of `gpg`, e.g.:
+
+```shell_session
+[user@work-email ~]$ export QUBES_GPG_DOMAIN=work-gpg
+[user@work-email ~]$ gpg -K
+[user@work-email ~]$ qubes-gpg-client -K
+/home/user/.gnupg/secring.gpg
+-----------------------------
+sec   4096R/3F48CB21 2012-11-15
+uid                  Qubes OS Security Team <security@qubes-os.org>
+ssb   4096R/30498E2A 2012-11-15
+(...)
+
+[user@work-email ~]$ qubes-gpg-client secret_message.txt.asc
+(...)
+```
+
+Note that running normal `gpg -K` in the demo above shows no private keys stored in this app qube.
+
+A note on `gpg` and `gpg2`:
+
+Throughout this guide, we refer to `gpg`, but note that Split GPG uses `gpg2` under the hood for compatibility with programs like Enigmail (which now supports only `gpg2`).
+If you encounter trouble while trying to set up Split GPG, make sure you're using `gpg2` for your configuration and testing, since keyring data may differ between the two installations.
+
+### Advanced Configuration
+
+The `qubes-gpg-client-wrapper` script sets the `QUBES_GPG_DOMAIN` variable automatically based on the content of the file `/rw/config/gpg-split-domain`, which should be set to the name of the GPG backend VM. This file survives the app qube reboot, of course.
+
+```shell_session
+[user@work-email ~]$ sudo bash
+[root@work-email ~]$ echo "work-gpg" > /rw/config/gpg-split-domain
+```
+
+Split GPG's default qrexec policy requires the user to enter the name of the app qube containing GPG keys on each invocation. To improve usability for applications like Thunderbird with Enigmail, in `dom0` place the following line at the top of the file `/etc/qubes-rpc/policy/qubes.Gpg`:
+
+```
+work-email  work-gpg  allow
+```
+
+where `work-email` is the Thunderbird + Enigmail app qube and `work-gpg` contains your GPG keys.
+
+You may also edit the qrexec policy file for Split GPG in order to tell Qubes your default gpg vm (qrexec prompts will appear with the gpg vm preselected as the target, instead of the user needing to type a name in manually). To do this, append `default_target=<vmname>` to `ask` in `/etc/qubes-rpc/policy/qubes.Gpg`. For the examples given on this page:
+
+```
+@anyvm  @anyvm  ask default_target=work-gpg
+```
+
+Note that, because this makes it easier to accept Split GPG's qrexec authorization prompts, it may decrease security if the user is not careful in reviewing presented prompts. This may also be inadvisable if there are multiple app qubes with Split GPG set up.
+
+## Using Thunderbird
+
+### Thunderbird 78 and higher
+
+Starting with version 78, Thunderbird has a built-in PGP feature and no longer requires the Enigmail extension. For users coming from the Enigmail extension, the built-in functionality is more limited currently, including that **public keys must live in your `work-email` qube with Thunderbird rather than your offline `work-gpg` qube**.
+
+In `work-email`, use the Thunderbird config editor (found at the bottom of preferences/options), and search for `mail.openpgp.allow_external_gnupg`. Switch the value to true. Still in config editor, search for `mail.openpgp.alternative_gpg_path`. Set its value to `/usr/bin/qubes-gpg-client-wrapper`. Restart Thunderbird after this change.
+
+[![tb78-1.png](/attachment/doc/tb78-1.png)](/attachment/doc/tb78-1.png)
+[![tb78-2.png](/attachment/doc/tb78-2.png)](/attachment/doc/tb78-2.png)
+[![tb78-3.png](/attachment/doc/tb78-3.png)](/attachment/doc/tb78-3.png)
+
+You need to obtain your key ID which should be **exactly 16 characters**. Enter the command `qubes-gpg-client-wrapper -K --keyid-format long`:
+
+```
+[user@work-email ~]$ qubes-gpg-client-wrapper -K --keyid-format long
 /home/user/.gnupg/pubring.kbx
 -----------------------------
-sec#  rsa2048 2019-12-18 [SC] [expires: 2021-12-17]
-      50C2035AF57B98CD6E4010F1B808E4BB07BA9EFB
-uid           [ultimate] test
-ssb#  rsa2048 2019-12-18 [E]
+sec   rsa2048/777402E6D301615C 2020-09-05 [SC] [expires: 2022-09-05]
+      F7D2D4E922DFB7B2589AF3E9777402E6D301615C
+uid                 [ultimate] Qubes test <user@localhost>
+ssb   rsa2048/370CE932085BA13B 2020-09-05 [E] [expires: 2022-09-05]
 ```
 
-If you want change some server option copy `/usr/share/doc/split-gpg2/examples/qubes-split-gpg2.conf.example` to `~/.config/qubes-split-gpg2/qubes-split-gpg2.conf` and change it as desired, it will take precedence over other loaded files, such as the drop-in configuration files with the suffix `.conf` in `~/.config/qubes-split-gpg2/conf.d/`.
+```
+[user@work-email ~]$ qubes-gpg-client-wrapper --armor --export 777402E6D301615C > 777402E6D301615C.asc
+```
 
-If you have a passphrase on your keys and `gpg-agent` only shows the "keygrip" (something like the fingerprint of the private key) when asking for the passphrase, then make sure that you have imported the public key part in the server domain.
+Open the Account Settings and open the *End-to-End Encryption* tab of the respective email account. Click the *Add Key* button. You'll be offered the choice *Use your external key through GnuPG*. Select it and click Continue.
 
-## Subkeys vs primary keys
+[![tb78-4.png](/attachment/doc/tb78-4.png)](/attachment/doc/tb78-4.png)
+[![tb78-5.png](/attachment/doc/tb78-5.png)](/attachment/doc/tb78-5.png)
 
-split-gpg2 only knows a hash of the data being signed.
-Therefore, it cannot differentiate between e.g. signatures of a piece of data or signatures of another key.
-This means that a client can use split-gpg2 to sign other keys, which split-gpg1 did not allow.
+The key ID reference you would need here is `777402E6D301615C`. Now paste or type the ID of the secret key that you would like to use. Be careful to enter it correctly, because your input isn't verified. Confirm to save this key ID. Now you can select the key ID to use.
 
-To prevent this, split-gpg2 creates a new GnuPG home directory and imports the secret subkeys (**not** the primary key!) to it.
-Clients will be able to use the secret parts of the subkeys, but not of the primary key.
-If your primary key is able to sign data and certify other keys, and your only subkey can only perform encryption, this means that all signing will fail.
-To make signing work again, generate a subkey that is capable of signing but **not** certification.
-split-gpg2 does not generate this key for you, so you need to generate it yourself.
-If you want to generate a key in software, use the `addkey` command of `gpg2 --edit-key`.
-If you want to generate a key on a smartcard or other hardware token, use `addcardkey` instead.
+[![tb78-6.png](/attachment/doc/tb78-6.png)](/attachment/doc/tb78-6.png)
+[![tb78-7.png](/attachment/doc/tb78-7.png)](/attachment/doc/tb78-7.png)
 
-## Advanced usage
+This key ID will be used to digitally sign or send an encrypted message with your account. For this to work, Thunderbird needs a copy of your public key. At this time, Thunderbird doesn't fetch the public key from `/usr/bin/qubes-gpg-client-wrapper`, you must manually import it. Export the key as follow (assuming the key ID would be `777402E6D301615C`):
 
-There are a few option not described in this README.
-See the comments in the example (config and the source code)[https://github.com/QubesOS/qubes-app-linux-split-gpg2/blob/main/qubes-split-gpg2.conf.example].
+[![tb78-8.png](/attachment/doc/tb78-8.png)](/attachment/doc/tb78-8.png)
+[![tb78-9.png](/attachment/doc/tb78-9.png)](/attachment/doc/tb78-9.png)
 
-Similar to a smartcard, split-gpg2 only tries to protect the private key.
-For advanced usages, consider if a specialized RPC service would be better.
-It could do things like checking what data is singed, detailed logging, exposing the encrypted content only to a VM without network, etc.
+Use Thunderbird's Tools menu to open *OpenPGP Key Management*. In that window, use the File menu to access the *Import Public Key(s) From File* command. Open the file with your public key. After the import was successful, right click on the imported key in the list and select *Key Properties*. You must mark your own key as *Yes, I've verified in person this key has the correct fingerprint*.
 
-Using split-gpg2 as the "backend" for split-gpg1 is known to work.
+Once this is done, you should be able to send an encrypted and signed email by selecting *Require Encryption* or *Digitally Sign This Message* in the compose menu *Options* or *Security* toolbar button. You can try it by sending an email to yourself.
 
-## Allow key generation
+[![tb78-10.png](/attachment/doc/tb78-10.png)](/attachment/doc/tb78-10.png)
 
-By setting `allow_keygen = yes` in `qubes-split-gpg2.conf` you can allow the client to generate new keys.
-Normal usage should not need this.
+For more details about using smart cards/Split GPG with Thunderbird PGP feature, please see [Thunderbird:OpenPGP:Smartcards](https://wiki.mozilla.org/Thunderbird:OpenPGP:Smartcards) from which the above documentation is inspired.
 
-**Warning**: This feature is new and not much tested.
-Therefore it's not security supported!
+### Older Thunderbird versions
 
-## Copyright
+For Thunderbird versions below 78, the traditional Enigmail + Split GPG setup is required.
+It is recommended to set up and use `/usr/bin/qubes-gpg-client-wrapper`, as discussed above, in Thunderbird through the Enigmail addon.
 
-Copyright (C) 2014 HW42 <hw42@ipsumj.de>\
-Copyright (C) 2019 Marek Marczykowski-Górecki <marmarek@invisiblethingslab.com>
+**Warning:** Before adding any account, configuring Enigmail with `/usr/bin/qubes-gpg-client-wrapper` is **required**. By default, Enigmail will generate a default GPG key in `work-email` associated with the newly created Thunderbird account. Generally, it corresponds to the email used in `work-gpg` associated to your private key. In consequence, a new, separate private key will be stored in `work-email` but it _does not_ correspond to your private key in `work-gpg`. Comparing the `fingerprint` or `expiration date` will show that they are not the same private key. In order to prevent Enigmail using this default generated local key in `work-email`, you can safely remove it.
 
-This program is free software; you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation; either version 2 of the License, or
-(at your option) any later version.
+On a fresh Enigmail install, your need to change the default `Enigmail Junior Mode`. Go to Thunderbird preferences and then privacy tab. Select `Force using S/MIME and Enigmail`. Then, in the preferences of Enigmail, make it point to `/usr/bin/qubes-gpg-client-wrapper` instead of the standard GnuPG binary:
 
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU General Public License for more details.
+[![tb-enigmail-split-gpg-settings-2.png](/attachment/doc/tb-enigmail-split-gpg-settings-2.png)](/attachment/doc/tb-enigmail-split-gpg-settings-2.png)
 
-You should have received a copy of the GNU General Public License along
-with this program; if not, write to the Free Software Foundation, Inc.,
-51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
\ No newline at end of file
+## Using Keybase with Split GPG
+
+Keybase, a security focused messaging and file-sharing app with GPG integration, can be configured to use Split GPG.
+
+The Keybase service does not preserve/pass the `QUBES_GPG_DOMAIN` environment variable through to underlying GPG processes, so it **must** be configured to use `/usr/bin/qubes-gpg-client-wrapper` (as discussed above) rather than `/usr/bin/qubes-gpg-client`.
+
+The following command will configure Keybase to use `/usr/bin/qubes-gpg-client-wrapper` instead of its built-in GPG client:
+
+```
+$ keybase config set gpg.command /usr/bin/qubes-gpg-client-wrapper
+```
+
+Now that Keybase is configured to use `qubes-gpg-client-wrapper`, you will be able to use `keybase pgp select` to choose a GPG key from your backend GPG app qube and link that key to your Keybase identity.
+
+## Using Git with Split GPG
+
+Git can be configured to utilize Split GPG, something useful if you would like to contribute to the Qubes OS Project as every commit is required to be signed.
+The most basic `~/.gitconfig` file enabling Split GPG looks something like this.
+
+```
+[user]
+	name = <YOUR_NAME>
+	email = <YOUR_EMAIL_ADDRESS>
+	signingKey = <YOUR_KEY_ID>
+
+[gpg]
+	program = qubes-gpg-client-wrapper
+```
+
+Your key id is the public id of your signing key, which can be found by running `qubes-gpg-client --list-keys`.
+In this instance, the key id is E142F75A6B1B610E0E8F874FB45589245791CACB.
+
+```shell_session
+[user@work-email ~]$ qubes-gpg-client --list-keys
+/home/user/.gnupg/pubring.kbx
+-----------------------------
+pub   ed25519 2022-08-16 [C]
+      E142F75A6B1B610E0E8F874FB45589245791CACB
+uid           [ultimate] Qubes User <user@example.com>
+sub   ed25519 2022-08-16 [S]
+sub   cv25519 2022-08-16 [E]
+sub   ed25519 2022-08-16 [A]
+```
+
+To sign commits, you now add the "-S" flag to your commit command, which should prompt for Split GPG usage.
+If you would like to automatically sign all commits, you can add the following snippet to `~/.gitconfig`.
+
+```
+[commit]
+	gpgSign = true
+```
+
+Lastly, if you would like to add aliases to sign and verify tags using the conventions the Qubes OS Project recommends, refer to the [code signing documentation](/doc/code-signing/#using-pgp-with-git).
+
+## Importing public keys
+
+Use `qubes-gpg-import-key` in the client app qube to import the key into the GPG backend VM.
+
+```shell_session
+[user@work-email ~]$ export QUBES_GPG_DOMAIN=work-gpg
+[user@work-email ~]$ qubes-gpg-import-key ~/Downloads/marmarek.asc
+```
+
+A safe, unspoofable user consent dialog box is displayed.
+
+[![r2-split-gpg-5.png](/attachment/doc/r2-split-gpg-5.png)](/attachment/doc/r2-split-gpg-5.png)
+
+Selecting "Yes to All" will add a line in the corresponding [RPC Policy](/doc/rpc-policy/) file.
+
+## Advanced: Using Split GPG with Subkeys
+
+Users with particularly high security requirements may wish to use Split GPG with [subkeys](https://wiki.debian.org/Subkeys).
+However, this setup comes at a significant cost: It will be impossible to sign other people's keys with the master secret key without breaking this security model.
+Nonetheless, if signing others' keys is not required, then Split GPG with subkeys offers unparalleled security for one's master secret key.
+
+### Setup Description
+
+In this example, the following keys are stored in the following locations (see below for definitions of these terms):
+
+| PGP Key(s) | VM Name      |
+| ---------- | ------------ |
+| `sec`      | `vault`      |
+| `ssb`      | `work-gpg`   |
+| `pub`      | `work-email` |
+
+* `sec` (master secret key)
+
+   Depending on your needs, you may wish to create this as a **certify-only (C)** key, i.e., a key which is capable only of signing (a.k.a., "certifying") other keys.
+   This key may be created *without* an expiration date.
+   This is for two reasons.
+   First, the master secret key is never to leave the `vault` VM, so it is extremely unlikely ever to be obtained by an adversary (see below).
+   Second, an adversary who *does* manage to obtain the master secret key either possesses the passphrase to unlock the key (if one is used) or does not.
+   An adversary who *does* possess the passphrase can simply use it to legally extend the expiration date of the key (or remove it entirely).
+   An adversary who does *not* possess the passphrase cannot use the key at all.
+   In either case, an expiration date provides no additional benefit.
+
+   By the same token, however, having a passphrase on the key is of little value.
+   An adversary who is capable of stealing the key from your `vault` would almost certainly also be capable of stealing the passphrase as you enter it.
+   An adversary who obtains the passphrase can then use it in order to change or remove the passphrase from the key.
+   Therefore, using a passphrase at all should be considered optional.
+   It is, however, recommended that a **revocation certificate** be created and safely stored in multiple locations so that the master keypair can be revoked in the (exceedingly unlikely) event that it is ever compromised.
+
+* `ssb` (secret subkey)
+
+   Depending on your needs, you may wish to create two different subkeys: one for **signing (S)** and one for **encryption (E)**.
+   You may also wish to give these subkeys reasonable expiration dates (e.g., one year).
+   Once these keys expire, it is up to you whether to *renew* these keys by extending the expiration dates or to create *new* subkeys when the existing set expires.
+
+   On the one hand, an adversary who obtains any existing encryption subkey (for example) will be able to use it in order to decrypt all emails (for example) which were encrypted to that subkey.
+   If the same subkey were to continue to be used--and its expiration date continually extended--only that one key would need to be stolen (e.g., as a result of the `work-gpg` VM being compromised; see below) in order to decrypt *all* of the user's emails.
+   If, on the other hand, each encryption subkey is used for at most approximately one year, then an adversary who obtains the secret subkey will be capable of decrypting at most approximately one year's worth of emails.
+
+   On the other hand, creating a new signing subkey each year without renewing (i.e., extending the expiration dates of) existing signing subkeys would mean that all of your old signatures would eventually read as "EXPIRED" whenever someone attempts to verify them.
+   This can be problematic, since there is no consensus on how expired signatures should be handled.
+   Generally, digital signatures are intended to last forever, so this is a strong reason against regularly retiring one's signing subkeys.
+
+* `pub` (public key)
+
+   This is the complement of the master secret key.
+   It can be uploaded to keyservers (or otherwise publicly distributed) and may be signed by others.
+
+* `vault`
+
+   This is a network-isolated VM.
+   The initial master keypair and subkeys are generated in this VM.
+   The master secret key *never* leaves this VM under *any* circumstances.
+   No files or text is *ever* [copied](/doc/how-to-copy-and-move-files/#security) or [pasted](/doc/how-to-copy-and-paste-text/#security) into this VM under *any* circumstances.
+
+* `work-gpg`
+
+   This is a network-isolated VM.
+   This VM is used *only* as the GPG backend for `work-email`.
+   The secret subkeys (but *not* the master secret key) are [copied](/doc/how-to-copy-and-move-files/#security) from the `vault` VM to this VM.
+   Files from less trusted VMs are *never* [copied](/doc/how-to-copy-and-move-files/#security) into this VM under *any* circumstances.
+
+* `work-email`
+
+   This VM has access to the mail server.
+   It accesses the `work-gpg` VM via the Split GPG protocol.
+   The public key may be stored in this VM so that it can be attached to emails and for other such purposes.
+
+### Security Benefits
+
+In the standard Split GPG setup, there are at least two ways in which the `work-gpg` VM might be compromised.
+First, an attacker who is capable of exploiting a hypothetical bug in `work-email`'s [MUA](https://en.wikipedia.org/wiki/Mail_user_agent) could gain control of the `work-email` VM and send a malformed request which exploits a hypothetical bug in the GPG backend (running in the `work-gpg` VM), giving the attacker control of the `work-gpg` VM.
+Second, a malicious public key file which is imported into the `work-gpg` VM might exploit a hypothetical bug in the GPG backend which is running there, again giving the attacker control of the `work-gpg` VM.
+In either case, such an attacker might then be able to leak both the master secret key and its passphrase (if any is used, it would regularly be input in the work-gpg VM and therefore easily obtained by an attacker who controls this VM) back to the `work-email` VM or to another VM (e.g., the `netvm`, which is always untrusted by default) via the Split GPG protocol or other [covert channels](/doc/data-leaks/).
+Once the master secret key is in the `work-email` VM, the attacker could simply email it to himself (or to the world).
+
+In the alternative setup described in this section (i.e., the subkey setup), even an attacker who manages to gain access to the `work-gpg` VM will not be able to obtain the user's master secret key since it is simply not there.
+Rather, the master secret key remains in the `vault` VM, which is extremely unlikely to be compromised, since nothing is ever copied or transferred into it.
+[^a-note] The attacker might nonetheless be able to leak the secret subkeys from the `work-gpg` VM in the manner described above, but even if this is successful, the secure master secret key can simply be used to revoke the compromised subkeys and to issue new subkeys in their place.
+(This is significantly less devastating than having to create a new *master* keypair.)
+
+[^a-note]: In order to gain access to the `vault` VM, the attacker would require the use of, e.g., a general Xen VM escape exploit or a [signed, compromised package which is already installed in the template](/doc/templates/#trusting-your-templates) upon which the `vault` VM is based.
+
+### Subkey Tutorials and Discussions
+
+(Note: Although the tutorials below were not written with Qubes Split GPG in mind, they can be adapted with a few commonsense adjustments.
+As always, exercise caution and use your good judgment.)
+
+* ["OpenPGP in Qubes OS" on the qubes-users mailing list](https://groups.google.com/d/topic/qubes-users/Kwfuern-R2U/discussion)
+* ["Creating the Perfect GPG Keypair" by Alex Cabal](https://alexcabal.com/creating-the-perfect-gpg-keypair/)
+* ["GPG Offline Master Key w/ smartcard" maintained by Abel Luck](https://gist.github.com/abeluck/3383449)
+* ["Using GnuPG with QubesOS" by Alex](https://apapadop.wordpress.com/2013/08/21/using-gnupg-with-qubesos/)
+
+## Current limitations
+
+* Current implementation requires importing of public keys to the vault domain.
+  This opens up an avenue to attack the gpg running in the backend domain via a hypothetical bug in public key importing code.
+  See ticket [#474](https://github.com/QubesOS/qubes-issues/issues/474) for more details and plans how to get around this problem, as well as the section on [using Split GPG with subkeys](#advanced-using-split-gpg-with-subkeys).
+
+* It doesn't solve the problem of allowing the user to know what is to be signed before the operation gets approved.
+  Perhaps the GPG backend domain could start a disposable and have the to-be-signed document displayed there? To Be Determined.
+
+* The Split GPG client will fail to sign or encrypt if the private key in the GnuPG backend is protected by a passphrase.
+  It will give an `Inappropriate ioctl for device` error.
+  Do not set passphrases for the private keys in the GPG backend domain.
+  Doing so won't provide any extra security anyway, as explained in the introduction and in [using Split GPG with subkeys](#advanced-using-split-gpg-with-subkeys).
+  If you are generating a new key pair, or if you have a private key that already has a passphrase, you can use `gpg2 --edit-key <key_id>` then `passwd` to set an empty passphrase.
+  Note that `pinentry` might show an error when you try to set an empty passphrase, but it will still make the change.
+  (See [this StackExchange answer](https://unix.stackexchange.com/a/379373) for more information.)
+  Note: The error shows only if you **do not** have graphical pinentry installed.

From ec6f975c82711d37be17934fc4c744b38018adec Mon Sep 17 00:00:00 2001
From: unman <unman@thirdeyesecurity.org>
Date: Sun, 11 May 2025 12:07:51 +0000
Subject: [PATCH 69/87] Add separate page for split-gpg-2

---
 user/security-in-qubes/split-gpg-2.md | 157 ++++++++++++++++++++++++++
 1 file changed, 157 insertions(+)
 create mode 100644 user/security-in-qubes/split-gpg-2.md

diff --git a/user/security-in-qubes/split-gpg-2.md b/user/security-in-qubes/split-gpg-2.md
new file mode 100644
index 00000000..68cdb3aa
--- /dev/null
+++ b/user/security-in-qubes/split-gpg-2.md
@@ -0,0 +1,157 @@
+---
+lang: en
+layout: doc
+permalink: /doc/split-gpg-2/
+redirect_from:
+- /en/doc/split-gpg-2/
+- /doc/SplitGpg-2/
+- /doc/UserDoc/SplitGpg-2/
+- /doc/open-pgp-2/
+- /en/doc/open-pgp-2/
+- /doc/OpenPGP-2/
+- /doc/UserDoc/OpenPGP-2/
+ref: 568
+title: Split GPG-2
+---
+
+Split GPG implements a concept similar to having a smart card with your private GPG keys, except that the role of the "smart card" is played by another Qubes app qube.
+This way one not-so-trusted domain, e.g. the one where Thunderbird is running, can delegate all crypto operations -- such as encryption/decryption and signing -- to another, more trusted, network-isolated domain.
+This way the compromise of your domain where Thunderbird or another client app is running -- arguably a not-so-unthinkable scenario -- does not allow the attacker to automatically also steal all your keys.
+(We should make a rather obvious comment here that the so-often-used passphrases on private keys are pretty meaningless because the attacker can easily set up a simple backdoor which would wait until the user enters the passphrase and steal the key then.)
+
+[![split-gpg-diagram.png](/attachment/doc/split-gpg-diagram.png)](/attachment/doc/split-gpg-diagram.png)
+
+This diagram presents an overview of the Split GPG architecture.
+
+## Advantages of Split GPG vs. traditional GPG with a smart card
+
+It is often thought that the use of smart cards for private key storage guarantees ultimate safety.
+While this might be true (unless the attacker can find a usually-very-expensive-and-requiring-physical-presence way to extract the key from the smart card) but only with regards to the safety of the private key itself.
+However, there is usually nothing that could stop the attacker from requesting the smart card to perform decryption of all the user documents the attacker has found or need to decrypt.
+In other words, while protecting the user's private key is an important task, we should not forget that ultimately it is the user data that are to be protected and that the smart card chip has no way of knowing the requests to decrypt documents are now coming from the attacker's script and not from the user sitting in front of the monitor.
+(Similarly the smart card doesn't make the process of digitally signing a document or a transaction in any way more secure -- the user cannot know what the chip is really signing.
+Unfortunately this problem of signing reliability is not solvable by Split GPG.)
+
+With Qubes Split GPG this problem is drastically minimized, because each time the key is to be used the user is asked for consent (with a definable time out, 5 minutes by default), plus is always notified each time the key is used via a tray notification from the domain where GPG backend is running.
+This way it would be easy to spot unexpected requests to decrypt documents.
+
+## Configuration
+
+Create/Edit `/etc/qubes/policy.d/30-user-gpg2.policy` in dom0, and add a line like this:
+
+```
+qubes.Gpg2 + gpg-client-vm @default allow target=gpg-server-vm
+```
+
+Import/Generate your secret keys in the server domain.
+For example:
+
+```
+gpg-server-vm$ gpg --import /path/to/my/secret-keys-export
+gpg-server-vm$ gpg --import-ownertrust /path/to/my/ownertrust-export
+```
+or
+
+```
+gpg-server-vm$ gpg --gen-key
+```
+
+In dom0 enable the `split-gpg2-client` service in the client domain, for example via the command-line:
+
+```shell
+dom0$ qvm-service <SPLIT_GPG2_CLIENT_DOMAIN_NAME> split-gpg2-client on
+```
+
+To verify if this was done correctly:
+
+```shell
+dom0$ qvm-service <SPLIT_GPG2_CLIENT_DOMAIN_NAME>
+```
+
+Output should be:
+
+```shell
+split-gpg2-client on
+```
+
+Restart the client domain.
+
+Export the **public** part of your keys and import them in the client domain.
+Also import/set proper "ownertrust" values.
+For example:
+
+```
+gpg-server-vm$ gpg --export > public-keys-export
+gpg-server-vm$ gpg --export-ownertrust > ownertrust-export
+gpg-server-vm$ qvm-copy public-keys-export ownertrust-export
+
+gpg-client-vm$ gpg --import ~/QubesIncoming/gpg-server-vm/public-keys-export
+gpg-client-vm$ gpg --import-ownertrust ~/QubesIncoming/gpg-server-vm/ownertrust-export
+```
+
+This should be enough to have it running:
+```
+gpg-client-vm$ gpg -K
+/home/user/.gnupg/pubring.kbx
+-----------------------------
+sec#  rsa2048 2019-12-18 [SC] [expires: 2021-12-17]
+      50C2035AF57B98CD6E4010F1B808E4BB07BA9EFB
+uid           [ultimate] test
+ssb#  rsa2048 2019-12-18 [E]
+```
+
+If you want change some server option copy `/usr/share/doc/split-gpg2/examples/qubes-split-gpg2.conf.example` to `~/.config/qubes-split-gpg2/qubes-split-gpg2.conf` and change it as desired, it will take precedence over other loaded files, such as the drop-in configuration files with the suffix `.conf` in `~/.config/qubes-split-gpg2/conf.d/`.
+
+If you have a passphrase on your keys and `gpg-agent` only shows the "keygrip" (something like the fingerprint of the private key) when asking for the passphrase, then make sure that you have imported the public key part in the server domain.
+
+## Subkeys vs primary keys
+
+split-gpg2 only knows a hash of the data being signed.
+Therefore, it cannot differentiate between e.g. signatures of a piece of data or signatures of another key.
+This means that a client can use split-gpg2 to sign other keys, which split-gpg1 did not allow.
+
+To prevent this, split-gpg2 creates a new GnuPG home directory and imports the secret subkeys (**not** the primary key!) to it.
+Clients will be able to use the secret parts of the subkeys, but not of the primary key.
+If your primary key is able to sign data and certify other keys, and your only subkey can only perform encryption, this means that all signing will fail.
+To make signing work again, generate a subkey that is capable of signing but **not** certification.
+split-gpg2 does not generate this key for you, so you need to generate it yourself.
+If you want to generate a key in software, use the `addkey` command of `gpg2 --edit-key`.
+If you want to generate a key on a smartcard or other hardware token, use `addcardkey` instead.
+
+## Advanced usage
+
+There are a few option not described in this README.
+See the comments in the example (config and the source code)[https://github.com/QubesOS/qubes-app-linux-split-gpg2/blob/main/qubes-split-gpg2.conf.example].
+
+Similar to a smartcard, split-gpg2 only tries to protect the private key.
+For advanced usages, consider if a specialized RPC service would be better.
+It could do things like checking what data is singed, detailed logging, exposing the encrypted content only to a VM without network, etc.
+
+Using split-gpg2 as the "backend" for split-gpg1 is known to work.
+
+## Allow key generation
+
+By setting `allow_keygen = yes` in `qubes-split-gpg2.conf` you can allow the client to generate new keys.
+Normal usage should not need this.
+
+**Warning**: This feature is new and not much tested.
+Therefore it's not security supported!
+
+## Copyright
+
+Copyright (C) 2014 HW42 <hw42@ipsumj.de>\
+Copyright (C) 2019 Marek Marczykowski-Górecki <marmarek@invisiblethingslab.com>
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along
+with this program; if not, write to the Free Software Foundation, Inc.,
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

From a5b15bdf5b01682ff8e272162cc7c13d14ed5def Mon Sep 17 00:00:00 2001
From: unman <unman@thirdeyesecurity.org>
Date: Sun, 11 May 2025 12:30:50 +0000
Subject: [PATCH 70/87] Add link to incomplete page on split-gpg-2 from current
 split-gpg page

---
 user/security-in-qubes/split-gpg.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/user/security-in-qubes/split-gpg.md b/user/security-in-qubes/split-gpg.md
index 637b068f..86966b2f 100644
--- a/user/security-in-qubes/split-gpg.md
+++ b/user/security-in-qubes/split-gpg.md
@@ -16,6 +16,12 @@ ref: 168
 title: Split GPG
 ---
 
+<div class="alert alert-warning" role="alert">
+  <i class="fa fa-exclamation-circle"></i>
+  <b>Note:</b> This information concerns split-gpg. 
+  The implementation has been updated to provide more features in split-gpg-2. Some incomplete information on split-gpg-2 is available <a href="https://www.qubes-os.org/doc/split-gpg-2/">here</a>
+</div>
+
 Split GPG implements a concept similar to having a smart card with your private GPG keys, except that the role of the "smart card" is played by another Qubes app qube.
 This way one not-so-trusted domain, e.g. the one where Thunderbird is running, can delegate all crypto operations -- such as encryption/decryption and signing -- to another, more trusted, network-isolated domain.
 This way the compromise of your domain where Thunderbird or another client app is running -- arguably a not-so-unthinkable scenario -- does not allow the attacker to automatically also steal all your keys.

From 9fede33dcd29058f57bae0a324e46e5a9f4f2a3d Mon Sep 17 00:00:00 2001
From: Andrew David Wong <adw@qubes-os.org>
Date: Tue, 13 May 2025 13:39:41 -0700
Subject: [PATCH 71/87] Remove Fedora 40 from supported templates (EOL)

---
 user/downloading-installing-upgrading/supported-releases.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/user/downloading-installing-upgrading/supported-releases.md b/user/downloading-installing-upgrading/supported-releases.md
index 30d8d4eb..42740d4c 100644
--- a/user/downloading-installing-upgrading/supported-releases.md
+++ b/user/downloading-installing-upgrading/supported-releases.md
@@ -57,7 +57,7 @@ It is the responsibility of each distribution to clearly notify its users in adv
 
 | Qubes OS    | Fedora | Debian |
 | ----------- | ------ | ------ |
-| Release 4.2 | 40, 41 | 12     |
+| Release 4.2 | 41     | 12     |
 
 ### Note on Debian support
 

From 07b2392c3fffe69b63b4143ac1182ed06934ce9f Mon Sep 17 00:00:00 2001
From: Woolfgm <160153877+Dahka2321@users.noreply.github.com>
Date: Wed, 14 May 2025 11:40:56 +0200
Subject: [PATCH 72/87] Update qrexec-internals.md

---
 developer/services/qrexec-internals.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/developer/services/qrexec-internals.md b/developer/services/qrexec-internals.md
index 8f0a10ac..7e05d278 100644
--- a/developer/services/qrexec-internals.md
+++ b/developer/services/qrexec-internals.md
@@ -253,4 +253,4 @@ There are two endpoints:
 - `policy.Ask` - ask the user about whether to execute a given action
 - `policy.Notify` - notify the user about an action.
 
-See [qrexec-policy-agent.rst](https://github.com/QubesOS/qubes-core-qrexec/blob/master/Documentation/qrexec-policy-agent.rst) for protocol details.
+See [qrexec-policy-agent.md](https://github.com/QubesOS/qubes-core-qrexec/blob/master/doc/qrexec-policy-agent.md) for protocol details.

From c6b07c0191194b90a5abbbe977a0c3e1eb02cdf3 Mon Sep 17 00:00:00 2001
From: unman <unman@thirdeyesecurity.org>
Date: Thu, 15 May 2025 10:29:39 +0000
Subject: [PATCH 73/87] Added Titles to images. Normalised language in
 description of procedure

---
 user/advanced-topics/standalones-and-hvms.md | 49 ++++++++++++++------
 1 file changed, 34 insertions(+), 15 deletions(-)

diff --git a/user/advanced-topics/standalones-and-hvms.md b/user/advanced-topics/standalones-and-hvms.md
index 6c344b47..e76d2f9b 100644
--- a/user/advanced-topics/standalones-and-hvms.md
+++ b/user/advanced-topics/standalones-and-hvms.md
@@ -50,6 +50,21 @@ is about the virtualization mode. In practice, however, it is most common for
 standalones to be HVMs and for HVMs to be standalones. Hence, this page covers
 both topics.
 
+## Understanding Virtualization Modes
+
+PVH has both better performance and better security than either PV or HVM:
+
+PVH has less attack surface than PV, as it relies on Second Level Address Translation (SLAT) hardware. Guests modify their own page tables natively, without hypervisor involvement. Xen does not need to perform complex checks to ensure that a guest cannot obtain write access to its own page tables, as is necessary for PV. Flaws in these checks have been a source of no fewer than four guest ⇒ host escapes: XSA-148, XSA-182, XSA-212, and XSA-213.
+
+PVH also has less attack surface than HVM, as it does not require QEMU to provide device emulation services. While QEMU is confined in a stubdomain, and again in a seccomp based sandbox, the stubdomain has significant attack surface against the hypervisor. Not only does it have the full attack surface of a PV domain, it also has access to additional hypercalls that allow it to control the guest it is providing emulation services for. XSA-109 was a vulnerability in one of these hypercalls.
+
+PVH has better performance than HVM, as the stubdomain iin HVM consumes resources (both memory and a small amount of CPU). There is little difference in the I/O path at runtime, as both PVH and HVM guests usually use paravirtualized I/O protocols.
+
+Surprisingly, PVH often has better performance than PV. This is because PVH does not require hypercalls for page table updates, which are expensive. SLAT does raise the cost of TLB misses, but this is somewhat mitigated by a second-level TLB in recent hardware.
+
+
+
+
 ## Creating a standalone
 
 You can create a standalone in the Qube Manager by selecting the "Type" of
@@ -175,37 +190,41 @@ seen, e.g., in the Qube Manager in the qube's properties:
 ![r4.0-manager-networking-config.png](/attachment/doc/r4.0-manager-networking-config.png)
 
 Alternatively, one can use the `qvm-ls -n` command to obtain the same
-information (IP/netmask/gateway). The netmask required is that for your own network, 
-so for example, if your IPv4 network has a subnet mask of /24 then the actual netmask to 
-use is 255.255.255.0 - even if the Qube Manager suggests 255.255.255.255  
+information (IP/netmask/gateway).
+The Qube Settimgs shows a netmask of 255.255.255.255.
+This is not suitable for most standalones, and you will need to use a different value.
 
-The DNS IP addresses are `10.139.1.1` and `10.139.1.2`. There is [opt-in
-support](/doc/networking/#ipv6) for IPv6 forwarding.
+In Qubes, the IP address is usually in range 10.137.0.0/16, with disposables in range 10.138.0.0/16, and DNS set to `10.139.1.1` and `10.139.1.2`.
+The simplest solution is to set the netmask to 255.0.0.0 - standard for a class A network.
+If you want a more restricted solution you could use 255.252.0.0, or 255.255.255.0
+
+There is [opt-in support](/doc/networking/#ipv6) for IPv6 forwarding.
 
 ### An example of setting up a network - Network Manager on KDE
 
 Every guest operating system has its own way of handling networking, and the user is 
 referred to the documentation that comes with that operating system. However, 
-Network Manager is widely used on Linux systems, and so hopefully a worked example will 
-prove useful. The worked example is for a HVM running EndeavourOS. 
+Network Manager is widely used on Linux systems, and so a worked example will 
+prove useful. This example is for an HVM running EndeavourOS. 
 
-> Image of Qubes Manager - is this what it's called??
+![Image of Qube Settings](/attachment/doc/EndeavourOS_Network.png "Qube Settings")
 
 In this example, Network Manager on KDE, the network had the following values:
 
 1. IPv4 networking
 2. IP address 10.137.0.17
-3. Netmask 255.255.255.255 (but in the network the netmask is actually 255.255.255.0)
+3. Netmask - qube settings showed 255.255.255.255, but we decided to use 255.255.255.0
 4. Gateway 10.138.24.248
 5. Virtual DNS 10.139.1.1 and 10.139.1.2
 
-> Image of Network Manager, annotated by numbers for reference below
+![Image of Network Manager, annotated by numbers for reference below](/attachment/doc/Network Manager.png "Annotated image of KDE Network Manager")
 
-The network was set up by entering Network Manager, tab Wi-Fi & Networking, clicking on the Wired Ethernet
-item, and selecting tab IPv4 (1). The Manual method is selected (2), which reveals areas for data entry. The DNS 
-Servers takes a comma-separated list, here 10.139.1.1,10.1.139.2 (3). At the bottom of the tab (4), click on '+ Add', 
-and enter the IP address of 10.137.0.17 under column 'Address', the Netmask of 25.255.255.0  (to match the network) 
-under column 'Netmask', and the Gateway of 10.138.24.248 under column 'Gateway'. Apply these changes.
+The network was set up by entering Network Manager, selecting the Wi-Fi & Networking tab, clicking on the Wired Ethernet
+item, and selecting tab IPv4 (1).
+The Manual method was selected (2), which revealed areas for data entry.
+The DNS Servers section takes a comma-separated list, here 10.139.1.1,10.1.139.2 (3).
+At the bottom of the tab (4),  the '+ Add' button was selected, and the IP address of 10.137.0.17 entered in the 'Address' column,  the Netmask of 255.255.255.0 entered in the 'Netmask' column, and the Gateway of 10.138.24.248 under 'Gateway'.
+Selecting the "Apply" button stored these changes
 
 ## Using template-based HVMs
 

From 73294eb89d3eeb7f7d891716a8c4cdf8a099c0da Mon Sep 17 00:00:00 2001
From: unman <unman@thirdeyesecurity.org>
Date: Thu, 15 May 2025 11:08:21 +0000
Subject: [PATCH 74/87] Minor changes in how-to-install-software

---
 user/how-to-guides/how-to-install-software.md | 22 +++++++++----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/user/how-to-guides/how-to-install-software.md b/user/how-to-guides/how-to-install-software.md
index 094f526e..87f8af4b 100644
--- a/user/how-to-guides/how-to-install-software.md
+++ b/user/how-to-guides/how-to-install-software.md
@@ -68,13 +68,6 @@ will appear in the Applications Menu. (If you encounter problems, see
 
 ## Installing software from other sources
 
-**Warning:** This method gives your template direct network access, which is
-[risky](#why-dont-templates-have-normal-network-access). This method is **not**
-recommended for trusted templates. Moreover, depending on how you install this
-software, it may not get updated automatically when you [update Qubes
-normally](/doc/how-to-update/), which means you may have to update it manually
-yourself.
-
 Some software is not available from the default repositories and must be
 downloaded and installed from another source. Depending on the installation method,
 you may either use the updates proxy or direct networking.
@@ -98,8 +91,15 @@ $ export HTTP_PROXY=http://127.0.0.1:8082 http_proxy=$HTTP_PROXY \
 
 ### Using direct networking
 
-This method assumes that you're trying to follow the instructions to install some piece
-of software in a normal operating system, except that operating system is running as a
+**Warning:** This method gives your template direct network access, which is
+[risky](#why-dont-templates-have-normal-network-access). This method is **not**
+recommended for trusted templates. Moreover, depending on how you install this
+software, it may not get updated automatically when you [update Qubes
+normally](/doc/how-to-update/), which means you may have to update it manually
+yourself.
+
+This method assumes that you are trying to follow instructions to install some piece
+of software in a normal operating system, except *that* operating system is running as a
 template in Qubes OS.
 
 1. (Recommended) Clone the desired template (since this new template will
@@ -166,7 +166,7 @@ Please see [How to Update](/doc/how-to-update/).
 In order to protect you from performing risky activities in templates, they do
 not have normal network access by default. Instead, templates use an [updates
 proxy](#updates-proxy) which allows you to install and update software using
-the distribution package manager over the proxy connection.
+the distribution's package manager over the proxy connection.
 **The updates proxy is already set up to work automatically out-of-the-box and
 requires no special action from you.**
 Most users should simply follow the normal instructions for [installing software
@@ -179,7 +179,7 @@ sources](#installing-software-from-other-sources).
 ## Advanced
 
 The following sections cover advanced topics pertaining to installing and
-updating software in domUs.
+updating software in qubes.
 
 
 ### Testing repositories

From b594557061312229e0d30f81ecd99f5a2efef213 Mon Sep 17 00:00:00 2001
From: unman <unman@thirdeyesecurity.org>
Date: Thu, 15 May 2025 12:12:18 +0000
Subject: [PATCH 75/87] Minor change to headings on update page.

---
 user/how-to-guides/how-to-update.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/user/how-to-guides/how-to-update.md b/user/how-to-guides/how-to-update.md
index 9c80c0f6..743c7bf1 100644
--- a/user/how-to-guides/how-to-update.md
+++ b/user/how-to-guides/how-to-update.md
@@ -151,7 +151,8 @@ Which one to use depends on the device whose firmware is being updated.
 Firmware updates are important on all systems, but they are especially
 important on AMD client systems.  These do not support loading microcode from
 the OS, so firmware updates are the **only** way to obtain microcode updates.
-## Firmware updates
+
+## Firmware update methods
 
 As of Qubes 4.2, firmware updates can be performed from within Qubes for [fwupd-supported computers](https://fwupd.org/).
 

From caffc06eaf6a87446a5fbad04bf3e2d4124ec9da Mon Sep 17 00:00:00 2001
From: Andrew David Wong <adw@qubes-os.org>
Date: Thu, 15 May 2025 17:06:24 -0700
Subject: [PATCH 76/87] Add Heads certified firmware option for NovaCustom V54
 & V56

---
 user/hardware/certified-hardware/novacustom-v54-series.md | 3 ++-
 user/hardware/certified-hardware/novacustom-v56-series.md | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/user/hardware/certified-hardware/novacustom-v54-series.md b/user/hardware/certified-hardware/novacustom-v54-series.md
index 44db3f56..448da878 100644
--- a/user/hardware/certified-hardware/novacustom-v54-series.md
+++ b/user/hardware/certified-hardware/novacustom-v54-series.md
@@ -47,7 +47,8 @@ The configuration options required for Qubes certification are detailed below.
 
 - Qubes OS does not currently support UEFI secure boot.
 - The option to be kept up to date with firmware updates is merely an email notification service and therefore does not affect certification.
-- The coreboot+Heads option is not currently certified. This option is a separate firmware variant. As such, it requires a separate certification process, which we expect to occur in the future.
+- Certified: coreboot+EDK-II
+- Certified: coreboot+Heads
 - Disabling Intel Management Engine (HAP disabling) does not affect certification.
 
 ### Operating system
diff --git a/user/hardware/certified-hardware/novacustom-v56-series.md b/user/hardware/certified-hardware/novacustom-v56-series.md
index 01eba16b..d743d7ab 100644
--- a/user/hardware/certified-hardware/novacustom-v56-series.md
+++ b/user/hardware/certified-hardware/novacustom-v56-series.md
@@ -47,7 +47,8 @@ The configuration options required for Qubes certification are detailed below.
 
 - Qubes OS does not currently support UEFI secure boot.
 - Keeping up-to-date with firmware updates is merely an email notification service and therefore does not affect certification.
-- The coreboot+Heads option is not currently certified. This option is a separate firmware variant. As such, it requires a separate certification process, which we expect to occur in the future.
+- Certified: coreboot+EDK-II
+- Certified: coreboot+Heads
 - Disabling Intel Management Engine (HAP disabling) does not affect certification.
 
 ### Operating system

From 0ead1b03a1c87f7d826873b0717aa85fa48790b3 Mon Sep 17 00:00:00 2001
From: Ali Mirjamali <ali@mirjamali.com>
Date: Mon, 17 Feb 2025 11:54:18 +0330
Subject: [PATCH 77/87] Add the new notes API documentation

related: https://github.com/QubesOS/qubes-issues/issues/899
---
 developer/services/admin-api.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/developer/services/admin-api.md b/developer/services/admin-api.md
index 74314ed7..f05ee780 100644
--- a/developer/services/admin-api.md
+++ b/developer/services/admin-api.md
@@ -99,6 +99,8 @@ to set the policy using current mechanism.
 | `admin.vm.feature.CheckWithTemplateAndAdminVM` | vm         | feature      | -                                                                   | value                                               |
 | `admin.vm.feature.Remove`                      | vm         | feature      | -                                                                   | -                                                   |
 | `admin.vm.feature.Set`                         | vm         | feature      | value                                                               | -                                                   |
+| `admin.vm.notes.Get`                           | vm         | -            | -                                                                   | notes                                               |
+| `admin.vm.notes.Set`                           | vm         | -            | notes                                                               | -                                                   |
 | `admin.vm.tag.List`                            | vm         | -            | -                                                                   | `<tag>\n`                                           |
 | `admin.vm.tag.Get`                             | vm         | tag          | -                                                                   | `0` or `1`                                          | retcode? |
 | `admin.vm.tag.Remove`                          | vm         | tag          | -                                                                   | -                                                   |

From 2b028834a600ccd15bc5bf9c74ae0105e03cba54 Mon Sep 17 00:00:00 2001
From: Ali Mirjamali <ali@mirjamali.com>
Date: Sun, 18 May 2025 21:42:07 +0330
Subject: [PATCH 78/87] Fixing existing CI/CD issues

---
 user/hardware/certified-hardware/certified-hardware.md | 2 +-
 user/how-to-guides/how-to-install-software.md          | 4 ++--
 user/how-to-guides/how-to-update.md                    | 5 ++---
 user/templates/templates.md                            | 2 +-
 4 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/user/hardware/certified-hardware/certified-hardware.md b/user/hardware/certified-hardware/certified-hardware.md
index 3067080b..e3465e62 100644
--- a/user/hardware/certified-hardware/certified-hardware.md
+++ b/user/hardware/certified-hardware/certified-hardware.md
@@ -36,7 +36,7 @@ The current Qubes-certified models are listed below in reverse chronological ord
 | [NovaCustom](https://novacustom.com/)  | [NV41 Series](https://novacustom.com/product/nv41-series/)                                                                                                             | [Certification details](/doc/certified-hardware/novacustom-nv41-series/)    |
 | [3mdeb](https://3mdeb.com/)            | [Dasharo FidelisGuard Z690](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) | [Certification details](/doc/certified-hardware/dasharo-fidelisguard-z690/) |
 | [Nitrokey](https://www.nitrokey.com/)  | [NitroPad T430](https://shop.nitrokey.com/shop/product/nitropad-t430-119)                                                                                              | [Certification details](/doc/certified-hardware/nitropad-t430/)             |
-| [Nitrokey](https://www.nitrokey.com/)  | [NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67)                                                                                               | [Certification details](/doc/certified-hardware/nitropad-x230/)             |
+| [Nitrokey](https://www.nitrokey.com/)  | <a id="nitropad-x230"></a>[NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67)                                                                                               | [Certification details](/doc/certified-hardware/nitropad-x230/)             |
 | [Insurgo](https://insurgo.ca/)         | [PrivacyBeast X230](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/)                                                         | [Certification details](/doc/certified-hardware/insurgo-privacybeast-x230/) |
 
 ## Become hardware certified
diff --git a/user/how-to-guides/how-to-install-software.md b/user/how-to-guides/how-to-install-software.md
index 87f8af4b..0cc90323 100644
--- a/user/how-to-guides/how-to-install-software.md
+++ b/user/how-to-guides/how-to-install-software.md
@@ -164,8 +164,8 @@ Please see [How to Update](/doc/how-to-update/).
 ## Why don't templates have normal network access?
 
 In order to protect you from performing risky activities in templates, they do
-not have normal network access by default. Instead, templates use an [updates
-proxy](#updates-proxy) which allows you to install and update software using
+not have normal network access by default. Instead, templates use an
+[updates-proxy](#updates-proxy)which allows you to install and update software using
 the distribution's package manager over the proxy connection.
 **The updates proxy is already set up to work automatically out-of-the-box and
 requires no special action from you.**
diff --git a/user/how-to-guides/how-to-update.md b/user/how-to-guides/how-to-update.md
index 743c7bf1..5120701f 100644
--- a/user/how-to-guides/how-to-update.md
+++ b/user/how-to-guides/how-to-update.md
@@ -158,7 +158,7 @@ As of Qubes 4.2, firmware updates can be performed from within Qubes for [fwupd-
 
 ### In dom0
 
-First, ensure that your [UpdateVM](/doc/Software/UpdateVM/)
+First, ensure that your UpdateVM
 contains the `fwupd-qubes-vm` package. This package is installed
 by default for qubes with `qubes-vm-recommended` packages.
 
@@ -198,8 +198,7 @@ Repeat the update process for any additional devices on your computer.
 
 Devices that are attached to non-dom0 qubes can be updated via a graphical tool for `fwupd`, or via the `fwupdmgr` commandline tool.
 
-To update the firmware of offline qubes, use the [Updates
-proxy](/doc/how-to/install/software/#updates-proxy).
+To update the firmware of offline qubes, use the [Updates proxy](/doc/how-to-install-software/#updates-proxy).
 
 ### Computers without fwupd support
 
diff --git a/user/templates/templates.md b/user/templates/templates.md
index cafd062a..392f999e 100644
--- a/user/templates/templates.md
+++ b/user/templates/templates.md
@@ -172,7 +172,7 @@ $ qvm-template list --installed
 
 In either case, issues with template removal may be raised. If an issue is raised, the template will remain installed and a list of concerns displayed. "Global property default_template" requires [switching](#switching) the default_template property to another template. "Template for" can be resolved by [switching](#switching) the dependent qubes' template. Once the issues are addressed, attempt the removal again.
 
-If the template's entry in the Qubes Menu is not removed with its uninstallation, consult the [troubleshooting page](/doc/app-menu-shortcut-troubleshooting/#fixing-shortcuts).
+If the template's entry in the Qubes Menu is not removed with its uninstallation, consult the [troubleshooting page](/doc/app-menu-shortcut-troubleshooting/#what-if-a-removed-application-is-still-in-the-app-menu).
 
 ## Reinstalling
 

From e520e2e5597aa5222b5cd2193998d3dbb7a5991a Mon Sep 17 00:00:00 2001
From: qubedmaiska <qubedmaiska@protonmail.com>
Date: Mon, 19 May 2025 03:46:03 -0400
Subject: [PATCH 79/87] fix for warning display and a url

---
 user/templates/templates.md                 | 2 +-
 user/templates/windows/migrate-to-4-1.md    | 5 ++++-
 user/templates/windows/windows-qubes-4-1.md | 7 +++++--
 3 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/user/templates/templates.md b/user/templates/templates.md
index cafd062a..392f999e 100644
--- a/user/templates/templates.md
+++ b/user/templates/templates.md
@@ -172,7 +172,7 @@ $ qvm-template list --installed
 
 In either case, issues with template removal may be raised. If an issue is raised, the template will remain installed and a list of concerns displayed. "Global property default_template" requires [switching](#switching) the default_template property to another template. "Template for" can be resolved by [switching](#switching) the dependent qubes' template. Once the issues are addressed, attempt the removal again.
 
-If the template's entry in the Qubes Menu is not removed with its uninstallation, consult the [troubleshooting page](/doc/app-menu-shortcut-troubleshooting/#fixing-shortcuts).
+If the template's entry in the Qubes Menu is not removed with its uninstallation, consult the [troubleshooting page](/doc/app-menu-shortcut-troubleshooting/#what-if-a-removed-application-is-still-in-the-app-menu).
 
 ## Reinstalling
 
diff --git a/user/templates/windows/migrate-to-4-1.md b/user/templates/windows/migrate-to-4-1.md
index d80f65d5..e5434c98 100644
--- a/user/templates/windows/migrate-to-4-1.md
+++ b/user/templates/windows/migrate-to-4-1.md
@@ -51,4 +51,7 @@ The PV disk drivers used for migration can be removed after successful installat
 
 After successful uninstallation of the PV disk drivers, the disks will appear as QEMU ATA disks.
 
-:warning: **Caution:** This change may lead Windows to declare that the hardware has changed and that in consequence, the activation is no longer valid, possibly complaining that the use of the software is no longer lawful. It should be possible to reactivate the software if a valid product key is provided.
+<div class="alert alert-warning" role="alert">
+    <i class="fa fa-exclamation-circle"></i>
+    <b>Caution:</b> This change may lead Windows to declare that the hardware has changed and that in consequence, the activation is no longer valid, possibly complaining that the use of the software is no longer lawful. It should be possible to reactivate the software if a valid product key is provided.
+</div>
diff --git a/user/templates/windows/windows-qubes-4-1.md b/user/templates/windows/windows-qubes-4-1.md
index 8908dc33..cbd2b3ba 100644
--- a/user/templates/windows/windows-qubes-4-1.md
+++ b/user/templates/windows/windows-qubes-4-1.md
@@ -154,8 +154,11 @@ These parameters are set for the following reasons:
     -  Close the registry editor and console windows.
     -  You will then return to the setup, which will continue normally and install Windows 11 without TPM 2.0.
    
-    :warning: **Caution:** This temporary patch may cease to work if it so pleases Microsoft sometime. With version 24H2 it is still working.
-    
+<div class="alert alert-warning" role="alert">
+    <i class="fa fa-exclamation-circle"></i>
+    <b>Caution:</b> This temporary patch may cease to work if it so pleases Microsoft sometime. With version 24H2 it is still working.
+</div>
+
     The installation of Windows 11 may require an internet connection to grab a Microsoft ID. Previously, this was true only for the home edition, but since version 24H2, it extends to the Pro edition, too. A workaround to bypass the internet connection requirements of the Windows 11 setup has been published that works for version 21H2 but may be blocked for newer versions:
     
     - When you reach the “Let’s Connect You To A Network” page, type Shift-F10 to open a console window.

From d76402c3ddb935baa1f272bcbf44f1bb4f3a44dd Mon Sep 17 00:00:00 2001
From: lafried <lahuk@protonmail.com>
Date: Wed, 21 May 2025 02:11:50 +0100
Subject: [PATCH 80/87] Fix syntax for dnf5 support

---
 user/templates/fedora/fedora-upgrade.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/user/templates/fedora/fedora-upgrade.md b/user/templates/fedora/fedora-upgrade.md
index 2d5dad90..a34bda37 100644
--- a/user/templates/fedora/fedora-upgrade.md
+++ b/user/templates/fedora/fedora-upgrade.md
@@ -47,7 +47,7 @@ If you wish to install a new, unmodified Fedora template instead of upgrading a
 [user@fedora-<new> ~]$ sudo mkfs.ext4 /dev/xvdi
 [user@fedora-<new> ~]$ sudo mount /dev/xvdi /mnt/removable
 [user@fedora-<new> ~]$ sudo dnf clean all
-[user@fedora-<new> ~]$ sudo dnf --releasever=<new> --setopt=cachedir=/mnt/removable --best --allowerasing distro-sync
+[user@fedora-<new> ~]$ sudo dnf --releasever=<new> --setopt=cachedir=/mnt/removable --best distro-sync --allowerasing
 [user@dom0 ~]$ qvm-shutdown fedora-<new>
 [user@dom0 ~]$ sudo losetup -d $dev
 [user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
@@ -116,7 +116,7 @@ The same general procedure may be used to upgrade any template based on the stan
         [user@fedora-<new> ~]$ sudo mkfs.ext4 /dev/xvdi
         [user@fedora-<new> ~]$ sudo mount /dev/xvdi /mnt/removable
         [user@fedora-<new> ~]$ sudo dnf clean all
-        [user@fedora-<new> ~]$ sudo dnf --releasever=<new> --setopt=cachedir=/mnt/removable --best --allowerasing distro-sync
+        [user@fedora-<new> ~]$ sudo dnf --releasever=<new> --setopt=cachedir=/mnt/removable --best distro-sync --allowerasing
         ```
 
        If this attempt is successful, proceed to step 4.
@@ -185,7 +185,7 @@ The same general procedure may be used to upgrade any template based on the stan
 [user@dom0 ~]$ qvm-clone fedora-<old>-minimal fedora-<new>-minimal
 [user@dom0 ~]$ qvm-run -u root -a fedora-<new>-minimal xterm
 [root@fedora-<new>-minimal ~]# dnf clean all
-[user@fedora-<new>-minimal ~]# dnf --releasever=<new> --best --allowerasing distro-sync
+[user@fedora-<new>-minimal ~]# dnf --releasever=<new> --best distro-sync --allowerasing
 [user@fedora-<new>-minimal ~]# fstrim -v /
 [user@dom0 ~]$ qvm-features fedora-<new>-minimal template-name fedora-<new>
 ```

From 34144a1620029ead19314853c6f3897f3ea3dd79 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sol=C3=A8ne=20Rapenne?= <solene@perso.pw>
Date: Sat, 24 May 2025 15:05:14 +0200
Subject: [PATCH 81/87] doc: make clear that sys-gui-gpu is not meant for
 improving performance

---
 user/advanced-topics/gui-domain.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/user/advanced-topics/gui-domain.md b/user/advanced-topics/gui-domain.md
index 6c18d51f..ae2b21b5 100644
--- a/user/advanced-topics/gui-domain.md
+++ b/user/advanced-topics/gui-domain.md
@@ -45,6 +45,8 @@ At this point, you need to shutdown all your running qubes as the `default_guivm
 
 Here, we describe how to setup `sys-gui-gpu` which is a GUI domain with *GPU passthrough* in [GUI domain](/news/2020/03/18/gui-domain/#gpu-passthrough-the-perfect-world-desktop-solution).
 
+> Note: the purpose of `sys-gui-gpu` is to improve Qubes OS security by detaching the GPU from dom0, this is not intended to improve GPU related performance within qubes, and this will not improve performance.
+
 [![sys-gui-gpu](/attachment/posts/guivm-gpu.png)](/attachment/posts/guivm-gpu.png)
 
 In `dom0`, enable the formula for `sys-gui-gpu` with pillar data:

From f72ad83ffbaf24203b5c15856bca051573cbe020 Mon Sep 17 00:00:00 2001
From: unman <unman@thirdeyesecurity.org>
Date: Sun, 25 May 2025 01:05:24 +0000
Subject: [PATCH 82/87] Edit secondary storage page for clarity

---
 .../secondary-storage.md                      | 40 ++++++++++---------
 1 file changed, 21 insertions(+), 19 deletions(-)

diff --git a/user/advanced-configuration/secondary-storage.md b/user/advanced-configuration/secondary-storage.md
index eedf2526..5874e4b3 100644
--- a/user/advanced-configuration/secondary-storage.md
+++ b/user/advanced-configuration/secondary-storage.md
@@ -10,35 +10,38 @@ ref: 187
 title: Secondary Storage
 ---
 
-# Storing AppVMs on Secondary Drives
+# Storing qubes on Secondary Drives
 
 Suppose you have a fast but small primary SSD and a large but slow secondary HDD.
-You want to store a subset of your AppVMs on the HDD.
+You may want to store a subset of your qubes on the HDD.
+Or if you install a second SSD, you may want to use *that* for storage of some qubes.
+This page explains how to use that second drive.
+
 
 ## Instructions
 
 Qubes 4.0 is more flexible than earlier versions about placing different VMs on different disks.
-For example, you can keep templates on one disk and AppVMs on another, without messy symlinks.
+For example, you can keep templates on one disk and qubes on another, without messy symlinks.
 
 You can query qvm-pool to list available storage drivers:
 
 ``` shell_session
 qvm-pool --help-drivers
 ```
-qvm-pool driver explaination:
-```shell_session
+qvm-pool driver explanation:
+```
 <file> refers to using a simple file for image storage and lacks a few features.
 <file-reflink> refers to storing images on a filesystem supporting copy on write.
 <linux-kernel> refers to a directory holding kernel images.
 <lvm_thin> refers to LVM managed pools.
 ```
-In theory, you can still use file-based disk images ("file" pool driver), but it lacks some features such as you won't be able to do backups without shutting down the qube.
+In theory, you can still use file-based disk images ("file" pool driver), but they will lack some features: for example, you won't be able to do backups without shutting down the qube.
 
-Additionnal storage can also be added on a Btrfs filesystem. A unique feature of Btrfs over LVM is that data can be compressed transparently. The subvolume can also be backuped using snapshots for an additionnal layer of protection; Btrfs supports differents level of redundancy; it has parity checksum; it is able to be expanded/shrinked. Starting/stoping a VM has less impact and less chances of causing slowdown of the system as some have noted with LVM. Revelant information for general btrfs configuration will be provided after LVM section.
+Additional storage can also be added on a Btrfs filesystem. A unique feature of Btrfs is that data can be compressed transparently. The subvolume can also be backed up using snapshots for an additional layer of protection; Btrfs supports differents level of redundancy; it has parity checksum; Btrfs volumes can be expanded or shrunk. Starting or stopping a VM has less impact and less chance of causing slowdown of the system as some users have noted with LVM. Relevant information for general btrfs configuration will be provided after the section on LVM storage.
 
 ### LVM storage
 
-These steps assume you have already created a separate [volume group](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/logical_volume_manager_administration/vg_admin#VG_create) and [thin pool](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/logical_volume_manager_administration/thinly_provisioned_volume_creation) (not thin volume) for your HDD.
+These steps assume you have already created a separate [volume group](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/logical_volume_manager_administration/vg_admin#VG_create) and [thin pool](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/logical_volume_manager_administration/thinly_provisioned_volume_creation) (not thin volume) for your second drive..
 See also [this example](https://www.linux.com/blog/how-full-encrypt-your-linux-system-lvm-luks) if you would like to create an encrypted LVM pool (but note you can use a single logical volume if preferred, and to use the `-T` option on `lvcreate` to specify it is thin). You can find the commands for this example applied to Qubes at the bottom of this R4.0 section.
 
 First, collect some information in a dom0 terminal:
@@ -48,9 +51,9 @@ sudo pvs
 sudo lvs
 ```
 
-Take note of the VG and thin pool names for your HDD, then register it with Qubes:
+Take note of the VG and thin pool names for your second drive., then register it with Qubes:
 
-```shell_session
+```
 # <pool_name> is a freely chosen pool name
 # <vg_name> is LVM volume group name
 # <thin_pool_name> is LVM thin pool name
@@ -58,10 +61,10 @@ qvm-pool --add <pool_name> lvm_thin -o volume_group=<vg_name>,thin_pool=<thin_po
 ```
 
 ### BTRFS storage
-Theses steps assume you have already created a separate Btrfs filesystem for your HDD, that it is encrypted with LUKS and it is mounted. It is recommended to use a subvolume as it enables compression and excess storage can be use for other things.
+Theses steps assume you have already created a separate Btrfs filesystem for your second drive., that it is encrypted with LUKS and it is mounted. It is recommended to use a subvolume as it enables compression and excess storage can be use for other things.
 
 
-It is possible to use already available Btrfs storage if it is configured. In dom0, available Btrfs storage can be displayed using:
+It is possible to use an existing Btrfs storage if it is configured. In dom0, available Btrfs storage can be displayed using:
 ```shell_session
 mount -t btrfs
 btrfs show filesystem
@@ -89,20 +92,19 @@ qvm-clone -P <pool_name> <sourceVMname> <cloneVMname>
 qvm-remove <sourceVMname>
 ```
 
-If that was a template, or other qube referenced elsewhere (NetVM or such), you will need to adjust those references manually after moving.
+If that was a template, or other qube referenced elsewhere (netVM or such), you will need to adjust those references manually after moving.
 For example:
 
 ```shell_session
 qvm-prefs <appvmname_based_on_old_template> template <new_template_name>
 ```
 
-#### Example HDD setup
+#### Example setup of second drive. 
 
-Assuming the secondary hard disk is at /dev/sdb (it will be completely erased), you can set it up for encryption by doing in a dom0 terminal (use the same passphrase as the main Qubes disk to avoid a second password prompt at boot):
+Assuming the secondary hard disk is at /dev/sdb , you can encrypt the drive as follows. Note that the drive contents will be completely erased,  In a dom0 terminal run this command - use the same passphrase as the main Qubes disk to avoid a second password prompt at boot:
 
 ```shell_session
 sudo cryptsetup luksFormat --hash=sha512 --key-size=512 --cipher=aes-xts-plain64 --verify-passphrase /dev/sdb
-sudo blkid /dev/sdb
 ```
 
 Note the device's UUID (in this example "b209..."), we will use it as its luks name for auto-mounting at boot, by doing:
@@ -111,13 +113,13 @@ Note the device's UUID (in this example "b209..."), we will use it as its luks n
 sudo nano /etc/crypttab
 ```
 
-And adding this line (change both "b209..." for your device's UUID from blkid) to crypttab:
+And adding this line to crypttab (replacing both "b209..." entries with your device's UUID taken from blkid) :
 
 ```shell_session
 luks-b20975aa-8318-433d-8508-6c23982c6cde UUID=b20975aa-8318-433d-8508-6c23982c6cde none
 ```
 
-Reboot the computer so the new luks device appears at /dev/mapper/luks-b209... and we can then create its pool, by doing this on a dom0 terminal (substitute the b209... UUIDs with yours):
+Reboot the computer so the new luks device appears at /dev/mapper/luks-b209...  You can then create the new pool by running this command in a dom0 terminal (substitute the b209... UUIDs with your UID):
 
 ##### For LVM
 
@@ -180,7 +182,7 @@ Finally we will tell Qubes to add a new pool on the just created Btrfs subvolume
 qvm-pool --add poolhd0_qubes file-reflink -o dir_path=/var/lib/qubes_newpool,revisions_to_keep=2
 ```
 
-By default VMs will be created on the main Qubes disk (i.e. a small SSD), to create them on this secondary HDD do the following on a dom0 terminal:
+By default VMs will be created on the main Qubes disk (i.e. a small SSD), to create them on this secondary drive do the following on a dom0 terminal:
 
 ```shell_session
 qvm-create -P poolhd0_qubes --label red unstrusted-hdd

From 684a7cee24065e0b3a7bbc50e73961076987cd53 Mon Sep 17 00:00:00 2001
From: unman <unman@thirdeyesecurity.org>
Date: Sun, 25 May 2025 01:17:06 +0000
Subject: [PATCH 83/87] Minor edits to Secondary Storage page

---
 user/advanced-topics/secondary-storage.md | 10 +---------
 1 file changed, 1 insertion(+), 9 deletions(-)

diff --git a/user/advanced-topics/secondary-storage.md b/user/advanced-topics/secondary-storage.md
index a0ff1598..af4b689c 100644
--- a/user/advanced-topics/secondary-storage.md
+++ b/user/advanced-topics/secondary-storage.md
@@ -110,13 +110,7 @@ sudo blkid /dev/sdb
 
 (The `--sector-size=512` argument can sometimes work around an incompatibility of storage hardware with LVM thin pools on Qubes. If this does not apply to your hardware, the argument will make no difference.)
 
-Note the device's UUID (in this example "b209..."), we will use it as its luks name for auto-mounting at boot, by doing:
-
-```shell_session
-sudo nano /etc/crypttab
-```
-
-And adding this line to crypttab (replacing both "b209..." entries with your device's UUID taken from blkid) :
+Note the device's UUID (in this example "b209..."), we will use it as its luks name for auto-mounting at boot, by editing `/etc/crypttab`, and adding this line to crypttab (replacing both "b209..." entries with your device's UUID taken from blkid) :
 
 ```shell_session
 luks-b20975aa-8318-433d-8508-6c23982c6cde UUID=b20975aa-8318-433d-8508-6c23982c6cde none
@@ -190,11 +184,9 @@ By default VMs will be created on the main Qubes disk (i.e. a small SSD), to cre
 ```shell_session
 qvm-create -P poolhd0_qubes --label red unstrusted-hdd
 ```
-=======
 
 Verify that corresponding lines were added to /etc/fstab and /etc/cryptab to enable auto mounting of the new pool.
 
 
 [Qubes Backup]: /doc/BackupRestore/
 [TemplateVM]: /doc/Templates/
->>>>>>> pr-1130:user/advanced-configuration/secondary-storage.md

From 5b5a4ebd9b8c839f9f1cf373667e4ba67623ab6d Mon Sep 17 00:00:00 2001
From: unman <unman@thirdeyesecurity.org>
Date: Tue, 27 May 2025 12:09:11 +0000
Subject: [PATCH 84/87] Update Debian and Fedora template pages.

---
 user/templates/debian/debian.md | 15 ++++++---------
 user/templates/fedora/fedora.md | 10 ++++------
 2 files changed, 10 insertions(+), 15 deletions(-)

diff --git a/user/templates/debian/debian.md b/user/templates/debian/debian.md
index c070791d..622d3e6d 100644
--- a/user/templates/debian/debian.md
+++ b/user/templates/debian/debian.md
@@ -12,19 +12,18 @@ title: Debian templates
 ---
 
 The Debian [template](/doc/templates/) is an officially [supported](/doc/supported-releases/#templates) template in Qubes OS.
-This page is about the standard (or "full") Debian template.
+The Current version is Debian 12 ("bookworm"). It is available in 3 versions - `debian-12`, a standard template; `debian-12-xfce`, a larger template with more installed applications, selected for [Xfce](/doc/templates/xfce/); `debian-12-minimal`.
+This page is about the "full" templates.
 For the minimal version, please see the [Minimal templates](/doc/templates/minimal/) page.
-There is also a [Qubes page on the Debian Wiki](https://wiki.debian.org/Qubes).
 
 ## Installing
 
-To [install](/doc/templates/#installing) a specific Debian template that is not currently installed in your system, use the following command in dom0:
+To [install](/doc/templates/#installing) a specific Debian template that is not currently installed in your system, use the Qubes Template Manager, or use the following command in a dom0 terminal:
 
 ```
-$ sudo qubes-dom0-update qubes-template-debian-XX
+$ qvm-template install XX
 ```
-
-   (Replace `XX` with the Debian version number of the template you wish to install.)
+   (Replace `XX` with the name of the template you wish to install.)
 
 To reinstall a Debian template that is already installed in your system, see [How to Reinstall a template](/doc/reinstall-template/).
 
@@ -100,10 +99,8 @@ Don't forget to make the file executable.
 
 ### Unattended Upgrades
 
-Some users have noticed that on upgrading to Stretch, the `unattended-upgrade` package is installed.
-
+Some users have noticed that on upgrading Debian templates, the `unattended-upgrade` package is installed.
 This package is pulled in as part of a Recommend chain, and can be purged.
-
 The lesson is that you should carefully look at what is being installed to your system, particularly if you run `dist-upgrade`.
 
 ### Package installation errors in Qubes 4.0
diff --git a/user/templates/fedora/fedora.md b/user/templates/fedora/fedora.md
index eefa7fac..baffd3d4 100644
--- a/user/templates/fedora/fedora.md
+++ b/user/templates/fedora/fedora.md
@@ -6,17 +6,15 @@ ref: 136
 title: Fedora templates
 ---
 
-The Fedora [template](/doc/templates/) is the default template in Qubes OS. This page is about the standard (or "full") Fedora template. For the minimal and Xfce versions, please see the [Minimal templates](/doc/templates/minimal/) and [Xfce templates](/doc/templates/xfce/) pages.
+The Fedora [template](/doc/templates/) is the default template in Qubes OS. The current version is Fedora 41. This page is about the standard (or "full") Fedora template. For the minimal and Xfce versions, please see the [Minimal templates](/doc/templates/minimal/) and [Xfce templates](/doc/templates/xfce/) pages.
 
 ## Installing
 
-To [install](/doc/templates/#installing) a specific Fedora template that is not currently installed in your system, use the following command in dom0:
-
+To [install](/doc/templates/#installing) a specific Fedora template that is not currently installed in your system, use the Qubes Template Manager, or use the following command in a dom0 terminal:
 ```
-$ sudo qubes-dom0-update qubes-template-fedora-XX
+$ qvm-template install XX 
 ```
-
-   (Replace `XX` with the Fedora version number of the template you wish to install.)
+   (Replace `XX` with the name of the Fedora template you wish to install.)
 
 To reinstall a Fedora template that is already installed in your system, see [How to Reinstall a template](/doc/reinstall-template/).
 

From 473fb5d3236e20c203e5e274e4979d88b08120bb Mon Sep 17 00:00:00 2001
From: unman <unman@thirdeyesecurity.org>
Date: Tue, 27 May 2025 13:04:44 +0000
Subject: [PATCH 85/87] Update Templates page. Includes some changes based on
 #1206

---
 user/templates/templates.md | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/user/templates/templates.md b/user/templates/templates.md
index 392f999e..31ca18f8 100644
--- a/user/templates/templates.md
+++ b/user/templates/templates.md
@@ -13,10 +13,15 @@ title: Templates
 
 In [Getting Started](/doc/getting-started/), we covered the distinction
 in Qubes OS between where you *install* your software and where you *run* your
-software. Your software is installed in [templates](/doc/glossary/#template).
-Each template shares its root filesystem (i.e., all of its programs and system
-files) with all the qubes based on it. [App qubes](/doc/glossary/#app-qube) are
-where you run your software and store your data.
+software. Software that you use in most everyday tasks, is installed within [templates](/doc/glossary/#template).
+When using Qubes OS, you normally work in [app qubes](/doc/glossary/#app-qube).
+App qubes are based on a *template* qube (or more simply, just *a template*).
+They inherit most of the ["root filesystem"](https://opensource.com/life/16/10/introduction-linux-filesystems), from the template.
+Changes you make to the root filesystem are not written back to the template: if you install an application in an app qube it will disappear when you shut down the qube. (You may be able to work round this by using Flatpak or snap packages, which install to the user's home directory.)
+The user home directory *is* specific to the app qube, and changes there are kept.
+There is a full explanation of this [below](#inheritance-and-persistence).
+
+If you use a [Standalone](/doc/glossary/#standalone), the **whole filesystem** is specific to the standalone, and every change you make will be kept after shutdown.
 
 The template system has significant benefits:
 
@@ -37,7 +42,7 @@ The template system has significant benefits:
 
 An important side effect of this system is that any software installed in an
 app qube (rather than in the template on which it is based) will disappear
-after the app qube reboots (see [Inheritance and
+when the app qube shuts down (see [Inheritance and
 Persistence](#inheritance-and-persistence)). For this reason, we recommend
 installing most of your software in templates, not app qubes.
 
@@ -61,6 +66,9 @@ exactly the same source code as we publish.
 * [Fedora Xfce](/doc/templates/xfce)
 * [Debian](/doc/templates/debian/)
 * [Debian Minimal](/doc/templates/minimal/)
+* [Debian Xfce](/doc/templates/xfce)
+
+You can see the current supported versions [here](/doc/supported-releases#templates).
 
 ## Community
 
@@ -109,16 +117,16 @@ when you wish to install a fresh template from the Qubes repositories, e.g.:
 * When you suspect your template has been compromised.
 * When you have made modifications to your template that you no longer want.
 
-You can use a command line tool - `qvm-template` - or a GUI - `qvm-template-gui`.
+You can manage your templates using the `Qubes Template Manager`, a GUI tool available from the Qube menu.
+You can also use a command line tool in dom0 - `qvm-template`.
 
 At the command line in dom0, `qvm-template list --available` will show available templates. To install a template, use:
 ```
 $ qvm-template install  <template_name>
 ```
-
 You can also use `qvm-template` to upgrade or reinstall templates.
 
-Repo definitions are stored in `/etc/qubes/repo-templates` and associated keys in `/etc/qubes/repo-templates/keys`.  
+Repository (repo) definitions are stored in dom0 in `/etc/qubes/repo-templates` and associated keys in `/etc/qubes/repo-templates/keys`.
 There are additional repos for testing releases and community templates.
 To temporarily enable any of these repos, use the `--enablerepo=<repo-name>` option. E.g. :
 ```

From 117b9ee6a378a9211db5a35cbae40a0cbda4b181 Mon Sep 17 00:00:00 2001
From: Andrew David Wong <adw@qubes-os.org>
Date: Thu, 5 Jun 2025 05:45:51 -0700
Subject: [PATCH 86/87] Remove Joanna from list of security team members

Thanks to oli from the Qubes OS Forum for pointing this out:
https://forum.qubes-os.org/t/qubes-canary-043/34234/2

Full explanation:
https://forum.qubes-os.org/t/qubes-canary-043/34234/3
---
 project-security/security.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/project-security/security.md b/project-security/security.md
index a8b325d8..bf8cff50 100644
--- a/project-security/security.md
+++ b/project-security/security.md
@@ -93,4 +93,3 @@ of the actions listed above.
 
 - [Marek Marczykowski-Górecki](/team/#marek-marczykowski-górecki)
 - [Simon Gaiser (aka HW42)](/team/#simon-gaiser-aka-hw42)
-- [Joanna Rutkowska](/team/#joanna-rutkowska) ([emeritus, canaries only](/news/2018/11/05/qubes-security-team-update/))

From b9a4429552199e2a07f369800514b3edbe5ac153 Mon Sep 17 00:00:00 2001
From: unman <unman@thirdeyesecurity.org>
Date: Thu, 5 Jun 2025 15:18:41 +0000
Subject: [PATCH 87/87] Update KDE page with more detailed information post
 install

---
 user/advanced-topics/kde.md | 40 +++++++++++++++++++++++++++----------
 1 file changed, 29 insertions(+), 11 deletions(-)

diff --git a/user/advanced-topics/kde.md b/user/advanced-topics/kde.md
index c2553f7f..715f928e 100644
--- a/user/advanced-topics/kde.md
+++ b/user/advanced-topics/kde.md
@@ -8,17 +8,37 @@ ref: 176
 title: KDE (desktop environment)
 ---
 
-Installation
-------------
+## Installation
 
 Prior to R3.2, KDE was the default desktop environment in Qubes. Beginning with
-R3.2, however, [XFCE is the new default desktop environment](/doc/releases/3.2/release-notes/). Nonetheless, it is
-still possible to install KDE by issuing this command in dom0:
-
+R3.2, however, [XFCE is the new default desktop environment](/doc/releases/3.2/release-notes/).
+Nonetheless, it is still possible to install KDE by issuing this command in dom0:
 ```shell_session
 $ sudo qubes-dom0-update kde-settings-qubes
 ```
+You may notice some warnings and errors in the installation - it is safe to ignore these.
 
+After the installation is complete log out.
+At the top of the log in screen is a small icon with *X* on it - if you click on it you will see choices between Xfce and
+Plasma. Select the Plasma(X11) option, and log in - you will see that Plasma (the KDE desktop environment) loads.
+
+KDE is very customisable, and there is a range of widgets to use.
+If you want to use the Menu widget, then you must edit `/etc/X11/xinit/xinitrc.d/55xfce-qubes.sh` as follows:
+```
+#!/usr/bin/sh
+
+# Use Qubes provided menu instead of default XFCE one
+if [ "$XDG_SESSION_DESKTOP" = "KDE" ]; then
+XDG_MENU_PREFIX="kf5-"
+else
+XDG_MENU_PREFIX="qubes-"
+fi
+export XDG_MENU_PREFIX
+```
+This allows you to edit the menu as you will. When editing the Menu *DO NOT use the option under "Edit->Restore to System Menu"*
+
+
+### Login manager
 You can also change your default login manager (lightdm) to the new KDE default: sddm
 
 * first you need to edit the `/etc/sddm.conf` to make sure if the custom X parameter is set according to Qubes needs:
@@ -44,8 +64,8 @@ You can also change your default login manager (lightdm) to the new KDE default:
 
 If you encounter performance issues with KDE, try switching back to LightDM.
 
-Window Management
------------------
+
+## Window Management
 
 You can set each window's position and size like this:
 
@@ -67,14 +87,12 @@ You can also use `kstart` to control virtual desktop placement like this:
   kstart --desktop 3 --windowclass <vm_name> -q --tray -a <vm_name> '<run_program_command>'
 ~~~
 
-(Replace "3" with whichever virtual desktop you want the window to be
-on.)
+(Replace "3" with whichever virtual desktop you want the window to be on.)
 
 This can be useful for creating a simple shell script which will set up your
 workspace the way you like.
 
-Removal
-------------
+## Removal
 
 If you decide to remove KDE do **not** use `dnf remove @kde-desktop-qubes`. You will almost certainly break your system.