Remove obsolete EFI config (xen.cfg) section

Grub is used for both for a long time already

developer/building/qubes-builder-details.md

@@ -14,7 +14,7 @@ title: Qubes builder details
 <div class="alert alert-warning" role="alert">
   <i class="fa fa-exclamation-circle"></i>
   <b>Note:</b> This information concerns the old Qubes builder (v1). It supports
-  only building Qubes 4.1 or earlier.<br>The build process has been completely rewritten in <a href="https://github.com/QubesOS/qubes-builderv2/">qubes-builder v2</a>. This can be be used for building Qubes R4.1 and later, and all related components.</div>
+  only building Qubes 4.1 or earlier.<br>The build process has been completely rewritten in <a href="https://github.com/QubesOS/qubes-builderv2/">qubes-builder v2</a>. This can be used for building Qubes R4.1 and later, and all related components.</div>
 
 Components Makefile.builder file
 --------------------------------

developer/building/qubes-builder.md

@@ -13,7 +13,7 @@ title: Qubes builder
 <div class="alert alert-warning" role="alert">
   <i class="fa fa-exclamation-circle"></i>
   <b>Note:</b> These instructions concern the older Qubes builder (v1). It supports
-  only building Qubes 4.1 or earlier.<br>The build process has been completely rewritten in <a href="https://github.com/QubesOS/qubes-builderv2/">qubes-builder v2</a>. This can be be used for building Qubes R4.1 and later, and all related components.
+  only building Qubes 4.1 or earlier.<br>The build process has been completely rewritten in <a href="https://github.com/QubesOS/qubes-builderv2/">qubes-builder v2</a>. This can be used for building Qubes R4.1 and later, and all related components.
 </div>
 
 **Note: See [ISO building instructions](/doc/qubes-iso-building/) for a streamlined overview on how to use the build system.**

developer/building/qubes-iso-building.md

@@ -15,7 +15,7 @@ title: Qubes ISO building
 <div class="alert alert-warning" role="alert">
   <i class="fa fa-exclamation-circle"></i>
   <b>Note:</b> These instructions concern the older Qubes builder (v1). It supports
-  only building Qubes 4.1 or earlier.<br>The build process has been completely rewritten in <a href="https://github.com/QubesOS/qubes-builderv2/">qubes-builder v2</a>. This can be be used for building Qubes R4.1 and later, and all related components.
+  only building Qubes 4.1 or earlier.<br>The build process has been completely rewritten in <a href="https://github.com/QubesOS/qubes-builderv2/">qubes-builder v2</a>. This can be used for building Qubes R4.1 and later, and all related components.
 </div>
 
 Build Environment

developer/debugging/vm-interface.md

@@ -28,7 +28,7 @@ Qubes VM have some settings set by dom0 based on VM settings. There are multiple
   - `full` - all disks
   - `rw-only` - only `/rw` disk
   - `none` - none
-- `/qubes-timezone - name of timezone based on dom0 timezone. For example `Europe/Warsaw`
+- `/qubes-timezone` - name of timezone based on dom0 timezone. For example `Europe/Warsaw`
 - `/qubes-keyboard` (deprecated in R4.1) - keyboard layout based on dom0 layout. Its syntax is suitable for `xkbcomp` command (after expanding escape sequences like `\n` or `\t`). This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). This entry is created as part of gui-daemon initialization (so not available when gui-daemon disabled, or not started yet).
 - `/keyboard-layout` - keyboard layout based on GuiVM layout. Its syntax can be `layout+variant+options`, `layout+variant`, `layout++options` or simply `layout`. For example, `fr+oss`, `pl++compose:caps` or `fr`. This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does).
 - `/qubes-debug-mode` - flag whether VM has debug mode enabled (qvm-prefs setting). One of `1`, `0`

developer/debugging/windows-debugging.md

@@ -10,253 +10,80 @@ ref: 50
 title: Windows debugging
 ---
 
-Debugging Windows code can be tricky in a virtualized environment. The guide below assumes Xen hypervisor and Windows 7 VMs.
+Debugging Windows code can be tricky in a virtualized environment. The guide below assumes Qubes 4.2 and Windows 7 or later VMs.
 
 User-mode debugging is usually straightforward if it can be done on one machine. Just duplicate your normal debugging environment in the VM.
 
-Things get complicated if you need to perform kernel debugging or troubleshoot problems that only manifest on system boot, user logoff or similar. For that you need two Windows VMs: the *host* and the *target*. The *host* will contain [WinDbg](https://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) installation, your source code and private symbols. The *target* will run the code being debugged. Both will be linked by virtual serial ports.
+Things get complicated if you need to perform kernel debugging or troubleshoot problems that only manifest on system boot, user logoff or similar. For that you need two Windows VMs: the *host* and the *target*. The *host* will contain the debugger, your source code and private symbols. The *target* will run the code being debugged. We will use kernel debugging over network which is supported from Windows 7 onwards. The main caveat is that Windows kernel supports only specific network adapters for this, and the default one in Qubes won't work.
 
-- First, you need to prepare separate copies of both *target* and *host* VM configuration files with some changes. Copy the files from **/var/lib/qubes/appvms/vmname/vmname.conf** to some convenient location, let's call them **host.conf** and **target.conf**.
-- In both copied files add the following line at the end: `serial = 'pty'`. This will make Xen connect VM's serial ports to dom0's ptys.
-- From now on you need to start both VMs like this: `qvm-start --custom-config=/your/edited/host.conf host`
-- To connect both VM serial ports together you will either need [socat](http://www.dest-unreach.org/socat/) or a custom utility described later.
-- To determine which dom0 pty corresponds to VM's serial port you need to read xenstore, example script below:
+## Important note
 
-```bash
-#!/bin/sh
+- Do not install Xen network PV drivers in the target VM. Network kernel debugging needs a specific type of NIC or it won't work, the network PV drivers interfere with that.
 
-id1=$(xl domid "$1-dm")
-tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty)
-echo $tty1
-```
+- If you have kernel debugging active when the Xen PV drivers are being installed, make sure to disable it before rebooting (`bcdedit /set debug off`). You can re-enable debugging after the reboot. The OS won't boot otherwise. I'm not sure what's the exact cause. I know that busparams for the debugging NIC change when PV drivers are installed (see later), but even changing that accordingly in the debug settings doesn't help -- so it's best to disable debug for this one reboot.
 
-Pass it a running VM name and it will output the corresponding pty name.
+## Modifying the NIC of the target VM
 
-- To connect both ptys you can use [socat](http://www.dest-unreach.org/socat/) like that:
+You will need to create a custom libvirt config for the target VM. See [the documentation](https://dev.qubes-os.org/projects/core-admin/en/latest/libvirt.html) for overview of how libvirt templates work in Qubes. The following assumes the target VM is named `target-vm`.
 
-```bash
-#!/bin/sh
+- Edit `/usr/share/qubes/templates/libvirt/xen.xml` to prepare our custom config to override just the NIC part of the global template:
+  - add `{% raw %}{% block network %}{% endraw %}` before `{% raw %}{% if vm.netvm %}{% endraw %}`
+  - add `{% raw %}{% endblock %}{% endraw %}` after the matching `{% raw %}{% endif %}{% endraw %}`
+- Copy `/usr/share/qubes/templates/libvirt/devices/net.xml` to `/etc/qubes/templates/libvirt/xen/by-name/target-vm.xml`.
+- Add `<model type='e1000'/>` to the `<interface>` section.
+- Enclose everything within `{% raw %}{% block network %}{% endraw %}` + `{% raw %}{% endblock %}{% endraw %}`.
+- Add `{% raw %}{% extends 'libvirt/xen.xml' %}{% endraw %}` at the start.
+- The final `target-vm.xml` should look something like this:
 
-id1=$(xl domid "$1-dm")
-id2=$(xl domid "$2-dm")
-tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty)
-tty2=$(xenstore-read /local/domain/${id2}/device/console/3/tty)
-socat $tty1,raw $tty2,raw
-```
+~~~
+{% raw %}
+{% extends 'libvirt/xen.xml' %}
+{% block network %}
+   <interface type='ethernet'>
+      <mac address="{{ vm.mac }}" />
+      <ip address="{{ vm.ip }}" />
+      <backenddomain name="{{ vm.netvm.name }}" />
+      <script path='vif-route-qubes' />
+      <model type='e1000' />
+   </interface>
+{% endblock %}
+{% endraw %}
+~~~
 
-...but there is a catch. Xen seems to process the traffic that goes through serial ports and changes all **0x0a** bytes into **0x0d, 0x0a** pairs (newline conversion). I didn't find a way to turn that off (setting ptys to raw mode didn't change anything) and it's not mentioned anywhere on the Internet, so maybe it's something on my system. If the above script works for you then you don't need anything more in dom0.
+- Start `target-vm` and verify in the device manager that a "Intel PRO/1000 MT" adapter is present.
 
-- On the *target* system, run `bcdedit /set debug on` on the console to turn on kernel debugging. It defaults to the first serial port.
-- On the *host* system, install [WinDbg](https://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) and start the kernel debug (Ctrl-K), choose **com1** as the debug port.
-- Reboot the *target* VM.
-- Run the above shell script in dom0.
-- If everything is fine you should see the proper kernel debugging output in WinDbg. However, if you see something like that:
+## Host and target preparation
+
+- On `host-vm` you will need WinDbg, which is a part of the [Windows SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/).
+- Copy the `Debuggers` directory from Windows SDK to `target-vm`.
+- In both `host-vm` and `target-vm` switch the windows network to private (it tends to be public by default).
+- Either turn off the windows firewall or enable all ICMP-in rules in both VMs.
+- In `firewall-vm` edit `/rw/config/qubes-firewall-user-script` to connect both Windows VMs, add:
+  - `iptables -I FORWARD 2 -s <target-vm-ip> -d <host-vm-ip> -j ACCEPT`
+  - `iptables -I FORWARD 2 -s <host-vm-ip> -d <target-vm-ip> -j ACCEPT`
+  - run `/rw/config/qubes-firewall-user-script` so the changes take effect immediately
+- Make sure both VMs can ping each other.
+- In `target-vm`:
+  - start elevated `cmd` session
+  - `cd sdk\Debuggers\x64`
+  - `kdnet` should show that the NIC is supported, note the busparams:
+
+    ~~~
+    Network debugging is supported on the following NICs:
+    busparams=0.6.0, Intel(R) PRO/1000 MT Network Connection, KDNET is running on this NIC.
+    ~~~
+
+  - `bcdedit /debug on`
+  - `bcdedit /dbgsettings net hostip:<host-vm-ip> port:50000 key:1.1.1.1` (you can customize the key)
+  - `bcdedit /set "{dbgsettings}" busparams x.y.z` (use the busparams `kdnet` has shown earlier)
+- In `host-vm` start WinDbg: `windbg -k net:port=50000,key=1.1.1.1`. It will listen for target's connection.
+- Reboot `target-vm`, debugging should start:
 
     ~~~
-    Opened \\.\com1
     Waiting to reconnect...
-    Connected to Windows 7 7601 x64 target at (Wed Mar 19 20:35:43.262 2014 (UTC + 1:00)), ptr64 TRUE
-    Kernel Debugger connection established.
-    Symbol search path is: srv*c:\symbols*https://msdl.microsoft.com/download/symbols
-    Executable search path is:
-    ... Retry sending the same data packet for 64 times.
-    The transport connection between host kernel debugger and target Windows seems lost.
-    please try resync with target, recycle the host debugger, or reboot the target Windows.
-    Unable to read KTHREAD address fffff8000281ccc0
-    **************************************************************************
-    Unable to read debugger data block header
-    **************************************************************************
-    Unable to read KTHREAD address fffff8000281ccc0
-    Unable to read PsLoadedModuleList
-    Unable to read KTHREAD address fffff8000281ccc0
-    **************************************************************************
-    Unable to read debugger data block header
-    **************************************************************************
+    Connected to target 10.137.0.19 on port 50000 on local IP 10.137.0.20.
+    You can get the target MAC address by running .kdtargetmac command.
+    Connected to Windows 10 19041 x64 target at (Thu Aug  3 14:05:48.069 2023 (UTC + 2:00)), ptr64 TRUE
     ~~~
 
-    ...then you're most likely a victim of the CRLF issue mentioned above. To get around it I wrote a small utility that basically does what socat would do and additionally corrects those replaced bytes in the stream. It's not pretty but it works:
-
-```c
-#include <errno.h>
-#include <stdio.h>
-#include <fcntl.h>
-#include <termios.h>
-
-int fd1, fd2;
-char mark = ' ';
-
-void out(unsigned char c)
-{
-    static int count = 0;
-    static unsigned char buf[17] = {0};
-
-    // relay to ouptput port
-    write(fd2, &c, 1);
-    fprintf(stderr, "%c", mark);
-
-    /* dump all data going over the line
-    if (count == 0)
-        fprintf(stderr, "%c", mark);
-    fprintf(stderr, "%02x ", c);
-    if (c >= 0x20 && c < 0x80)
-        buf[count] = c;
-    else
-        buf[count] = '.';
-    count++;
-    if (count == 0x10)
-    {
-        count = 0;
-        fprintf(stderr, " %s\n", buf);
-    }
-    */
-}
-
-int main(int argc, char* argv[])
-{
-    unsigned char c = 0;
-    struct termios tio;
-    ssize_t size;
-
-    if (argc < 3)
-    {
-        fprintf(stderr, "Usage: %s pty1 pty2 [mark character]\n", argv[0]);
-        return EINVAL;
-    }
-
-    fd1 = open(argv[1], O_RDONLY | O_NOCTTY);
-    if (fd1 <= 0)
-    {
-        perror("open fd1");
-        return errno;
-    }
-    fd2 = open(argv[2], O_WRONLY | O_NOCTTY);
-    if (fd2 <= 0)
-    {
-        perror("open fd2");
-        return errno;
-    }
-/*
-    // This doesn't make any difference which supports the theory
-    // that it's Xen who corrupts the byte stream.
-    cfmakeraw(&tio);
-    if (tcsetattr(fd1, TCSANOW, &tio) < 0)
-    {
-        perror("tcsetattr 1");
-        return errno;
-    }
-    if (tcsetattr(fd2, TCSANOW, &tio) < 0)
-    {
-        perror("tcsetattr 2");
-        return errno;
-    }
-*/
-    if (argc == 4)
-        mark = argv[3][0];
-
-    while (1)
-    {
-        size = read(fd1, &c, 1);
-        if (size <= 0)
-            break;
-
-parse:
-        if (c == 0x0d)
-        {
-            size = read(fd1, &c, 1);
-            if (size <= 0)
-            {
-                out(0x0d);
-                break;
-            }
-            if (c == 0x0a)
-            {
-                out(0x0a);
-            }
-            else
-            {
-                out(0x0d);
-                goto parse;
-            }
-        }
-        else
-            out(c);
-    }
-
-    close(fd1);
-    close(fd2);
-    return 0;
-}
-```
-
-> This utility is a unidirectional relay so you need to run two instances to get duplex communication, like:
->
->     #!/bin/sh
->
->     id1=$(xl domid "$1-dm")
->     id2=$(xl domid "$2-dm")
->     tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty)
->     tty2=$(xenstore-read /local/domain/${id2}/device/console/3/tty)
->     ./ptycrlf ${tty1} ${tty2} - &
->     ./ptycrlf ${tty2} ${tty1} + &
-
-> With this everything should be good:
->
-> ~~~
-> Opened \\.\com1
-> Waiting to reconnect...
-> Connected to Windows 7 7601 x64 target at (Wed Mar 19 20:56:31.371 2014 (UTC + 1:00)), ptr64 TRUE
-> Kernel Debugger connection established.
-> Symbol search path is: srv*c:\symbols*https://msdl.microsoft.com/download/symbols
-> Executable search path is:
-> Windows 7 Kernel Version 7601 MP (1 procs) Free x64
-> Built by: 7601.18247.amd64fre.win7sp1_gdr.130828-1532
-> Machine Name:
-> Kernel base = 0xfffff800`0261a000 PsLoadedModuleList = 0xfffff800`0285d6d0
-> System Uptime: not available
-> ~~~
-
-# Debugging HVMs in the Qubes R4.0
-
-There are two main issues to be adopted to get all things to work in the R4.0.
-
-## Add a virtual serial port
-
-Qemu in the stub domain with virtual serial port added in a recommended way (```<serial type="pty"/>```) fails to start (Could not open '/dev/hvc1': No such device). It seems like a lack of multiple xen consoles support/configuration. The only way that I have found is to attach serial port explicitly to the available console.
-
-1. Unpack stub domain in dom0:
-
-```shell_session
-$ mkdir stubroot
-$ cp /usr/lib/xen/boot/stubdom-linux-rootfs stubroot/stubdom-linux-rootfs.gz
-$ cd stubroot
-$ gunzip stubdom-linux-rootfs.gz
-$ cpio -i -d -H newc --no-absolute-filenames < stubdom-linux-rootfs
-$ rm stubdom-linux-rootfs
-```
-
-2. Edit Init script to remove last loop and to add "-serial /dev/hvc0" to the qemu command line.
-
-3. Apply changes:
-
-```shell_session
-$ find . -print0 | cpio --null -ov --format=newc | gzip -9 > ../stubdom-linux-rootfs
-$ sudo mv ../stubdom-linux-rootfs /usr/lib/xen/boot
-```
-
-## Connect two consoles
-
-Run the following script:
-
-```shell
-debugname1=win7new
-debugname2=win7dbg
-id1=$(xl domid "$debugname1-dm")
-id2=$(xl domid "$debugname2-dm")
-
-tty1=$(xenstore-read /local/domain/${id1}/console/tty)
-tty2=$(xenstore-read /local/domain/${id1}/console/tty)
-
-socat $tty1,raw $tty2,raw
-```
-
 Happy debugging!

developer/general/package-contributions.md

@@ -71,7 +71,7 @@ The review procedure is as follows:
 1. Someone, S, wishes to make a change to a package, P.
 2. S submits a fast-forwardable pull request against the fork of P's repo owned by [QubesOS-contrib](https://github.com/QubesOS-contrib).
 3. The PM reviews the pull request.
-   If the the pull request passes the PM's review, the PM adds a [signed](/doc/code-signing/) *comment* on the pull request stating that it has passed review.
+   If the pull request passes the PM's review, the PM adds a [signed](/doc/code-signing/) *comment* on the pull request stating that it has passed review.
    (In cases in which S = PM, the PM can simply add a [signed](/doc/code-signing/) *tag* to the HEAD commit prior to submitting the pull request.)
    If the pull request does not pass the PM's review, the PM leaves a comment on the pull request explaining why not.
 4. The QCR reviews the pull request.

developer/releases/4_2/release-notes.md

@@ -1,6 +1,6 @@
 ---
 layout: doc
-title: Qubes OS 4.2.0 release notes
+title: Qubes OS 4.2 release notes
 permalink: /doc/releases/4.2/release-notes/
 ---
 

developer/services/admin-api.md

@@ -106,6 +106,7 @@ to set the policy using current mechanism.
 | `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>`

developer/services/dom0-secure-updates.md

@@ -33,11 +33,11 @@ Keeping Dom0 not connected to any network makes it hard, however, to provide upd
 
 The update process is initiated by [qubes-dom0-update script](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes-dom0-update), running in Dom0.
 
-Updates (\*.rpm files) are checked and downloaded by UpdateVM, which by default is the same as the firewall VM, but can be configured to be any other, network-connected VM. This is done by [qubes-download-dom0-updates.sh script](https://github.com/QubesOS/qubes-core-agent-linux/blob/release2/misc/qubes-download-dom0-updates.sh) (this script is executed using qrexec by the previously mentioned qubes-dom0-update). Note that we assume that this script might get compromised and fetch maliciously compromised downloads -- this is not a problem as Dom0 verifies digital signatures on updates later. The downloaded rpm files are placed in a ~~~/var/lib/qubes/dom0-updates~~~ directory on UpdateVM filesystem (again, they might get compromised while being kept there, still this isn't a problem). This directory is passed to yum using the ~~~--installroot=~~~ option.
+Updates (`*.rpm` files) are checked and downloaded by UpdateVM, which by default is the same as the firewall VM, but can be configured to be any other, network-connected VM. This is done by [qubes-download-dom0-updates.sh script](https://github.com/QubesOS/qubes-core-agent-linux/blob/release2/misc/qubes-download-dom0-updates.sh) (this script is executed using qrexec by the previously mentioned qubes-dom0-update). Note that we assume that this script might get compromised and fetch maliciously compromised downloads -- this is not a problem as Dom0 verifies digital signatures on updates later. The downloaded rpm files are placed in a ~~~/var/lib/qubes/dom0-updates~~~ directory on UpdateVM filesystem (again, they might get compromised while being kept there, still this isn't a problem). This directory is passed to yum using the ~~~--installroot=~~~ option.
 
 Once updates are downloaded, the update script that runs in UpdateVM requests an RPM service [qubes.ReceiveUpdates](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes.ReceiveUpdates) to be executed in Dom0. This service is implemented by [qubes-receive-updates script](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes-receive-updates) running in Dom0. The Dom0's qubes-dom0-update script (which originally initiated the whole update process) waits until qubes-receive-updates finished.
 
-The qubes-receive-updates script processes the untrusted input from Update VM: it first extracts the received \*.rpm files (that are sent over qrexec data connection) and then verifies digital signature on each file. The qubes-receive-updates script is a security-critical component of the Dom0 update process (as is the [qfile-dom0-unpacker.c](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qfile-dom0-unpacker.c) and the rpm utility, both used by the qubes-receive-updates for processing the untrusted input).
+The qubes-receive-updates script processes the untrusted input from Update VM: it first extracts the received `*.rpm` files (that are sent over qrexec data connection) and then verifies digital signature on each file. The qubes-receive-updates script is a security-critical component of the Dom0 update process (as is the [qfile-dom0-unpacker.c](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qfile-dom0-unpacker.c) and the rpm utility, both used by the qubes-receive-updates for processing the untrusted input).
 
 Once qubes-receive-updates finished unpacking and verifying the updates, the updates are placed in ``qubes-receive-updates`` directory in Dom0 filesystem. Those updates are now trusted. Dom0 is configured (see /etc/yum.conf in Dom0) to use this directory as a default (and only) [yum repository](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes-cached.repo).
 

developer/services/qrexec-internals.md

@@ -251,6 +251,6 @@ It is a [socket-based Qubes RPC service](/doc/qrexec-socket-services/). Requests
 There are two endpoints:
 
 - `policy.Ask` - ask the user about whether to execute a given action
-- `policy.Notify` - notify the user about about an 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.

developer/system/gui.md

@@ -49,7 +49,7 @@ In the case of Qubes, `qubes-gui` does not transfer all changed pixels via vchan
   and pass this to dom0 via the deprecated `MFNDUMP` message.
 - New `qubes-gui` versions will rely on `qubes-drv` having allocated
   memory using gntalloc, and then pass the grant table indexes gntalloc
-  has chosen to the GUI daemon using using the `WINDOW_DUMP` message.
+  has chosen to the GUI daemon using the `WINDOW_DUMP` message.
 
 Now, `qubes-guid` has to tell the dom0 Xorg server about the location of the buffer.
 There is no supported way (e.g. Xorg extension) to do this zero-copy style.

introduction/issue-tracking.md

@@ -67,7 +67,7 @@ There are three issue **types**: `T: bug`, `T: enhancement`, and `T: task`.
 - `T: enhancement` --- Type: enhancement. A new feature that does not yet exist **or** improvement of existing functionality.
 - `T: task` --- Type: task. An action item that is neither a bug nor an enhancement.
 
-Every open issue should have **exactly one** type. An open issue should not have more than one type, and it should not lack a type entirely. Bug reports are for problems in things that already exist. If something doesn't exist yet, but you think it ought to exist, then use `T: enhancement` instead. If something already exists, but you think it could be improved in some way, you should again use `T: enhancement`. `T: task` is for issues that fall under under neither `T: bug` nor `T: enhancement`.
+Every open issue should have **exactly one** type. An open issue should not have more than one type, and it should not lack a type entirely. Bug reports are for problems in things that already exist. If something doesn't exist yet, but you think it ought to exist, then use `T: enhancement` instead. If something already exists, but you think it could be improved in some way, you should again use `T: enhancement`. `T: task` is for issues that fall under neither `T: bug` nor `T: enhancement`.
 
 #### Priority
 

introduction/support.md

@@ -419,7 +419,7 @@ account is **not** required. Any email address will work.) To post a message to
 the list, address your email to `qubes-project@googlegroups.com`. If your post
 does not appear immediately, please allow time for moderation to occur. To
 unsubscribe, send a blank email to
-`qubes-project+unsubscribe@googlegroups.com`. This list also also has a
+`qubes-project+unsubscribe@googlegroups.com`. This list also has a
 [traditional mail
 archive](https://www.mail-archive.com/qubes-project@googlegroups.com/) and an
 optional [Google Groups web

user/advanced-topics/bind-dirs.md

@@ -60,7 +60,7 @@ In this example, we want to make `/var/lib/tor` persistent. Enter all of the fol
 
 From now on, all files in the `/var/lib/tor` directory will persist across reboots.
 
-You can make make as many files or folders persist as you want simply by making multiple entries in the `50_user.conf` file, each on a separate line.
+You can make as many files or folders persist as you want simply by making multiple entries in the `50_user.conf` file, each on a separate line.
 For example, if you added the file `/etc/tor/torrc` to the `binds` variable, any modifications to *that* file would also persist across reboots.
 
 ```

user/advanced-topics/disposable-customization.md

@@ -27,7 +27,7 @@ Additionally, if you want to have menu entries for starting applications in disp
 [user@dom0 ~]$ qvm-features <DISPOSABLE_TEMPLATE> appmenus-dispvm 1
 ```
 
-**Note:** Application shortcuts that existed before setting this feature will not be updated automatically. Please go the the "Applications" tab in the qube's "Settings" dialog and unselect all existing shortcuts by clicking "<<", then click "OK" and close the dialog. Give it a few seconds time and then reopen and re-select all the shortcuts you want to see in the menu. See [this page](/doc/managing-appvm-shortcuts) for background information.
+**Note:** Application shortcuts that existed before setting this feature will not be updated automatically. Please go the "Applications" tab in the qube's "Settings" dialog and unselect all existing shortcuts by clicking "<<", then click "OK" and close the dialog. Give it a few seconds time and then reopen and re-select all the shortcuts you want to see in the menu. See [this page](/doc/managing-appvm-shortcuts) for background information.
 
 ## Security
 

user/advanced-topics/how-to-install-software-in-dom0.md

@@ -209,23 +209,7 @@ to do a lot of work yourself](https://groups.google.com/d/msg/qubes-users/m8sWoy
 
 This section describes changing the default kernel in dom0. It is sometimes
 needed if you have upgraded to a newer kernel and are having problems booting,
-for example. The procedure varies depending on if you are booting with UEFI or
-grub. On the next kernel update, the default will revert to the newest.
-
-### EFI
-
-~~~
-sudo nano /boot/efi/EFI/qubes/xen.cfg
-~~~
-
-In the `[global]` section at the top, change the `default=` line to match one
-of the three boot entries listed below. For example:
-
-~~~
-default=4.19.67-1.pvops.qubes.x86_64
-~~~
-
-### Grub2
+for example. On the next kernel update, the default will revert to the newest.
 
 ~~~
 sudo nano /etc/default/grub

user/advanced-topics/managing-vm-kernels.md

@@ -313,7 +313,7 @@ Go to dom0 -> Qubes VM Manger -> right click on the VM -> Qube settings -> Advan
 Depends on `Virtualization` mode setting:
 
 * `Virtualization` mode `PV`: Possible, however use of `Virtualization` mode `PV` mode is discouraged for security purposes.
-  * If you require `Virtualization` mode `PV` mode, install `grub2-xen-pvh` in dom0. This can be done by running command `sudo qubes-dom0-update pvgrub2-pvh in dom0.
+  * If you require `Virtualization` mode `PV` mode, install `grub2-xen-pvh` in dom0. This can be done by running command `sudo qubes-dom0-update pvgrub2-pvh` in dom0.
 * `Virtualization` mode `PVH`: Possible.
 * `Virtualization` mode `HVM`: Possible.
 

user/advanced-topics/standalones-and-hvms.md

@@ -34,7 +34,7 @@ virtualization extensions of the host CPU. These are typically contrasted with
 Paravirtualized (PV) VMs.
 
 HVMs allow you to create qubes based on any OS for which you have an
-installation ISO, so you can easily have qubes running Windows, \*BSD, or any
+installation ISO, so you can easily have qubes running Windows, `*BSD`, or any
 Linux distribution. You can also use HVMs to run "live" distros.
 
 By default, every qube runs in PVH mode (which has security advantages over
@@ -197,7 +197,7 @@ you would install it into a normal HVM. Generally, you should install in to the
 first "system" disk. (Resize it as needed before starting installation.)
 
 You can then create a new qube using the new template. If you use this Template
-as is, then any HVMs based on it it will effectively be disposables. All file
+as is, then any HVMs based on it will effectively be disposables. All file
 system changes will be wiped when the HVM is shut down.
 
 Please see [this

user/advanced-topics/volume-backup-revert.md

@@ -42,7 +42,7 @@ qvm-volume config vmname:private revisions_to_keep 2
 ```
 
 With the VM stopped, you may revert to an older snapshot of the private volume
-from the the above list of "Available revisions (for revert)", where the last
+from the above list of "Available revisions (for revert)", where the last
 item on the list with the largest integer is the most recent snapshot:
 
 ```

user/downloading-installing-upgrading/installation-guide.md

@@ -118,7 +118,7 @@ From here, you can navigate the boot screen using the arrow keys on your keyboar
 * Install Qubes OS
 * Test this media and install Qubes OS
 * Troubleshooting - verbose boot
-* Rescue a Qubes SO system
+* Rescue a Qubes OS system
 * Install Qubes OS 4.2.1 using kernel-latest
  
 Select the option to test this media and install Qubes OS. 

user/downloading-installing-upgrading/supported-releases.md

@@ -57,8 +57,8 @@ It is the responsibility of each distribution to clearly notify its users in adv
 
 | Qubes OS    | Fedora | Debian |
 | ----------- | ------ | ------ |
-| Release 4.1 | 38, 39 | 11, 12 |
-| Release 4.2 | 38, 39 | 12     |
+| Release 4.1 | 39     | 11, 12 |
+| Release 4.2 | 39     | 12     |
 
 ### Note on Debian support
 

user/hardware/certified-hardware.md

@@ -86,7 +86,7 @@ If you are a hardware vendor, you can have your hardware certified as compatible
 
 **Note:** This section describes the requirements for hardware *certification*, *not* the requirements for *running* Qubes OS. For the latter, please see the [system requirements](/doc/system-requirements/). A brief list of the requirements described in this section is available [here](/doc/system-requirements/#qubes-certified-hardware).
 
-A basic requirement is that all Qubes-certified devices must be be available for purchase with Qubes OS preinstalled. Customers may be offered the option to select from a list of various operating systems (or no operating system at all) to be preinstalled, but Qubes OS must be on that list in order to maintain Qubes hardware certification.
+A basic requirement is that all Qubes-certified devices must be available for purchase with Qubes OS preinstalled. Customers may be offered the option to select from a list of various operating systems (or no operating system at all) to be preinstalled, but Qubes OS must be on that list in order to maintain Qubes hardware certification.
 
 One of the most important security improvements introduced with the release of Qubes 4.0 was to replace paravirtualization (PV) technology with **hardware-enforced memory virtualization**, which recent processors have made possible thanks to so-called Second Level Address Translation ([SLAT](https://en.wikipedia.org/wiki/Second_Level_Address_Translation)), also known as [EPT](https://ark.intel.com/Search/FeatureFilter?productType=processors&ExtendedPageTables=true&MarketSegment=Mobile) in Intel parlance. SLAT (EPT) is an extension to Intel VT-x virtualization, which originally was capable of only CPU virtualization but not memory virtualization and hence required a complex Shadow Page Tables approach. We hope that embracing SLAT-based memory virtualization will allow us to prevent disastrous security bugs, such as the infamous [XSA-148](https://xenbits.xen.org/xsa/advisory-148.html), which --- unlike many other major Xen bugs --- regrettably did [affect](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-022-2015.txt) Qubes OS. Consequently, we require SLAT support of all certified hardware beginning with Qubes OS 4.0.
 

user/how-to-guides/how-to-use-block-storage-devices.md

@@ -122,7 +122,7 @@ If you don't see anything that looks like your drive, run `sudo udevadm trigger
 
 ## Recovering From Premature Device Destruction
 
-If the you fail to detach the device before it's destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), [there will be problems](https://github.com/QubesOS/qubes-issues/issues/1082).
+If you fail to detach the device before it's destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), [there will be problems](https://github.com/QubesOS/qubes-issues/issues/1082).
 
 To recover from this error state, in dom0 run
 

user/security-in-qubes/firewall.md

@@ -284,7 +284,7 @@ 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 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:
+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:
 
 ```
 nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'

user/security-in-qubes/split-gpg.md

@@ -140,10 +140,10 @@ 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:
+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
+@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.
@@ -361,10 +361,10 @@ Once the master secret key is in the `work-email` VM, the attacker could simply
 
 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.
-<sup>\*</sup> 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.
+[^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.)
 
-<sup>\*</sup>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.
+[^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
 

user/templates/windows/qubes-windows-tools-4-0.md

@@ -270,7 +270,7 @@ Qubes Windows Tools (QWT for short) contain several components than can be enabl
    - Xen PV Disk Drivers: paravirtual storage drivers.
    - Xen PV Network Drivers: paravirtual network drivers.
 - Qubes Core Agent: qrexec agent and services. Needed for proper integration with Qubes.
-   - Move user profiles: user profile directory (c:\users) is moved to VM's private disk backed by private.img file in dom0 (useful mainly for HVM templates).
+   - Move user profiles: user profile directory (`c:\users`) is moved to VM's private disk backed by private.img file in dom0 (useful mainly for HVM templates).
 - Qubes GUI Agent: video driver and gui agent that enable seamless showing of Windows applications on the secure Qubes desktop.
 - Disable UAC: User Account Control may interfere with QWT and doesn't really provide any additional benefits in Qubes environment.
 
@@ -331,7 +331,7 @@ If the VM is inaccessible (doesn't respond to qrexec commands, gui is not functi
 
 Safe Mode should at least give you access to logs (see above).
 
-**Please include appropriate logs when reporting bugs/problems.** Starting from version 2.4.2 logs contain QWT version, but if you're using an earlier version be sure to mention which one. If the OS crashes (BSOD) please include the BSOD code and parameters in your bug report. The BSOD screen should be visible if you run the VM in debug mode (`qvm-start --debug vmname`). If it's not visible or the VM reboots automatically, try to start Windows in safe mode (see above) and 1) disable automatic restart on BSOD (Control Panel - System - Advanced system settings - Advanced - Startup and recovery), 2) check the system event log for BSOD events. If you can, send the `memory.dmp` dump file from c:\Windows.
+**Please include appropriate logs when reporting bugs/problems.** Starting from version 2.4.2 logs contain QWT version, but if you're using an earlier version be sure to mention which one. If the OS crashes (BSOD) please include the BSOD code and parameters in your bug report. The BSOD screen should be visible if you run the VM in debug mode (`qvm-start --debug vmname`). If it's not visible or the VM reboots automatically, try to start Windows in safe mode (see above) and 1) disable automatic restart on BSOD (Control Panel - System - Advanced system settings - Advanced - Startup and recovery), 2) check the system event log for BSOD events. If you can, send the `memory.dmp` dump file from `c:\Windows`.
 Xen logs (/var/log/xen/console/guest-*) are also useful as they contain pvdrivers diagnostic output.
 
 If a specific component is malfunctioning, you can increase its log verbosity as explained above to get more troubleshooting information. Below is a list of components:

user/templates/windows/qubes-windows-tools-4-1.md

@@ -26,7 +26,7 @@ Qubes Windows Tools (QWT) are a set of programs and drivers that provide integra
 - **Audio** - Audio support is available even without QWT installation if `qvm-features audio-model` is set as `ich6`
 
 
-**Note:** Due to the security problems described in [QSB-091](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-091-2023.txt), installation of Qubes Windows Tools is currently blocked. Instead, a text file containing a warning is displayed. Currently, it is difficult to estimate the severity of the risks posed by the sources of the Xen drivers used in QWT possibly being compromised, so it was decided not to offer direct QWT installation until this problem could be treated properly. While Windows qubes are, in Qubes, generally not regarded as being very trustworthy, a possible compromise of the Xen drivers used in Qubes Windows Tools might create a risk for Xen or dom0 and thus be dangerous for Qubes itself. If you **understand** this risk and are **willing to take it**, you can still install the previous versions of Qubes Windows Tools, using the command
+**Note:** Due to the security problems described in [QSB-091](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-091-2023.txt), installation of Qubes Windows Tools is currently blocked. Instead, a text file containing a warning is displayed. Currently, it is difficult to estimate the severity of the risks posed by the sources of the Xen drivers used in QWT possibly being compromised, so it was decided not to offer direct QWT installation until this problem could be treated properly. While Windows qubes are, in Qubes, generally not regarded as being very trustworthy, a possible compromise of the Xen drivers used in Qubes Windows Tools might create a risk for Xen or `dom0` and thus be dangerous for Qubes itself. This risk may be small or even non-existent, as stated in QSB-091. If you **understand** this risk and are **willing to take it**, you can still install the previous versions of Qubes Windows Tools, using the command
 
 	sudo qubes-dom0-update qubes-windows-tools-4.1.68
 
@@ -34,9 +34,9 @@ for Qubes R4.1.2, or
 
 	sudo qubes-dom0-update qubes-windows-tools-4.1.69
 
-for Qubes R4.2.0, respectively, instead of the command listed in step 1 of the installation described below. This will provide the .iso file to be presented as installation drive to the Windows qube in step 3 of the QWT installation.
+for Qubes R4.2.0, respectively, instead of the command listed in step 1 of the installation described below. This will provide the .iso file to be presented as an installation drive to the Windows qube in step 3 of the QWT installation.
 
-If you prefer to download the corresponding .rpm files for manual QWT installation, these are still available from the repositories (version [4.1.68-1](https://yum.qubes-os.org/r4.1/current/dom0/fc32/rpm/qubes-windows-tools-4.1.68-1.noarch.rpm) for Qubes R4.1.2 and version [4.1.69-1](https://yum.qubes-os.org/r4.2/current/dom0/fc37/rpm/qubes-windows-tools-4.1.69-1.fc37.noarch.rpm) for Qubes R4.2.0).
+If you prefer to download the corresponding .rpm files for manual QWT installation, these are still available from the repositories (version [4.1.68-1](https://yum.qubes-os.org/r4.1/current/dom0/fc32/rpm/qubes-windows-tools-4.1.68-1.noarch.rpm) for Qubes R4.1.2 and version [4.1.69-1](https://yum.qubes-os.org/r4.2/current/dom0/fc37/rpm/qubes-windows-tools-4.1.69-1.fc37.noarch.rpm) for Qubes R4.2.0). After downloading, copy the file to `dom0` as described in [How to copy from dom0](https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-dom0) and install it via `sudo dnf install /path/to/rpmfile`. Now you can proceed according to step 3 of the description below.
 
 **Warning**: These older versions of Qubes Windows Tools will be replaced during the next dom0 update by the current dummy version 4.1.70-1. This can be inhibited by appending the line `exclude=qubes-windows-tools` to the file `/etc/dnf/dnf.conf` in dom0. But this will also stop any further QWT updates - so be sure to remove this line when - hopefully - a new functional version 4.1.71-1 of Qubes Windows Tools will be made available!!!
 
@@ -263,7 +263,7 @@ Windows qubes can be used as disposables, like any other Linux-based qubes. On c
 		- Type `shell:startup`.
 		- An explorer window will open, which is positioned to the `Autostart` folder.
 	- Right-click and select the option "New -> Link".
-	- Select `C:\Windows\System32\CMD.exe`as executable.
+	- Select `C:\Windows\System32\CMD.exe` as executable.
 	- Name the link, e.g. as `Command Prompt`.
 	- Close the Window with `OK`.
 	- Shut down this AppVM.
@@ -273,7 +273,7 @@ Windows qubes can be used as disposables, like any other Linux-based qubes. On c
 - Still in the Advanced tab, select your Windows qube as its own `Default disposable template`. Alternatively, in dom0 execute the command `qvm-prefs <VMname> default_dispvm <VMname>`.
 - Close the Qube Manager by clicking `OK`.
 
-Now you should have a menu `Disposable: <VMname>` containing the applications that can be started in a disposable Windows VM. If you set the newly created and configured Windows VM as `Default disposable template`for any other Windows- (or Linux-) based qube, this qube can use the Windows-based dispvm like any other disposable.
+Now you should have a menu `Disposable: <VMname>` containing the applications that can be started in a disposable Windows VM. If you set the newly created and configured Windows VM as `Default disposable template` for any other Windows- (or Linux-) based qube, this qube can use the Windows-based dispvm like any other disposable.
 
 For further information on usage of disposables, see [How to use disposables](/doc/how-to-use-disposables/).
 

user/troubleshooting/app-menu-shortcut-troubleshooting.md

@@ -16,11 +16,11 @@ Clicking on such shortcut runs the assigned application in its app qube.
 
 ![dom0-menu.png"](/attachment/doc/r4.0-dom0-menu.png)
 
-To make applications newly installed via the OS's package manager show up in the menu, use the `qvm-sync-appmenus` command (Linux VMs do this automatically):
+To make applications newly installed via the OS's package manager show up in the menu, use the `qvm-sync-appmenus` command (Linux qubes do this automatically):
 
 `qvm-sync-appmenus vmname`
 
-After that, select the *Add more shortcuts* entry in the VM's submenu to customize which applications are shown:
+After that, select the *Add more shortcuts* entry in the qube's submenu to customize which applications are shown:
 
 ![dom0-appmenu-select.png"](/attachment/doc/r4.0-dom0-appmenu-select.png)
 
@@ -29,7 +29,7 @@ The above image shows that Windows HVMs are also supported (provided that Qubes
 What if my application has not been automatically included in the list of available apps?
 -----------------------------------------------------------------------------------------
 
-Some times applications may not have included a `.desktop` file and may not be detected by `qvm-sync-appmenus`.
+Sometimes applications may not have included a `.desktop` file and may not be detected by `qvm-sync-appmenus`.
 Other times, you may want to make a web shortcut available from the Qubes start menu.
 
 You can manually create new entries in the "available applications" list of shortcuts for all app qubes based on a template.
@@ -75,7 +75,7 @@ If you only want to create a shortcut for a single app qube, you can create a cu
    </Menu>
    ~~~
 
-What about applications in DispVMs?
+What about applications in disposables?
 -----------------------------------
 
 [See here](/doc/disposable-customization/).
@@ -101,17 +101,21 @@ $ rm -i ~/.local/share/applications/my-old-vm-*
 Behind the scenes
 -----------------
 
-`qvm-sync-appmenus` works by invoking *GetAppMenus* [Qubes service](/doc/qrexec/) in the target domain.
-This service enumerates installed applications and sends formatted info back to the dom0 script (`/usr/libexec/qubes-appmenus/qubes-receive-appmenus`) which creates .desktop files in the app qube/template directory.
+`qvm-sync-appmenus` works by invoking the *GetAppMenus* [Qubes service](/doc/qrexec/) in the target domain.
+This service enumerates applications installed in that qube and sends formatted info back to the dom0 script (`/usr/libexec/qubes-appmenus/qubes-receive-appmenus`) which creates `.desktop` files in the app qube/template directory of dom0.
 
-For Linux VMs the service script is in `/etc/qubes-rpc/qubes.GetAppMenus`.
+For Linux qubes the service script is in `/etc/qubes-rpc/qubes.GetAppMenus`.
 In Windows it's a PowerShell script located in `c:\Program Files\Invisible Things Lab\Qubes OS Windows Tools\qubes-rpc-services\get-appmenus.ps1` by default.
 
 The list of installed applications for each app qube is stored in dom0's `~/.local/share/qubes-appmenus/<vmname>/apps.templates`.
 Each menu entry is a file that follows the [.desktop file format](https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) with some wildcards (*%VMNAME%*, *%VMDIR%*).
 Applications selected to appear in the menu are stored in `~/.local/share/qubes-appmenus/<vmname>/apps`.
 
-Actual command lines for the menu shortcuts involve `qvm-run` command which starts a process in another domain.
+Actual command lines for the menu shortcuts involve the `qvm-run` command which starts a process in another domain.
 Examples: `qvm-run -q -a --service -- %VMNAME% qubes.StartApp+7-Zip-7-Zip_File_Manager` or `qvm-run -q -a --service -- %VMNAME% qubes.StartApp+firefox`
 
-Note that you can create a shortcut that points to a .desktop file in your app qube with e.g. `qvm-run -q -a --service -- personal qubes.StartApp+firefox`.
+Note that you can create a shortcut that points to a `.desktop` file in your app qube with e.g. `qvm-run -q -a --service -- personal qubes.StartApp+firefox`.
+
+While this works well for standard applications, creating a menu entry for Windows applications running under *wine* may need an additional step in order to establish the necessary environment in *wine*. Installing software under *wine* will create the needed `.desktop` file in the target Linux qube in the directory `~/.local/share/applications/wine/Programs/` or a subdirectory thereof, depending on the Windows menu structure seen under *wine*. If the name of this file contains spaces, it will not be found, because the `qvm-run` command is falsely seen as terminating at this space. The solution is to remove these spaces by renaming the `.desktop` file accordingly, e.g. by renaming `Microsoft Excel.desktop` to `Excel.desktop`. Refreshing the menu structure will then build working menu entries.
+
+**Note:** Applications installed under *wine* are installed in AppVMs, not in the template on which these AppVMs are based, as the file structure used by *wine* is stored under `~/.wine`, which is part of the persistent data of the AppVM and not inherited from its template.

user/troubleshooting/pci-troubleshooting.md

@@ -104,7 +104,7 @@ While using the `no-strict-reset` flag, do not require PCI device to be reset be
 qvm-pci attach --persistent --option permissive=true --option no-strict-reset=true sys-usb dom0:<BDF_OF_DEVICE>
 ~~~
 
-Be sure to replace `<BDF_OF_DEVICE>` with the BDF of your PCI device, which can be be obtained from running `qvm-pci`.
+Be sure to replace `<BDF_OF_DEVICE>` with the BDF of your PCI device, which can be obtained from running `qvm-pci`.
 
 You can also configure strict reset directly from the Qubes interface by following these steps: