fixed a tab

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

developer/building/development-workflow.md

@@ -12,42 +12,41 @@ title: Development workflow
 
 A workflow for developing Qubes OS+
 
-First things first, setup [QubesBuilder](/doc/qubes-builder/). This guide
+To begin, setup [QubesBuilder](/doc/qubes-builder-v2/). This guide
-assumes you're using qubes-builder to build Qubes.
+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
-`qubes-src` directory under qubes-builder. Subdirectories there are separate
+`artifacts/sources` directory under qubes-builder. Subdirectories there are
-components, stored in separate git repositories.
+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
 
 **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
+$ 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
+commits from the dev branches, merge them, and eventually push to your own repo.
-on github.
 
 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
+letter to the Qubes listserv describing the changes, and including a link to
-your repository. You can also create pull request on github. Don't forget to
+your repository. If you are using GitHub you can instead create a pull request.
-include your public PGP key you use to sign your tags.
+Don't forget to include the public PGP key you use to sign your tags.
 
 ### Kernel-specific notes
 
 #### 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 +65,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
@@ -74,14 +73,14 @@ cd kernel-3.4.18/linux-3.4.18
 
 #### Changing the config
 
-In kernel-3.4.18/linux-3.4.18:
+In `kernel-3.4.18/linux-3.4.18`:
 
 ~~~
 cp ../../config .config
 make oldconfig
 ~~~
 
-Now change the configuration. For example, in kernel-3.4.18/linux-3.4.18:
+Now change the configuration. For example, in `kernel-3.4.18/linux-3.4.18`:
 
 ~~~
 make menuconfig
@@ -117,9 +116,7 @@ vi series.conf
 
 #### Building RPMs
 
-TODO: Is this step generic for all subsystems?
+Now is a good moment to make sure you have changed the kernel release name in
-
-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
 'kernel-3.4.18-1debug20121116c.pvops.qubes.x86\_64.rpm'. This will help
@@ -131,34 +128,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/`
 
-~~~
+### Useful [QubesBuilder](/doc/qubes-builder-v2/) commands
--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/) commands
+1. `./qb package diff` - show uncommitted changes
-
+2. ` ./qb repository check-release-status-for-component` and
-1. `make check` - will check if all the code was committed into repository and
+`./qb repository check-release-status-for-template` - show version of each
-if all repository are tagged with signed tag.
+   component/template (based on git tags)
-2. `make show-vtags` - show version of each component (based on git tags) -
+3. `./qb package sign` -  sign built packages
-mostly useful just before building ISO. **Note:** this will not show version
+4. `./qb package publish` and `./qb package upload` - publish signed packages
-for components containing changes since last version tag.
+   and upload published
-3. `make push` - push change from **all** repositories to git server. You must
+   repository
-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.
 
 ## Copying Code to dom0
 
@@ -297,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.
 
@@ -321,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:
 
 ~~~
@@ -337,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
@@ -417,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)

developer/building/qubes-builder-v2.md

@@ -0,0 +1,166 @@
+---
+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 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/).
+
+# 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 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 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. Installing dependencies
+
+   - 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:
+   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
+   ```
+
+    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
+   $ 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 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:
+
+   ```
+   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:
+
+```
+# 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 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.
+

developer/code/code-signing.md

@@ -144,9 +144,11 @@ Although GitHub adds a little green `Verified` button next to the commit, the [s
 
 1. Is the commit signed?
    If the commit is not signed, you can see the message
+   
    > policy/qubesos/code-signing — No signature found
 2. If the commit is signed, the key is downloaded from a GPG key server.
    If you can see the following error message, please check if you have uploaded the key to a key server.
+   
    > policy/qubesos/code-signing — Unable to verify (no valid key found)
 
 ### No Signature Found

developer/code/source-code.md

@@ -60,6 +60,7 @@ method you choose, you must [sign your code](/doc/code-signing/) before it can b
 
 * **Preferred**: Use GitHub's [fork & pull requests](https://guides.github.com/activities/forking/).
 
+
    Opening a pull request on GitHub greatly eases the code review and tracking
    process. In addition, especially for bigger changes, it's a good idea to send
    a message to the [qubes-devel mailing list](/support/#qubes-devel) in order to notify people who

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:
 
@@ -267,11 +267,13 @@ It feeds off of the openQA test data to make graph plots. Here is an example:
 ![openqa-investigator-splitgpg-example.png](/attachment/doc/openqa-investigator-splitgpg-example.png)
 
 Some outputs:
+
   - plot by tests
   - plot by errors
   - markdown
 
 Some filters:
+
   - filter by error
   - filter by test name
 

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
 ```

developer/general/developing-gui-applications.md

@@ -59,7 +59,7 @@ If error should be thrown, you need to provide the error code and name, for exam
       b'2\x00QubesNoSuchPropertyError\x00\x00No such property\x00'
 ```
 
-For details of particular calls, you can use [Extending the mock Qubes object].
+For details of particular calls, you can use [Extending the mock Qubes object](#extending-the-mock-qubes-object).
 
 
 ## Available mocks

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
 
@@ -174,45 +174,6 @@ If applicable, links to more information or discussions
 
 **Mentor**: [Frédéric Pierret](/team/)
 
-<!--
-
-REMOVED as of February 2022: work is being done on this
-
-### Wayland support in GUI agent and/or GUI daemon
-
-**Project**: Wayland support in GUI agent and/or GUI daemon
-
-**Brief explanation**: Currently both GUI agent (VM side of the GUI virtualization) and GUI daemon (dom0 side of GUI virtualization) support X11 protocol only. It may be useful to add support for Wayland there. Note that those are in fact two independent projects:
-
-1. GUI agent - make it work as Wayland compositor, instead of extracting window's composition buffers using custom X11 driver
-2. GUI daemon - act as Wayland application, showing windows retrieved from VMs, keeping zero-copy display path (window content is directly mapped from application running in VM, not copied)
-
-**Expected results**:
-
-Choose either of GUI agent, GUI daemon. Both are of similar complexity and each separately looks like a good task for GSoC time period.
-
-- design relevant GUI agent/daemon changes, the GUI protocol should not be affected
-- consider window decoration handling - VM should have no way of spoofing those, so it must be enforced by GUI daemon (either client-side - by GUI daemon itself, or server-side, based on hints given by GUI daemon)
-- implement relevant GUI agent/daemon changes
-- implement tests for new GUI handling, similar to existing tests for X11 based GUI
-
-Relevant links:
-
-- [Low level GUI documentation](/doc/gui/)
-- [qubes-gui-agent-linux](https://github.com/qubesos/qubes-gui-agent-linux)
-- [qubes-gui-daemon](https://github.com/qubesos/qubes-gui-daemon)
-- [Use Wayland instead of X11 to increase performance](https://github.com/qubesos/qubes-issues/issues/3366)
-
-**Knowledge prerequisite**:
-
-- Wayland architecture
-- basics of X11 (for understanding existing code)
-- C language
-- using shared memory (synchronization methods etc)
-
-**Mentor**: [Marek Marczykowski-Górecki](/team/).
-
--->
 
 ### Qubes Live USB
 
@@ -252,26 +213,6 @@ details: [#1552](https://github.com/QubesOS/qubes-issues/issues/1552),
 
 **Mentor**: [Frédéric Pierret](/team/)
 
-<!--
-### Unikernel-based firewallvm with Qubes firewall settings support
-
-REMOVED as of January 2020: work is being done on this
-
-**Project**: Unikernel based firewallvm with Qubes firewall settings support
-
-**Brief explanation**: [blog post](https://roscidus.com/blog/blog/2016/01/01/a-unikernel-firewall-for-qubesos/), [repo](https://github.com/talex5/qubes-mirage-firewall)
-
-**Expected results**: A firewall implemented as a unikernel which supports all the networking-related functionality as the default sys-firewall VM, including configuration via Qubes Manager. Other duties currently assigned to sys-firewall such as the update proxy may need to be appropriately migrated first.
-
-**Knowledge prerequisite**:
-
-- [OCaml](https://ocaml.org/) + [MirageOS](https://mirage.io/) or other unikernel framework,
-- Xen network stack,
-- Qubes networking model & firewall semantics.
-
-**Mentor**: [Thomas Leonard](mailto:talex5@gmail.com), [Marek Marczykowski-Górecki](/team/)
--->
-
 ### LogVM(s)
 
 **Project**: LogVM(s)
@@ -422,7 +363,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
 
@@ -461,44 +402,6 @@ Some related discussion:
 **Mentor**: [Marek Marczykowski-Górecki](/team/)
 
 
-<!--
-
-REMOVED as of February 2021: work is being done on this
-
-### Porting Qubes to POWER9/PPC64
-
-**Project**: Porting Qubes to POWER9/ppc64
-
-**Brief explanation**:
-
-Qubes currently supports the x86_64 CPU architecture. PowerPC is desirable for security purposes as it is the only architecture where one can get performant hardware with entirely open source firmware. Xen has **deprecated** support for Power9/PPC64 processors. Here are two directions to tackle this project from:
-
-- Port Qubes to KVM then work on ppc64 specifics
-  - Implement some missing functionality in KVM then implement KVM support in the Qubes Hypervisor Abstraction Layer and build process. Improving the HAL will also be beneficial for simplifying the process of porting to further architectures and hypervisors.
-
-- Port Xen to ppc64 then work on Qubes specifics
-  - For more information on porting Xen see [this thread](https://markmail.org/message/vuk7atnyqfq52epp).
-
-More information and further links can be found in the related issue:
-[#4318](https://github.com/QubesOS/qubes-issues/issues/4318).
-
-**Expected results**:
-
-- Add cross-compilation support to qubes-builder and related components.
-- Make ppc64 specific adjustments to Qubes toolstacks/manager (including passthrough of devices from device tree to guest domains).
-- ppc64 specific integration and unit tests.
-- Production of generic u-boot or uefi capable image/iso for target hardware.
-
-**Knowledge prerequisite**:
-
-- Libvirt and Qubes toolstacks (C and python languages).
-- KVM or XEN internals
-- General ppc64 architecture knowledge.
-
-**Mentor**: [Marek Marczykowski-Górecki](/team/)
-
--->
-
 ### Android development in Qubes
 
 **Project**: Research running Android in Qubes VM (probably HVM) and connecting it to Android Studio
@@ -538,12 +441,14 @@ Since the Admin API is continuously growing and changing, continuous security as
 A [Fuzzer](https://en.wikipedia.org/wiki/Fuzzing) would help to automate part of these assessments.
 
 **Expected results**:
+
   - fully automated & extensible Fuzzer for parts of the Admin API
   - user & developer documentation
 
 **Difficulty**: medium
 
 **Prerequisites**:
+
   - basic Python understanding
   - some knowledge about fuzzing & existing fuzzing frameworks (e.g. [oss-fuzz](https://github.com/google/oss-fuzz/tree/master/projects/qubes-os))
   - a hacker's curiosity
@@ -560,6 +465,7 @@ A [Fuzzer](https://en.wikipedia.org/wiki/Fuzzing) would help to automate part of
 **Brief explanation**: Since recently, Xen supports "unified EFI boot" which allows to sign not only Xen binary itself, but also dom0 kernel and their parameters. While the base technology is there, enabling it is a painful and complex process. The goal of this project is to integrate configuration of this feature into Qubes, automating as much as possible. See discussion in [issue #4371](https://github.com/QubesOS/qubes-issues/issues/4371)
 
 **Expected results**:
+
  - a tool to prepare relevant boot files for unified Xen EFI boot - this includes collecting Xen, dom0 kernel, initramfs, config file, and possibly few more (ucode update?); the tool should then sign the file with user provided key (preferably propose to generate it too)
  - integrate it with updates mechanism, so new Xen or dom0 kernel will be picked up automatically
  - include a fallback configuration that can be used for troubleshooting (main unified Xen EFI intentionally does not allow to manipulate parameters at boot time)
@@ -567,6 +473,7 @@ A [Fuzzer](https://en.wikipedia.org/wiki/Fuzzing) would help to automate part of
 **Difficulty**: hard
 
 **Knowledge prerequisite**:
+
  - basic understanding of Secure Boot
  - Bash and Python scripting
 
@@ -586,6 +493,7 @@ A [Fuzzer](https://en.wikipedia.org/wiki/Fuzzing) would help to automate part of
 **Difficulty**: medium
 
 **Knowledge prerequisite**:
+
  - Python scripting
  - Basic knowledge of Linux system services management (systemd, syslog etc)
 

developer/general/gsod.md

@@ -58,9 +58,9 @@ Qubes OS regularly participates in Google Summer of Code and Google Season of Do
 
 ## Past Projects
 
-You can view the project we had in 2019 in the [2019 GSoD archive](https://developers.google.com/season-of-docs/docs/2019/participants/project-qubes) and the [2019 writer's report](https://refre.ch/report-qubesos/).
+You can view the project we had in 2019 in the [2019 GSoD archive](https://developers.google.com/season-of-docs/docs/2019/participants/project-qubes) and the [2019 writer's report](https://web.archive.org/web/20200928002746/https://refre.ch/report-qubesos/).
 
-You can view the project we had in 2020 in the [2020 GSoD archive](https://developers.google.com/season-of-docs/docs/2020/participants/project-qubesos-c1e0) and the [2020 writer's report](https://gist.github.com/PROTechThor/bfe9b8b28295d88c438b6f6c754ae733).
+You can view the project we had in 2020 in the [2020 GSoD archive](https://developers.google.com/season-of-docs/docs/2020/participants/project-qubesos-c1e0) and the [2020 writer's report](https://web.archive.org/web/20210723170547/https://gist.github.com/PROTechThor/bfe9b8b28295d88c438b6f6c754ae733).
 
 You can view the results of the project we had in 2023 [here](https://www.youtube.com/playlist?list=PLjwSYc73nX6aHcpqub-6lzJbL0vhLleTB).
 

developer/releases/2_0/release-notes.md

@@ -68,7 +68,7 @@ Note: if the user has custom Template VMs (i.e. other than the default template,
 
 #### From Qubes R1 to R2 beta1
 
-If you're already running Qubes Release 1, you don't need to reinstall, it's just enough to update the packages in your Dom0 and the template VM(s). This procedure is described [here?](/doc/upgrade-to-r2/).
+If you're already running Qubes Release 1, you don't need to reinstall, it's just enough to update the packages in your Dom0 and the template VM(s). This procedure is described [here](/doc/upgrade-to-r2/).
 
 #### From Qubes R1 or R2 Beta 1 to R2 beta2
 

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, [current API documentation](https://dev.qubes-os.org/projects/core-admin/en/latest/) and the documentation API index as a [webarchive](https://web.archive.org/web/20230128102821/https://dev.qubes-os.org/projects/qubes-core-admin/en/latest/)
 * [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

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

@@ -57,17 +57,17 @@ We strongly recommend [updating Qubes OS](/doc/how-to-update/) immediately after
 
 - Qubes 4.2.2 includes a fix for [#8332: File-copy qrexec service is overly restrictive](https://github.com/QubesOS/qubes-issues/issues/8332). As explained in the issue comments, we introduced a change in Qubes 4.2.0 that caused inter-qube file-copy/move actions to reject filenames containing, e.g., non-Latin characters and certain symbols. The rationale for this change was to mitigate the security risks associated with unusual unicode characters and invalid encoding in filenames, which some software might handle in an unsafe manner and which might cause confusion for users. Such a change represents a trade-off between security and usability.
   
-  After the change went live, we received several user reports indicating more severe usability problems than we had anticipated. Moreover, these problems were prompting users to resort to dangerous workarounds (such as packing files into an archive format prior to copying) that carry far more risk than the original risk posed by the unrestricted filenames. In addition, we realized that this was a backward-incompatible change that should not have been introduced in a minor release in the first place.
+  - After the change went live, we received several user reports indicating more severe usability problems than we had anticipated. Moreover, these problems were prompting users to resort to dangerous workarounds (such as packing files into an archive format prior to copying) that carry far more risk than the original risk posed by the unrestricted filenames. In addition, we realized that this was a backward-incompatible change that should not have been introduced in a minor release in the first place.
   
-  Therefore, we have decided, for the time being, to restore the original (pre-4.2) behavior by introducing a new `allow-all-names` argument for the `qubes.Filecopy` service. By default, `qvm-copy` and similar tools will use this less restrictive service (`qubes.Filecopy +allow-all-names`) whenever they detect any files that would be have been blocked by the more restrictive service (`qubes.Filecopy +`). If no such files are detected, they will use the more restrictive service.
+  - Therefore, we have decided, for the time being, to restore the original (pre-4.2) behavior by introducing a new `allow-all-names` argument for the `qubes.Filecopy` service. By default, `qvm-copy` and similar tools will use this less restrictive service (`qubes.Filecopy +allow-all-names`) whenever they detect any files that would be have been blocked by the more restrictive service (`qubes.Filecopy +`). If no such files are detected, they will use the more restrictive service.
   
-  Users who wish to opt for the more restrictive 4.2.0 and 4.2.1 behavior can do so by modifying their RPC policy rules. To switch a single rule to the more restrictive behavior, change `*` in the argument column to `+` (i.e., change "any argument" to "only empty"). To use the more restrictive behavior globally, add the following "deny" rule before all other relevant rules:
+  - Users who wish to opt for the more restrictive 4.2.0 and 4.2.1 behavior can do so by modifying their RPC policy rules. To switch a single rule to the more restrictive behavior, change `*` in the argument column to `+` (i.e., change "any argument" to "only empty"). To use the more restrictive behavior globally, add the following "deny" rule before all other relevant rules:
   
-  ```
+    ```
-  qubes.Filecopy    +allow-all-names    @anyvm    @anyvm    deny
+    qubes.Filecopy    +allow-all-names    @anyvm    @anyvm    deny
-  ```
+    ```
   
-  For more information, see [RPC policies](/doc/rpc-policy/) and [Qube configuration interface](/doc/vm-interface/#qubes-rpc).
+  - For more information, see [RPC policies](/doc/rpc-policy/) and [Qube configuration interface](/doc/vm-interface/#qubes-rpc).
 
 - Beginning with Qubes 4.2, the recommended way to update Qubes OS via the command line has changed. Salt is no longer the preferred method, though it is still supported. Instead, `qubes-dom0-update` is recommended for updating dom0, and `qubes-vm-update` is recommended for updating templates and standalones. (The recommended way to update via the GUI has not changed. The Qubes Update tool is still the preferred method.) For more information, see [How to update](/doc/how-to-update/).
 

developer/releases/version-scheme.md

@@ -71,7 +71,7 @@ When enough progress has been made, we announce the first stable release, e.g.
 `3.0.0`. This is not only a version but an actual release. It is considered
 stable, and we commit to supporting it according to our [support
 schedule](/doc/supported-releases/). Core components are branched at this
-moment, and bug fixes are backported from the master branch. Please see [help,
+moment, and bug fixes are backported from the main branch. Please see [help,
 support, mailing lists, and forum](/support/) for places to ask questions about
 stable releases. No major features or interface incompatibilities are to be
 included in this release. We release bug fixes as patch releases (`3.0.1`,
@@ -173,7 +173,7 @@ We mark each component version in the repository by tag containing
 
 At the release of some release we create branches named like `release2`. Only
 bug fixes and compatible improvements are backported to these branches. These
-branches should compile. All new development is done in `master` branch. This
+branches should compile. All new development is done in `main` branch. This
 branch is totally unsupported and may not even compile depending on maintainer
 of repository.
 

developer/services/admin-api.md

@@ -62,95 +62,100 @@ 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 |
+| call                                           | dest       | argument     | inside                                                              | return                                              | note |
-| ------------------------------------- | --------- | --------- | ----------------------------------------- | --------------------------------------------------------- | ---- |
+|------------------------------------------------|------------|--------------|---------------------------------------------------------------------|-----------------------------------------------------| ---- |
-| `admin.vmclass.List`                   | `dom0`    | -         | -                                         | `<class>\n`                                               |
+| `admin.vmclass.List`                           | `dom0`     | -            | -                                                                   | `<class>\n`                                         |
-| `admin.vm.List`                        | `dom0|<vm>` | -         | -                                         | `<name> class=<class> state=<state>\n`                    |
+| `admin.vm.List`                                | `dom0      | <vm>`        | -                                                                   | -                                                   | `<name> class=<class> state=<state>\n`                    |
-| `admin.vm.Create.<class>`              | `dom0`    | template  | `name=<name> label=<label>`               | -                                                         |
+| `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.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.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.vm.Remove`                              | vm         | -            | -                                                                   | -                                                   |
-| `admin.label.List`                     | `dom0`    | -         | -                                         | `<property>\n`                                            |
+| `admin.label.List`                             | `dom0`     | -            | -                                                                   | `<property>\n`                                      |
-| `admin.label.Create`                   | `dom0`    | label     | `0xRRGGBB`                                | -                                                         |
+| `admin.label.Create`                           | `dom0`     | label        | `0xRRGGBB`                                                          | -                                                   |
-| `admin.label.Get`                      | `dom0`    | label     | -                                         | `0xRRGGBB`                                                |
+| `admin.label.Get`                              | `dom0`     | label        | -                                                                   | `0xRRGGBB`                                          |
-| `admin.label.Index`                    | `dom0`    | label     | -                                         | `<label-index>`                                           |
+| `admin.label.Index`                            | `dom0`     | label        | -                                                                   | `<label-index>`                                     |
-| `admin.label.Remove`                   | `dom0`    | label     | -                                         | -                                                         |
+| `admin.label.Remove`                           | `dom0`     | label        | -                                                                   | -                                                   |
-| `admin.property.List`                  | `dom0`    | -         | -                                         | `<property>\n`                                            |
+| `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.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.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.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.Help`                          | `dom0`     | property     | -                                                                   | `help`                                              |
-| `admin.property.HelpRst`               | `dom0`    | property  | -                                         | `help.rst`                                                |
+| `admin.property.HelpRst`                       | `dom0`     | property     | -                                                                   | `help.rst`                                          |
-| `admin.property.Reset`                 | `dom0`    | property  | -                                         | -                                                         |
+| `admin.property.Reset`                         | `dom0`     | property     | -                                                                   | -                                                   |
-| `admin.property.Set`                   | `dom0`    | property  | value                                     | -                                                         |
+| `admin.property.Set`                           | `dom0`     | property     | value                                                               | -                                                   |
-| `admin.vm.property.List`               | vm        | -         | -                                         | `<property>\n`                                            |
+| `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.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.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.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.Help`                       | vm         | property     | -                                                                   | `help`                                              |
-| `admin.vm.property.HelpRst`            | vm        | property  | -                                         | `help.rst`                                                |
+| `admin.vm.property.HelpRst`                    | vm         | property     | -                                                                   | `help.rst`                                          |
-| `admin.vm.property.Reset`              | vm        | property  | -                                         | -                                                         |
+| `admin.vm.property.Reset`                      | vm         | property     | -                                                                   | -                                                   |
-| `admin.vm.property.Set`                | vm        | property  | value                                     | -                                                         |
+| `admin.vm.property.Set`                        | vm         | property     | value                                                               | -                                                   |
-| `admin.vm.feature.List`                | vm        | -         | -                                         | `<feature>\n`                                             |
+| `admin.vm.feature.List`                        | vm         | -            | -                                                                   | `<feature>\n`                                       |
-| `admin.vm.feature.Get`                 | vm        | feature   | -                                         | value                                                     |
+| `admin.vm.feature.Get`                         | vm         | feature      | -                                                                   | value                                               |
-| `admin.vm.feature.CheckWithTemplate`   | vm        | feature   | -                                         | value                                                     |
+| `admin.vm.feature.CheckWithTemplate`           | vm         | feature      | -                                                                   | value                                               |
-| `admin.vm.feature.CheckWithNetvm`      | vm        | feature   | -                                         | value                                                     |
+| `admin.vm.feature.CheckWithNetvm`              | vm         | feature      | -                                                                   | value                                               |
-| `admin.vm.feature.CheckWithAdminVM`    | vm        | feature   | -                                         | value                                                     |
+| `admin.vm.feature.CheckWithAdminVM`            | vm         | feature      | -                                                                   | value                                               |
-| `admin.vm.feature.CheckWithTemplateAndAdminVM`| vm | feature   | -                                         | value                                                     |
+| `admin.vm.feature.CheckWithTemplateAndAdminVM` | vm         | feature      | -                                                                   | value                                               |
-| `admin.vm.feature.Remove`              | vm        | feature   | -                                         | -                                                         |
+| `admin.vm.feature.Remove`                      | vm         | feature      | -                                                                   | -                                                   |
-| `admin.vm.feature.Set`                 | vm        | feature   | value                                     | -                                                         |
+| `admin.vm.feature.Set`                         | vm         | feature      | value                                                               | -                                                   |
-| `admin.vm.tag.List`                    | vm        | -         | -                                         | `<tag>\n`                                                 |
+| `admin.vm.notes.Get`                           | vm         | -            | -                                                                   | notes                                               |
-| `admin.vm.tag.Get`                     | vm        | tag       | -                                         | `0` or `1`                                                | retcode? |
+| `admin.vm.notes.Set`                           | vm         | -            | notes                                                               | -                                                   |
-| `admin.vm.tag.Remove`                  | vm        | tag       | -                                         | -                                                         |
+| `admin.vm.tag.List`                            | vm         | -            | -                                                                   | `<tag>\n`                                           |
-| `admin.vm.tag.Set`                     | vm        | tag       | -                                         | -                                                         |
+| `admin.vm.tag.Get`                             | vm         | tag          | -                                                                   | `0` or `1`                                          | retcode? |
-| `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.tag.Remove`                          | vm         | tag          | -                                                                   | -                                                   |
-| `admin.vm.firewall.Set`                | vm        | -         | `<rule>\n`                                | -                                                         | set firewall rules, see `admin.vm.firewall.Get` for syntax
+| `admin.vm.tag.Set`                             | vm         | tag          | -                                                                   | -                                                   |
-| `admin.vm.firewall.Reload`             | vm        | -         | -                                         | -                                                         | force reload firewall without changing any rule
+| `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.deviceclass.List`            | `dom0`    | -         | -                                         | `<class>\n`                                               |
+| `admin.vm.firewall.Set`                        | vm         | -            | `<rule>\n`                                                          | -                                                   | set firewall rules, see `admin.vm.firewall.Get` for syntax
-| `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.firewall.Reload`                     | vm         | -            | -                                                                   | -                                                   | force reload firewall without changing any rule
-| `admin.vm.device.<class>.Detach`       | vm        | device    | -                                         | -                                                         | `device` is in form `<backend-name>+<device-ident>`
+| `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>.Set.persistent`| vm       | device    | `True`\|`False`                            | -                                                         | `device` is in form `<backend-name>+<device-ident>`
+| `admin.vm.device.<class>.Detach`               | vm         | device       | -                                                                   | -                                                   | `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>.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>.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.vm.device.<class>.Unassign`             | vm         | device       | -                                                                   | -                                                   | `device` is in form `<backend-name>+<device-ident>`.
-| `admin.pool.List`                      | `dom0`    | -         | -                                         | `<pool>\n`                                                |
+| `admin.vm.device.<class>.Set.required`         | vm         | device       | `True`\|`False`                                                     | -                                                   | `device` is in form `<backend-name>+<device-ident>`
-| `admin.pool.ListDrivers`               | `dom0`    | -         | -                                         | `<pool-driver> <property> ...\n`                          | Properties allowed in `admin.pool.Add`
+| `admin.vm.deviceclass.List`                    | `dom0`     | -            | -                                                                   | `<deviceclass>\n`                                   |
-| `admin.pool.Info`                      | `dom0`    | pool      | -                                         | `<property>=<value>\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.pool.Add`                       | `dom0`    | driver    | `<property>=<value>\n`                    | -                                                         |
+| `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.pool.Set.revisions_to_keep`     | `dom0`    | pool      | `<value>`                                 | -                                                         |
+| `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.Remove`                    | `dom0`    | pool      | -                                         | -                                                         |
+| `admin.pool.List`                              | `dom0`     | -            | -                                                                   | `<pool>\n`                                          |
-| `admin.pool.volume.List`               | `dom0`    | pool      | -                                         | volume id                                                 |
+| `admin.pool.ListDrivers`                       | `dom0`     | -            | -                                                                   | `<pool-driver> <property> ...\n`                    | Properties allowed in `admin.pool.Add`
-| `admin.pool.volume.Info`               | `dom0`    | pool      | vid                                       | `<property>=<value>\n`                                    |
+| `admin.pool.Info`                              | `dom0`     | pool         | -                                                                   | `<property>=<value>\n`                              |
-| `admin.pool.volume.Set.revisions_to_keep`| `dom0`  | pool      | `<vid> <value>`                           | -                                                         |
+| `admin.pool.Add`                               | `dom0`     | driver       | `<property>=<value>\n`                                              | -                                                   |
-| `admin.pool.volume.ListSnapshots`      | `dom0`    | pool      | vid                                       | `<snapshot>\n`                                            |
+| `admin.pool.Set.revisions_to_keep`             | `dom0`     | pool         | `<value>`                                                           | -                                                   |
-| `admin.pool.volume.Snapshot`           | `dom0`    | pool      | vid                                       | snapshot                                                  |
+| `admin.pool.Remove`                            | `dom0`     | pool         | -                                                                   | -                                                   |
-| `admin.pool.volume.Revert`             | `dom0`    | pool      | `<vid> <snapshot>`                        | -                                                         |
+| `admin.pool.volume.List`                       | `dom0`     | pool         | -                                                                   | volume id                                           |
-| `admin.pool.volume.Resize`             | `dom0`    | pool      | `<vid> <size_in_bytes>`                   | -                                                         |
+| `admin.pool.volume.Info`                       | `dom0`     | pool         | vid                                                                 | `<property>=<value>\n`                              |
-| `admin.pool.volume.Import`             | `dom0`    | pool      | `<vid>\n<raw volume data>`                | -                                                         |
+| `admin.pool.volume.Set.revisions_to_keep`      | `dom0`     | pool         | `<vid> <value>`                                                     | -                                                   |
-| `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.ListSnapshots`              | `dom0`     | pool         | vid                                                                 | `<snapshot>\n`                                      |
-| `admin.pool.volume.CloneTo`            | `dom0`    | pool      | `<vid> <token>`                           | -                                                         | copy volume pointed by a token to volume `vid` in `pool` |
+| `admin.pool.volume.Snapshot`                   | `dom0`     | pool         | vid                                                                 | snapshot                                            |
-| `admin.vm.volume.List`                 | vm        | -         | -                                         | `<volume>\n`                                              | `<volume>` is per-VM volume name (`root`, `private`, etc), `<vid>` is pool-unique volume id
+| `admin.pool.volume.Revert`                     | `dom0`     | pool         | `<vid> <snapshot>`                                                  | -                                                   |
-| `admin.vm.volume.Info`                 | vm        | volume    | -                                         | `<property>=<value>\n`                                    |
+| `admin.pool.volume.Resize`                     | `dom0`     | pool         | `<vid> <size_in_bytes>`                                             | -                                                   |
-| `admin.vm.volume.Set.revisions_to_keep`| vm        | volume    | value                                     | -                                                         |
+| `admin.pool.volume.Import`                     | `dom0`     | pool         | `<vid>\n<raw volume data>`                                          | -                                                   |
-| `admin.vm.volume.ListSnapshots`        | vm        | volume    | -                                         | snapshot                                                  | duplicate of `admin.pool.volume.`, but with other call params |
+| `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.vm.volume.Snapshot`             | vm        | volume    | -                                         | snapshot                                                  | id. |
+| `admin.pool.volume.CloneTo`                    | `dom0`     | pool         | `<vid> <token>`                                                     | -                                                   | copy volume pointed by a token to volume `vid` in `pool` |
-| `admin.vm.volume.Revert`               | vm        | volume    | snapshot                                  | -                                                         | id. |
+| `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.Resize`               | vm        | volume    | size_in_bytes                             | -                                                         | id. |
+| `admin.vm.volume.Info`                         | vm         | volume       | -                                                                   | `<property>=<value>\n`                              |
-| `admin.vm.volume.Import`               | vm        | volume    | raw volume data                           | -                                                         | id. |
+| `admin.vm.volume.Set.revisions_to_keep`        | vm         | volume       | value                                                               | -                                                   |
-| `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.ListSnapshots`                | vm         | volume       | -                                                                   | snapshot                                            | duplicate of `admin.pool.volume.`, but with other call params |
-| `admin.vm.volume.Clear`                | vm        | volume    | -                                         | -                                                         | clear contents of volume |
+| `admin.vm.volume.Snapshot`                     | vm         | volume       | -                                                                   | snapshot                                            | id. |
-| `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.Revert`                       | vm         | volume       | snapshot                                                            | -                                                   | id. |
-| `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.volume.Resize`                       | vm         | volume       | size_in_bytes                                                       | -                                                   | id. |
-| `admin.vm.CurrentState`                | vm        | -         | -                                         | `<state-property>=<value>\n`                              | state properties: `power_state`, `mem`, `mem_static_max`, `cputime`
+| `admin.vm.volume.Import`                       | vm         | volume       | raw volume data                                                     | -                                                   | id. |
-| `admin.vm.Start`                       | vm        | -         | -                                         | -                                                         |
+| `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.Shutdown`                    | vm        | -         | -                                         | -                                                         |
+| `admin.vm.volume.Clear`                        | vm         | volume       | -                                                                   | -                                                   | clear contents of volume |
-| `admin.vm.Pause`                       | vm        | -         | -                                         | -                                                         |
+| `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.Unpause`                     | vm        | -         | -                                         | -                                                         |
+| `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.Kill`                        | vm        | -         | -                                         | -                                                         |
+| `admin.vm.CurrentState`                        | vm         | -            | -                                                                   | `<state-property>=<value>\n`                        | state properties: `power_state`, `mem`, `mem_static_max`, `cputime`
-| `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.vm.Start`                               | vm         | -            | -                                                                   | -                                                   |
-| `admin.backup.Info`                    | `dom0`    | config id | -                                         | backup info                                               | info what would be included in the backup
+| `admin.vm.Shutdown`                            | vm         | -            | -                                                                   | -                                                   |
-| `admin.backup.Cancel`                  | `dom0`    | config id | -                                         | -                                                         | cancel running backup operation
+| `admin.vm.Pause`                               | vm         | -            | -                                                                   | -                                                   |
-| `admin.Events`                         | `dom0|vm` | -         | -                                         | events                                                    |
+| `admin.vm.Unpause`                             | vm         | -            | -                                                                   | -                                                   |
-| `admin.vm.Stats`                       | `dom0|vm` | -         | -                                         | `vm-stats` events, see below                              | emit VM statistics (CPU, memory usage) in form of events
+| `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 +307,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

developer/services/dom0-secure-updates.md

@@ -33,7 +33,7 @@ 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.
 

developer/services/qfilecopy.md

@@ -24,6 +24,6 @@ This has the following disadvantages:
 
 In modern Qubes OS releases, we have reimplemented interVM file copy using qrexec, which addresses the above mentioned disadvantages. Nowadays, even more generic solution (qubes rpc) is used. See the developer docs on qrexec and qubes rpc. In a nutshell, the file sender and the file receiver just read/write from stdin/stdout, and the qubes rpc layer passes data properly - so, no block devices are used.
 
-The rpc action for regular file copy is *qubes.Filecopy*, the rpc client is named *qfile-agent*, the rpc server is named *qfile-unpacker*. For DispVM copy, the rpc action is *qubes.OpenInVM*, the rpc client is named *qopen-in-vm*, rpc server is named *vm-file-editor*. Note that the qubes.OpenInVM action can be done on a normal AppVM, too.
+The rpc action for regular file copy is *qubes.Filecopy*, the rpc client is named *qfile-agent*, the rpc server is named *qfile-unpacker*. For DispVM copy, the rpc action is *qubes.OpenInVM*, the rpc client is named *qopen-in-vm*, rpc server is named *vm-file-editor*. Note that the *qubes.OpenInVM* action can be done on a normal AppVM, too.
 
 Being a rpc server, *qfile-unpacker* must be coded securely, as it processes potentially untrusted data format. Particularly, we do not want to use external tar or cpio and be prone to all vulnerabilities in them; we want a simplified, small utility, that handles only directory/file/symlink file type, permissions, mtime/atime, and assume user/user ownership. In the current implementation, the code that actually parses the data from srcVM has ca 100 lines of code and executes chrooted to the destination directory. The latter is hardcoded to `~user/QubesIncoming/srcVM`; because of chroot, there is no possibility to alter files outside of this directory.

developer/services/qmemman.md

@@ -15,7 +15,7 @@ Rationale
 
 Traditionally, Xen VMs are assigned a fixed amount of memory. It is not the optimal solution, as some VMs may require more memory than assigned initially, while others underutilize memory. Thus, there is a need for solution capable of shifting free memory from VM to another VM.
 
-The [tmem](https://oss.oracle.com/projects/tmem/) project provides a "pseudo-RAM" that is assigned on per-need basis. However this solution has some disadvantages:
+The [tmem](https://web.archive.org/web/20210712161104/https://oss.oracle.com/projects/tmem/) project provides a "pseudo-RAM" that is assigned on per-need basis. However this solution has some disadvantages:
 
 - It does not provide real RAM, just an interface to copy memory to/from fast, RAM-based storage. It is perfect for swap, good for file cache, but not ideal for many tasks.
 - It is deeply integrated with the Linux kernel. When Qubes will support Windows guests natively, we would have to port *tmem* to Windows, which may be challenging.
@@ -24,13 +24,19 @@ Therefore, in Qubes another solution is used. There is the *qmemman* dom0 daemon
 
 Similarly, when there is need for Xen free memory (for instance, in order to create a new VM), traditionally the memory is obtained from dom0 only. When *qmemman* is running, it offers an interface to obtain memory from all domains.
 
-To sum up, *qmemman* pros and cons. Pros:
+To sum up, *qmemman* pros and cons.
+
+<div class="focus">
+  <i class="fa fa-check"></i> <strong>Pros</strong>
+</div>
 
 - provides automatic balancing of memory across participating PV and HVM domains, based on their memory demand
 - works well in practice, with less than 1% CPU consumption in the idle case
 - simple, concise implementation
 
-Cons:
+<div class="focus">
+  <i class="fa fa-times"></i> <strong>Cons</strong>
+</div>
 
 - the algorithm to calculate the memory requirement for a domain is necessarily simple, and may not closely reflect reality
 - *qmemman* is notified by a VM about memory usage change not more often than 10 times per second (to limit CPU overhead in VM). Thus, there can be up to 0.1s delay until qmemman starts to react to the new memory requirements

developer/services/qrexec-internals.md

@@ -122,25 +122,25 @@ Details of all possible use cases and the messages involved are described below.
 
       qrexec-client -d domX [-l local_program] user:cmd
 
-  (If `local_program` is set, `qrexec-client` executes it and uses that child's stdin/stdout in place of its own when exchanging data with `qrexec-agent` later.)
+  - (If `local_program` is set, `qrexec-client` executes it and uses that child's stdin/stdout in place of its own when exchanging data with `qrexec-agent` later.)
 
-  `qrexec-client` translates that request into a `MSG_EXEC_CMDLINE` message sent to `qrexec-daemon`, with `connect_domain` set to 0 (connect to **dom0**) and `connect_port also set to 0 (allocate a port).
+  - `qrexec-client` translates that request into a `MSG_EXEC_CMDLINE` message sent to `qrexec-daemon`, with `connect_domain` set to 0 (connect to **dom0**) and `connect_port` also set to 0 (allocate a port).
 
 - **dom0**: `qrexec-daemon` allocates a free port (in this case 513), and sends a `MSG_EXEC_CMDLINE` back to the client with connection parameters (**domX** and 513) and with command field empty.
 
-  `qrexec-client` disconnects from the daemon, starts a vchan server on port 513 and awaits connection.
+  - `qrexec-client` disconnects from the daemon, starts a vchan server on port 513 and awaits connection.
 
-  Then, `qrexec-daemon` passes on the request as `MSG_EXEC_CMDLINE` message to the `qrexec-agent` running in **domX**. In this case, the connection parameters are **dom0** and 513.
+  - Then, `qrexec-daemon` passes on the request as `MSG_EXEC_CMDLINE` message to the `qrexec-agent` running in **domX**. In this case, the connection parameters are **dom0** and 513.
 
 - **domX**: `qrexec-agent` receives `MSG_EXEC_CMDLINE`, and starts the command (`user:cmd`, or `cmd` as user `user`). If possible, this is actually delegated to a separate server (`qrexec-fork-server`) also running on domX.
 
-  After starting the command, `qrexec-fork-server` connects to `qrexec-client` in **dom0** over the provided vchan port 513.
+  - After starting the command, `qrexec-fork-server` connects to `qrexec-client` in **dom0** over the provided vchan port 513.
 
 - Data is forwarded between the `qrexec-client` in **dom0** and the command executed in **domX** using `MSG_DATA_STDIN`, `MSG_DATA_STDOUT` and `MSG_DATA_STDERR`.
 
-  Empty messages (with data `len` field set to 0 in `msg_header`) are an EOF marker. Peer receiving such message should close the associated input/output pipe.
+  - Empty messages (with data `len` field set to 0 in `msg_header`) are an EOF marker. Peer receiving such message should close the associated input/output pipe.
 
-  When `cmd` terminates, **domX**'s `qrexec-fork-server` sends `MSG_DATA_EXIT_CODE` header to `qrexec-client` followed by the exit code (**int**).
+  - When `cmd` terminates, **domX**'s `qrexec-fork-server` sends `MSG_DATA_EXIT_CODE` header to `qrexec-client` followed by the exit code (**int**).
 
 ### domX: request execution of service `admin.Service` in dom0
 
@@ -150,41 +150,41 @@ Details of all possible use cases and the messages involved are described below.
 
       qrexec-client-vm dom0 admin.Service [local_program] [params]
 
-  (If `local_program` is set, it will be executed in **domX** and connected to the remote command's stdin/stdout).
+  - (If `local_program` is set, it will be executed in **domX** and connected to the remote command's stdin/stdout).
 
-  `qrexec-client-vm` connects to `qrexec-agent` and requests service execution (`admin.Service`) in **dom0**.
+  - `qrexec-client-vm` connects to `qrexec-agent` and requests service execution (`admin.Service`) in **dom0**.
 
-  `qrexec-agent` assigns an internal identifier to the request. It's based on a file descriptor of the connected `qrexec-client-vm`: in this case, `SOCKET11`.
+  - `qrexec-agent` assigns an internal identifier to the request. It's based on a file descriptor of the connected `qrexec-client-vm`: in this case, `SOCKET11`.
 
-  `qrexec-agent` forwards the request (`MSG_TRIGGER_SERVICE3`) to its corresponding `qrexec-daemon` running in dom0.
+  - `qrexec-agent` forwards the request (`MSG_TRIGGER_SERVICE3`) to its corresponding `qrexec-daemon` running in dom0.
 
 - **dom0**: `qrexec-daemon` receives the request and triggers `qrexec-policy` program, passing all necessary parameters: source domain **domX**, target domain **dom0**, service `admin.Service` and identifier `SOCKET11`.
 
-  `qrexec-policy` evaluates if the RPC should be allowed or denied, possibly also launching a GUI confirmation prompt.
+  - `qrexec-policy` evaluates if the RPC should be allowed or denied, possibly also launching a GUI confirmation prompt.
 
-  (If the RPC is denied, it returns with exit code 1, in which case `qrexec-daemon` sends a `MSG_SERVICE_REFUSED` back).
+  - (If the RPC is denied, it returns with exit code 1, in which case `qrexec-daemon` sends a `MSG_SERVICE_REFUSED` back).
 
 - **dom0**: If the RPC is allowed, `qrexec-policy` will launch a `qrexec-client` with the right command:
 
       qrexec-client -d dom0 -c domX,X,SOCKET11 "QUBESRPC admin.Service domX name dom0"
 
-  The `-c domX,X,SOCKET11` are parameters indicating how connect back to **domX** and pass its input/output.
+  - The `-c domX,X,SOCKET11` are parameters indicating how connect back to **domX** and pass its input/output.
 
-  The command parameter describes the RPC call: it contains service name (`admin.Service`), source domain (`domX`) and target description (`name dom0`, could also be e.g. `keyword @dispvm`). The target description is important in case the original target wasn't dom0, but the service is executing in dom0.
+  - The command parameter describes the RPC call: it contains service name (`admin.Service`), source domain (`domX`) and target description (`name dom0`, could also be e.g. `keyword @dispvm`). The target description is important in case the original target wasn't dom0, but the service is executing in dom0.
 
-  `qrexec-client` connects to a `qrexec-daemon` for **domX** and sends a `MSG_SERVICE_CONNECT` with connection parameters (**dom0**, and port 0, indicating a port should be allocated) and request identifier (`SOCKET11`).
+  - `qrexec-client` connects to a `qrexec-daemon` for **domX** and sends a `MSG_SERVICE_CONNECT` with connection parameters (**dom0**, and port 0, indicating a port should be allocated) and request identifier (`SOCKET11`).
 
-  `qrexec-daemon` allocates a free port (513) and sends back connection parameters to `qrexec-client` (**domX** port 513).
+  - `qrexec-daemon` allocates a free port (513) and sends back connection parameters to `qrexec-client` (**domX** port 513).
 
-  `qrexec-client` starts the command, and tries to connect to **domX** over the provided port 513.
+  - `qrexec-client` starts the command, and tries to connect to **domX** over the provided port 513.
 
-  Then, `qrexec-daemon` forwards the connection request (`MSG_SERVICE_CONNECT`) to `qrexec-agent` running in **domX**, with the right parameters (**dom0** port 513, request `SOCKET11`).
+  - Then, `qrexec-daemon` forwards the connection request (`MSG_SERVICE_CONNECT`) to `qrexec-agent` running in **domX**, with the right parameters (**dom0** port 513, request `SOCKET11`).
 
 - **dom0**: Because the command has the form `QUBESRPC: ...`, it is started through the `qubes-rpc-multiplexer` program with the provided parameters (`admin.Service domX name dom0`). That program finds and executes the necessary script in `/etc/qubes-rpc/`.
 
 - **domX**: `qrexec-agent` receives the `MSG_SERVICE_CONNECT` and passes the connection parameters back to the connected `qrexec-client-vm`. It identifies the `qrexec-client-vm` by the request identifier (`SOCKET11` means file descriptor 11).
 
-  `qrexec-client-vm` starts a vchan server on 513 and receives a connection from `qrexec-client`.
+  - `qrexec-client-vm` starts a vchan server on 513 and receives a connection from `qrexec-client`.
 
 - Data is forwarded between **dom0** and **domX** as in the previous example (dom0-VM).
 
@@ -196,37 +196,37 @@ Details of all possible use cases and the messages involved are described below.
 
       qrexec-client-vm domY qubes.Service [local_program] [params]
 
-  (If `local_program` is set, it will be executed in **domX** and connected to the remote command's stdin/stdout).
+  - (If `local_program` is set, it will be executed in **domX** and connected to the remote command's stdin/stdout).
 
 - The request is forwarded as `MSG_TRIGGER_SERVICE3` to `qrexec-daemon` running in **dom0**, then to `qrexec-policy`, then (if allowed) to `qrexec-client`.
 
-  This is the same as in the previous example (VM-dom0).
+  - This is the same as in the previous example (VM-dom0).
 
 - **dom0**: If the RPC is allowed, `qrexec-policy` will launch a `qrexec-client` with the right command:
 
       qrexec-client -d domY -c domX,X,SOCKET11 user:cmd "DEFAULT:QUBESRPC qubes.Service domX"
 
-  The `-c domX,X,SOCKET11` are parameters indicating how connect back to **domX** and pass its input/output.
+  - The `-c domX,X,SOCKET11` are parameters indicating how connect back to **domX** and pass its input/output.
 
-  The command parameter describes the service call: it contains the username (or `DEFAULT`), service name (`qubes.Service`) and source domain (`domX`).
+  - The command parameter describes the service call: it contains the username (or `DEFAULT`), service name (`qubes.Service`) and source domain (`domX`).
 
-  `qrexec-client` will then send a `MSG_EXEC_CMDLINE` message to `qrexec-daemon` for **domY**. The message will be with port number 0, requesting port allocation.
+  - `qrexec-client` will then send a `MSG_EXEC_CMDLINE` message to `qrexec-daemon` for **domY**. The message will be with port number 0, requesting port allocation.
 
-  `qrexec-daemon` for **domY** will allocate a port (513) and send it back. It will also send a `MSG_EXEC_CMDLINE` to its corresponding agent. (It will also translate `DEFAULT` to the configured default username).
+  - `qrexec-daemon` for **domY** will allocate a port (513) and send it back. It will also send a `MSG_EXEC_CMDLINE` to its corresponding agent. (It will also translate `DEFAULT` to the configured default username).
 
-  Then, `qrexec-client` will also send `MSG_SERVICE_CONNECT` message to **domX**'s agent, indicating that it should connect to **domY** over port 513.
+  - Then, `qrexec-client` will also send `MSG_SERVICE_CONNECT` message to **domX**'s agent, indicating that it should connect to **domY** over port 513.
 
-  Having notified both domains about a connection, `qrexec-client` now exits.
+  - Having notified both domains about a connection, `qrexec-client` now exits.
 
 - **domX**: `qrexec-agent` receives a `MSG_SERVICE_CONNECT` with connection parameters (**domY** port 513) and request identifier (`SOCKET11`). It sends the connection parameters back to the right `qrexec-client-vm`.
 
-  `qrexec-client-vm` starts a vchan server on port 513. note that this is different than in the other examples: `MSG_SERVICE_CONNECT` means you should start a server, `MSG_EXEC_CMDLINE` means you should start a client.
+  - `qrexec-client-vm` starts a vchan server on port 513. note that this is different than in the other examples: `MSG_SERVICE_CONNECT` means you should start a server, `MSG_EXEC_CMDLINE` means you should start a client.
 
 - **domY**: `qrexec-agent` receives a `MSG_EXEC_CMDLINE` with the command to execute (`user:QUBESRPC...`) and connection parameters (**domX** port 513).
 
-  It forwards the request to `qrexec-fork-server`, which handles the command and connects to **domX** over the provided port.
+  - It forwards the request to `qrexec-fork-server`, which handles the command and connects to **domX** over the provided port.
 
-  Because the command is of the form `QUBESRPC ...`, `qrexec-fork-server` starts it using `qubes-rpc-multiplexer` program, which finds and executes the necessary script in `/etc/qubes-rpc/`.
+  - Because the command is of the form `QUBESRPC ...`, `qrexec-fork-server` starts it using `qubes-rpc-multiplexer` program, which finds and executes the necessary script in `/etc/qubes-rpc/`.
 
 - After that, the data is passed between **domX** and **domY** as in the previous examples (dom0-VM, VM-dom0).
 
@@ -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.

developer/services/qrexec-socket-services.md

@@ -62,6 +62,7 @@ See the below example.
 
 `qrexec-policy-agent` is the program that handles "ask" prompts for Qubes RPC calls.
 It is a good example of an application that:
+
 * Uses Python and asyncio.
 * Runs as a daemon, to save some overhead on starting process.
 * Runs as a normal user.

developer/services/qrexec.md

@@ -250,7 +250,6 @@ This means it is possible to install a different script for a particular service
 
 See [below](#rpc-service-with-argument-file-reader) for an example of an RPC service using an argument.
 
-<!-- TODO document "Yes to All" authorization if it is reintroduced -->
 
 ## Qubes RPC examples
 

developer/services/qrexec2.md

@@ -17,7 +17,7 @@ Qubes **qrexec** is a framework for implementing inter-VM (incl. Dom0-VM)
 services. It offers a mechanism to start programs in VMs, redirect their
 stdin/stdout, and a policy framework to control this all.
 
-## Qrexec basics ##
+## Qrexec basics
 
 During each domain creation a process named `qrexec-daemon` is started in
 dom0, and a process named `qrexec-agent` is started in the VM. They are
@@ -56,7 +56,7 @@ There is a similar command line utility available inside Linux AppVMs (note
 the `-vm` suffix): `qrexec-client-vm` that will be described in subsequent
 sections.
 
-## Qubes RPC services ##
+## Qubes RPC services
 
 Apart from simple Dom0-\>VM command executions, as discussed above, it is
 also useful to have more advanced infrastructure for controlled inter-VM
@@ -90,7 +90,7 @@ themselves. Qrexec framework is careful about connecting the stdin/stdout
 of the server process with the corresponding stdin/stdout of the requesting
 process in the requesting VM (see example Hello World service described below).
 
-## Qubes RPC administration ##
+## Qubes RPC administration
 
 Besides each VM needing to provide explicit programs to serve each supported
 service, the inter-VM service RPC is also governed by a central policy in Dom0.
@@ -135,7 +135,7 @@ if still there is no policy file after prompting, the action is denied.
 On the target VM, the `/etc/qubes-rpc/XYZ` must exist, containing the file
 name of the program that will be invoked.
 
-### Requesting VM-VM (and VM-Dom0) services execution ###
+### Requesting VM-VM (and VM-Dom0) services execution
 
 In a src VM, one should invoke the qrexec client via the following command:
 
@@ -161,7 +161,7 @@ If requesting VM-VM (and VM-Dom0) services execution *without cmdline helper*,
 connect directly to `/var/run/qubes/qrexec-agent-fdpass` socket as described
 [below](#all-the-pieces-together-at-work).
 
-### Revoking "Yes to All" authorization ###
+### Revoking "Yes to All" authorization
 
 Qubes RPC policy supports an "ask" action, that will prompt the user whether
 a given RPC call should be allowed. It is set as default for services such
@@ -184,7 +184,7 @@ A user might also want to set their own policies in this section. This may
 mostly serve to prevent the user from mistakenly copying files or text from
 a trusted to untrusted domain, or vice-versa.
 
-### Qubes RPC "Hello World" service ###
+### Qubes RPC "Hello World" service
 
 We will show the necessary files to create a simple RPC call that adds two
 integers on the target VM and returns back the result to the invoking VM.
@@ -232,7 +232,7 @@ be allowed.
 **Note:** For a real world example of writing a qrexec service, see this
 [blog post](https://blog.invisiblethings.org/2013/02/21/converting-untrusted-pdfs-into-trusted.html).
 
-### More high-level RPCs? ###
+### More high-level RPCs?
 
 As previously noted, Qubes aims to provide mechanisms that are very simple
 and thus with very small attack surface. This is the reason why the inter-VM
@@ -242,14 +242,14 @@ users/app developers are always free to run more high-level RPC protocols on
 top of qrexec. Care should be taken, however, to consider potential attack
 surfaces that are exposed to untrusted or less trusted VMs in that case.
 
-# Qubes RPC internals #
+## Qubes RPC internals
 
 (*This is about the implementation of qrexec v2. For the implementation of
 qrexec v3, see [here](/doc/qrexec-internals/). Note that the user
 API in v3 is backward compatible: qrexec apps written for Qubes R2 should
 run without modification on Qubes R3.*)
 
-## Dom0 tools implementation ##
+## Dom0 tools implementation
 
 Players:
 
@@ -262,7 +262,7 @@ Players:
 
 **Note:** None of the above tools are designed to be used by users.
 
-## Linux VMs implementation ##
+## Linux VMs implementation
 
 Players:
 
@@ -275,7 +275,7 @@ Players:
 **Note:** None of the above tools are designed to be used by
 users. `qrexec-client-vm` is designed to be wrapped up by Qubes apps.
 
-## Windows VMs implementation ##
+## Windows VMs implementation
 
 `%QUBES_DIR%` is the installation path (`c:\Program Files\Invisible Things
 Lab\Qubes OS Windows Tools` by default).
@@ -291,7 +291,7 @@ Lab\Qubes OS Windows Tools` by default).
 **Note:** None of the above tools are designed to be used by
 users. `qrexec-client-vm` is designed to be wrapped up by Qubes apps.
 
-## All the pieces together at work ##
+## All the pieces together at work
 
 **Note:** This section is not needed to use qrexec for writing Qubes
 apps. Also note the [qrexec framework implemention in Qubes R3](/doc/qrexec3/)

developer/system/gui.md

@@ -16,8 +16,8 @@ title: GUI virtualization
 
 All AppVM X applications connect to local (running in AppVM) Xorg servers that use the following "hardware" drivers:
 
-- *`dummyqsb_drv`* - video driver, that paints onto a framebuffer located in RAM, not connected to real hardware
+- `dummyqsb_drv` - video driver, that paints onto a framebuffer located in RAM, not connected to real hardware
-- *`qubes_drv`* - it provides a virtual keyboard and mouse (in fact, more, see below)
+- `qubes_drv` - it provides a virtual keyboard and mouse (in fact, more, see below)
 
 For each AppVM, there is a pair of `qubes-gui` (running in AppVM) and `qubes-guid` (running in the AppVM’s GuiVM, dom0 by default) processes connected over vchan.
 The main responsibilities of `qubes-gui` are:
@@ -119,7 +119,7 @@ AppVM -> GuiVM messages
 Proper handling of the below messages is security-critical.
 Note that all messages except for `CLIPBOARD`, `MFNDUMP`, and `WINDOW_DUMP` have fixed size, so the parsing code can be small.
 
-The `override_redirect` window attribute is explained at [Override Redirect Flag](https://tronche.com/gui/x/xlib/window/attributes/override-redirect.html). The `transient_for` attribute is explained at [`transient_for` attribute](https://tronche.com/gui/x/icccm/sec-4.html#WM_TRANSIENT_FOR).
+The `override_redirect` window attribute is explained at [Override Redirect Flag](https://tronche.com/gui/x/xlib/window/attributes/override-redirect.html). The `transient_for` attribute is explained at `transient_for` [attribute](https://tronche.com/gui/x/icccm/sec-4.html#WM_TRANSIENT_FOR).
 
 Window manager hints and flags are described in the [Extended Window Manager Hints (EWMH) spec](https://standards.freedesktop.org/wm-spec/latest/), especially under the `_NET_WM_STATE` section.
 

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.
+

developer/system/template-implementation.md

@@ -27,7 +27,7 @@ This is mounted as /rw and here is placed all VM private data. This includes:
 - */usr/local* – which is symlink to /rw/usrlocal
 - some config files (/rw/config) called by qubes core scripts (ex /rw/config/rc.local)
 
-**Note:** Whenever a TemplateBasedVM is created, the contents of the `/home` directory of its parent TemplateVM [are *not* copied to the child TemplateBasedVM's `/home`](/doc/templates/#inheritance-and-persistence). The child TemplateBasedVM's `/home` is independent from its parent TemplateVM's `/home`, which means that any changes to the parent TemplateVM's `/home` will not affect the child TemplateBasedVM's `/home`. Once a TemplateBasedVM has been created, any changes in its `/home`, `/usr/local`, or `/rw/config` directories will be persistent across reboots, which means that any files stored there will still be available after restarting the TemplateBasedVM. No changes in any other directories in TemplateBasedVMs persist in this manner. If you would like to make changes in other directories which *do* persist in this manner, you must make those changes in the parent TemplateVM.
+**Note:** Whenever a TemplateBasedVM is created, the contents of the `/home` directory of its parent TemplateVM are *not* copied to the [child TemplateBasedVM's](/doc/templates/#inheritance-and-persistence) `/home`. The child TemplateBasedVM's `/home` is independent from its parent TemplateVM's `/home`, which means that any changes to the parent TemplateVM's `/home` will not affect the child TemplateBasedVM's `/home`. Once a TemplateBasedVM has been created, any changes in its `/home`, `/usr/local`, or `/rw/config` directories will be persistent across reboots, which means that any files stored there will still be available after restarting the TemplateBasedVM. No changes in any other directories in TemplateBasedVMs persist in this manner. If you would like to make changes in other directories which *do* persist in this manner, you must make those changes in the parent TemplateVM.
 
 ### modules.img (xvdd)
 

developer/system/template-manager.md

@@ -23,7 +23,7 @@ specifically override the changes.) Other operations that work well on normal
 VMs are also somewhat inconsistent on RPM-managed templates. This includes
 actions such as renaming
 ([#839](https://github.com/QubesOS/qubes-issues/issues/839)), removal
-([#5509](https://github.com/QubesOS/qubes-issues/issues/5509)) and
+([#5509](https://web.archive.org/web/20210526123932/https://github.com/QubesOS/qubes-issues/issues/5509)) and
 backup/restore ([#1385](https://github.com/QubesOS/qubes-issues/issues/1385),
 [#1453](https://github.com/QubesOS/qubes-issues/issues/1453), [discussion
 thread

introduction/faq.md

@@ -144,7 +144,7 @@ Briefly, here are some of the main pros and cons of this approach relative to Qu
   (For example, you might find it natural to lock your secure laptop in a safe when you take your unsecure laptop out with you.)
 
 <div class="focus">
-    <i class="fa fa-times"></i> <strong>Cons</strong>
+  <i class="fa fa-times"></i> <strong>Cons</strong>
 </div>
 
 - Physical separation can be cumbersome and expensive, since we may have to obtain and set up a separate physical machine for each security level we need.
@@ -190,7 +190,7 @@ By default, Qubes OS uses [LUKS](https://en.wikipedia.org/wiki/Linux_Unified_Key
 
 ### What do all these terms mean?
 
-All Qubes-specific terms are defined in the [glossary](/doc/glossary/)
+All Qubes-specific terms are defined in the [glossary](/doc/glossary/).
 
 ### Does Qubes run every app in a separate VM?
 
@@ -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?
 

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
+Qubes OS is an operating system built out of securely-isolated compartments, or [qubes](/doc/glossary/#qube). 
-called [qubes](/doc/glossary/#qube). For example, you might have a work qube, a
+You can have a work qube, a personal qube, a banking qube, a web browsing qube, a standalone Windows qube and so on. 
-personal qube, a banking qube, a web browsing qube, and so on. You can have as
+You can have as many qubes as you want! Most of the time, you'll be using an [app
-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
-qube](/doc/glossary/#app-qube), which is a qube intended 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 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
@@ -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
+have to install the web browser a single time, and updating the template updates all the qubes based on it. 
-to update all the qubes based on it. This elegant design saves time and space
+This elegant design saves time and space while enhancing security.
-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,25 @@ 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
+qube](/doc/glossary/#admin-qube) used to administer your entire system. 
-administer your entire system. There's only one admin qube, and it's called
+There's only one admin qube, and it's called [dom0](/doc/glossary/#dom0). 
-[dom0](/doc/glossary/#dom0). You can think of it as the master qube, holding
+You can think of it as the master qube, holding ultimate power over everything that happens in Qubes OS. 
-ultimate power over everything that happens in Qubes OS. Dom0 is more trusted
+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.
-than any other qube. If dom0 were ever compromised, it would be "game over."
+That's why everything in Qubes OS is specifically designed to protect dom0 and ensure that doesn't
-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
 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, be very careful when interacting with dom0.
 
 ### 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
+colors. The color of the frame of each window on your desktop will correspond to the color of that qube. 
-the color of that qube. These colored frames help you keep track of which qube
+These colored frames help you keep track of which qube you're currently using.
-each window belongs to and how trustworthy it is. This is especially helpful
+You may use them to show how trustworthy it is. This is especially helpful
-when you have the same app running in multiple qubes at the same time. For
+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 +79,16 @@ mistakes.
 [![snapshot_41.png](/attachment/doc/r4.1-snapshot_40.png)](/attachment/doc/r4.1-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
+stop light signalling danger), green with what's safe and trusted, and yellow and
-orange with things in the middle. This color scheme also extends to include
+orange with things in-between. This color scheme also includes
-blue and black, which are usually interpreted as indicating progressively more
+blue and black, commonly interpreted as indicating progressively more
-trusted domains than green, with black being ultimately trusted. Color and
+trusted domains than green, with black being ultimately trusted. However, color and
-associated meanings are ultimately up to you, however. The system itself does
+associated meanings are entirely up to you. The system itself does
-not treat the colors differently. If you create two identical qubes --- black
+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 +100,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 **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.
-
-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/).
 
 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 +129,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 see all of your qubes at the same time, you can use the **Qube Manager**. 
-to the App Menu → Qubes Tools → Qube Manager), which displays the states of
+It displays the states of all the qubes in your system, even the ones that aren’t running.
-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.1-qubes-manager.png](/attachment/doc/r4.1-qubes-manager.png)](/attachment/doc/r4.1-qubes-manager.png)
 
 #### Command-line interface
 
-All aspects of Qubes OS can be controlled using command-line tools. Opening a
+All aspects of Qubes OS can be controlled using command-line tools such as the terminal emulator. 
-terminal emulator in dom0 can be done in several ways:
+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`.
+- 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
+Various command-line tools are described as part of this guide, and the whole reference can be found [here](/doc/tools/).
-command-line tools are described as part of this guide, and the whole reference
+Terminal emulators can also be run in other qubes as normal programs. 
-can be found [here](/doc/tools/).
 
 ## 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
+Other software installed in Qubes OS by default includes open-source applications such as file managers, 
-terminals, printer managers, text editors, and "applets" used to configure
+command-line terminals, printer managers, text editors, and applets for configuring audio and user interface settings.
-different things like audio or parts of the user interface are also installed
+Most of these applications are incorporated within each template.
-by default—most within the templates. Most are bundled with each template.
 
 ### Adding, removing, and listing qubes
 
-You can easily create a new qube with the **Create Qubes VM** option in the App
+To create a new qube or remove one, use **Create Qubes VM** option in the App Menu.
-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
+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 +188,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
+It's a good idea to start out with the pre-installed app qubes: `work`, `personal`, `untrusted`, and `vault`. 
-the structure of your digital life, and this is at least a little different for
+If you start to feel that some activity just doesn't fit into any of your existing qubes, or
-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
 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 +246,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/)!

introduction/screenshots.md

@@ -61,6 +61,7 @@ Qubes is all about seamless integration from the user’s point of view. Here yo
 [![r4.0-manager-and-sysnet-network-prompt.png](/attachment/doc/r4.0-manager-and-sysnet-network-prompt.png)](/attachment/doc/r4.0-manager-and-sysnet-network-prompt.png)
 
 All the networking runs in a special, unprivileged NetVM. (Notice the red frame around the Network Manager dialog box on the screen above.) This means that in the event that your network card driver, Wi-Fi stack, or DHCP client is compromised, the integrity of the rest of the system will not be affected! This feature requires Intel VT-d or AMD IOMMU hardware (e.g., Core i5/i7 systems)
+
 * * * * *
 
 [![r4.0-software-update.png](/attachment/doc/r4.0-software-update.png)](/attachment/doc/r4.0-software-update.png)

introduction/support.md

@@ -499,10 +499,11 @@ too](https://forum.qubes-os.org/t/using-the-forum-via-email/533)!)
 
 The Qubes OS Project has a presence on the following social media platforms:
 
-- <a rel="me" href="https://twitter.com/QubesOS">Twitter</a>
+- [Twitter](https://twitter.com/QubesOS)
-- <a rel="me" href="https://mastodon.social/@QubesOS">Mastodon</a>
+- [Mastodon](https://mastodon.social/@QubesOS)
-- <a rel="me" href="https://www.reddit.com/r/Qubes/">Reddit</a>
+- [Reddit](https://www.reddit.com/r/Qubes/)
-- <a rel="me" href="https://www.linkedin.com/company/qubes-os/">LinkedIn</a>
+- [Facebook](https://www.facebook.com/QubesOS/)
+- [LinkedIn](https://www.linkedin.com/company/qubes-os/)
 
 Generally speaking, these are not intended to be primary support venues. (Those
 would be [qubes-users](#qubes-users) and the [forum](#forum).) Rather, these
@@ -514,6 +515,7 @@ news.
 ## Chat
 
 If you'd like to chat, join us on
+
 - the `#qubes` channel on `irc.libera.chat` or
 - the `#qubes:invisiblethingslab.com` matrix channel.
 

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>

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/))

project-security/verifying-signatures.md

@@ -833,6 +833,7 @@ the arguments to `gpg2`. (The signature file goes first.)
 ### Why am I getting "WARNING: This key is not certified with a trusted signature! There is no indication that the signature belongs to the owner."?
 
 There are several possibilities:
+
 - You don't have the [Qubes Master Signing
   Key](#how-to-import-and-authenticate-the-qubes-master-signing-key).
 - You have not [set the Qubes Master Signing Key's trust level

user/advanced-topics/bind-dirs.md

@@ -8,21 +8,20 @@ ref: 186
 title: How to make any file persistent (bind-dirs)
 ---
 
-## What are bind-dirs? ##
+## What are bind-dirs?
 
 With [bind-dirs](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/vm-systemd/bind-dirs.sh)
 any arbitrary files or folders can be made persistent in app qubes.
 
-## What is it useful for? ##
+## What is it useful for?
 
 In an app qube all of the file system comes from the template except `/home`, `/usr/local`, and `/rw`.
 This means that changes in the rest of the filesystem are lost when the app qube is shutdown.
 bind-dirs provides a mechanism whereby files usually taken from the template can be persisted across reboots.
 
-For example, in Whonix, [Tor's data dir `/var/lib/tor` has been made persistent in the TemplateBased ProxyVM sys-whonix](https://github.com/Whonix/qubes-whonix/blob/8438d13d75822e9ea800b9eb6024063f476636ff/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf#L5)
+For example, in Whonix, Tor's data dir `/var/lib/tor` [has been made persistent in the TemplateBased ProxyVM sys-whonix](https://github.com/Whonix/qubes-whonix/blob/8438d13d75822e9ea800b9eb6024063f476636ff/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf#L5). In this way sys-whonix can benefit from the Tor anonymity feature 'persistent Tor entry guards' but does not have to be a standalone.
-In this way sys-whonix can benefit from the Tor anonymity feature 'persistent Tor entry guards' but does not have to be a standalone.
 
-## How to use bind-dirs.sh? ##
+## How to use bind-dirs.sh?
 
 In this example, we want to make `/var/lib/tor` persistent. Enter all of the following commands in your app qube.
 
@@ -68,13 +67,13 @@ binds+=( '/var/lib/tor' )
 binds+=( '/etc/tor/torrc' )
 ```
 
-## Other Configuration Folders ##
+## Other Configuration Folders
 
 * `/usr/lib/qubes-bind-dirs.d` (lowest priority, for packages)
 * `/etc/qubes-bind-dirs.d`  (intermediate priority, for template wide configuration)
 * `/rw/config/qubes-bind-dirs.d` (highest priority, for per VM configuration)
 
-## How does it work? ##
+## How does it work?
 
 bind-dirs.sh is called at startup of an app qube, and configuration files in the above configuration folders are parsed to build a bash array.
 Files or folders identified in the array are copied to `/rw/bind-dirs` if they do not already exist there, and are then bind mounted over the original files/folders.
@@ -84,7 +83,7 @@ Creation of the files and folders in `/rw/bind-dirs` should be automatic the fir
 If you want to circumvent this process, you can create the relevant file structure under `/rw/bind-dirs` and make any changes at the same time that you perform the configuration, before reboot.
 Note that you must create the full folder structure under `/rw/bind-dirs` - e.g you would have to create `/rw/bind-dirs/var/lib/tor`
 
-## Limitations ##
+## Limitations
 
 * Files that exist in the template root image cannot be deleted in the app qubes root image using bind-dirs.sh.
 * Re-running `sudo /usr/lib/qubes/init/bind-dirs.sh` without a previous `sudo /usr/lib/qubes/init/bind-dirs.sh umount` does not work.
@@ -93,9 +92,9 @@ Note that you must create the full folder structure under `/rw/bind-dirs` - e.g
 Any changes you make will not survive a reboot. If you think it likely you will want to edit a file, then either include the parent directory in bind-dirs rather than the file, or perform the file operation on the file in `/rw/bind-dirs`.
 * Some files are altered when a qube boots - e.g. `/etc/hosts`.
 If you try to use bind-dirs on such files you may break your qube in unpredictable ways.
-You can add persistent rules to `/etc/hosts` using [`/rw/config/rc.local`](/doc/config-files)
+You can add persistent rules to `/etc/hosts` using [`/rw/config/rc.local`](/doc/config-files).
 
-## How to remove binds from bind-dirs.sh? ##
+## How to remove binds from bind-dirs.sh?
 
 `binds` is actually just a bash variable (an array) and the bind-dirs.sh configuration folders are sourced as bash snippets in lexical order.
 Therefore if you wanted to remove an existing entry from the `binds` array, you could do that by using a lexically higher configuration file.
@@ -111,7 +110,8 @@ binds=( "${binds[@]/'/var/lib/tor'}" )
 
 ## Custom persist feature ##
 
-Custom persist is an optional advanced feature allowing the creation of minimal state AppVM. The purpose of such an AppVM is to avoid unwanted data to persist as much as possible by the disabling the ability to configure persistence from the VM itself. When enabled, the following happens:
+Custom persist is an optional advanced feature allowing the creation of minimal state AppVM. The purpose of such an AppVM is to avoid unwanted data to persist as much as possible by disabling the ability to configure persistence from the VM itself. When enabled, the following happens:
+
 * ``/rw/config/rc.local`` is no longer executed
 * ``/rw/config/qubes-firewall-user-script`` is ignored
 * ``/rw/config/suspend-module-blacklist`` is ignored

user/advanced-topics/config-files.md

@@ -18,7 +18,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:
 
     ~~~
@@ -32,6 +32,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.
@@ -113,8 +115,7 @@ VM: {
 Currently supported settings:
 
 - `allow_fullscreen` - allow VM to request its windows to go fullscreen (without any colorful frame).
-
+    - **Note:** Regardless of this setting, you can always put a window into fullscreen mode in Xfce4 using the trusted window manager by right-clicking on a window's title bar and selecting "Fullscreen".
-    **Note:** Regardless of this setting, you can always put a window into fullscreen mode in Xfce4 using the trusted window manager by right-clicking on a window's title bar and selecting "Fullscreen".
     This functionality should still be considered safe, since a VM window still can't voluntarily enter fullscreen mode.
     The user must select this option from the trusted window manager in dom0.
     To exit fullscreen mode from here, press `alt` + `space` to bring up the title bar menu again, then select "Leave Fullscreen".

user/advanced-topics/gui-configuration.md

@@ -21,7 +21,7 @@ qvm-features dom0 gui-videoram-min $(($WIDTH * $HEIGHT * 4 / 1024))
 qvm-features dom0 gui-videoram-overhead 0
 ```
 
-Where `$WIDTH`×`$HEIGHT` is the maximum desktop size that you anticipate needing.
+Where `$WIDTH` × `$HEIGHT` is the maximum desktop size that you anticipate needing.
 For example, if you expect to use a 1080p display and a 4k display side-by-side, that is `(1920 + 3840) × 2160 × 4 / 1024 = 48600`, or slightly more than 48 MiB per qube.
 After making these adjustments, the qubes need to be restarted.
 
@@ -31,6 +31,7 @@ qvm-features dom0 gui-videoram-min $(xrandr --verbose | grep "Screen 0" | sed -e
 ```
 
 The amount of memory allocated per qube is the maximum of:
+
 - `gui-videoram-min`
 - current display + `gui-videoram-overhead`
 
@@ -41,8 +42,8 @@ You might face issues when playing video, if the video is choppy instead of
 smooth display this could be because the X server doesn't work. You can use the
 Linux terminal (Ctrl-Alt-F2) after starting the virtual machine, login. You can
 look at the Xorg logs file. As an option you can have the below config as
-well present in `/etc/X11/xorg.conf.d/90-intel.conf`, depends on HD graphics
+well present in `/etc/X11/xorg.conf.d/90-intel.conf` (depends on HD graphics
-though -
+though).
 
 ```bash
 Section "Device"

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:
@@ -120,13 +122,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 +171,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.

user/advanced-topics/i3.md

@@ -24,7 +24,7 @@ optionally in case you would prefer writing your own configuration (see
 
 That's it. After logging out, you can select i3 in the login manager.
 
-### Customization
+# Customization
 
 **Caution:** The following external resources may not have been reviewed by the Qubes team.
 
@@ -34,13 +34,13 @@ That's it. After logging out, you can select i3 in the login manager.
 * [i3 config with dmenu-i3-window-jumper](https://github.com/anadahz/qubes-i3-config/blob/master/config)
 * [dmenu script to open a terminal in a chosen VM](https://gist.github.com/dmoerner/65528941dd20b05c98ee79e92d7e0183)
 
-## Compilation and installation from source
+# Compilation and installation from source
 
 Note that the compilation from source is done in a Fedora based domU (could
 be dispvm). The end result is always an `.rpm` that is copied to dom0 and then
 installed through the package manager.
 
-### Getting the code
+## Getting the code
 
 Clone the i3-qubes repository here:
 
@@ -57,7 +57,7 @@ OS and changes some defaults so the user can't override decisions.
 If you want to make any changes to the package, this is the time and place to do
 it.
 
-### Building
+## Building
 
 You'll need to install the build dependencies, which are listed in
 build-deps.list. You can verify them and then install them with:
@@ -76,7 +76,7 @@ $ make verify-sources
 $ make rpms
 ```
 
-### Installing
+## Installing
 
 **Warning**: Manually installing software in dom0 is inherently risky, and the method described here circumvents the usual security mechanisms of qubes-dom0-update.
 

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
+R3.2, however, [XFCE is the new default desktop environment](/doc/releases/3.2/release-notes/).
-still possible to install KDE by issuing this command in dom0:
+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
+(Replace "3" with whichever virtual desktop you want the window to be on.)
-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.
 

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

@@ -60,7 +60,7 @@ nopat
 
 ## Installing different kernel using Qubes kernel package
 
-VM kernels are packages by Qubes team in `kernel-qubes-vm` packages.
+VM kernels are packaged by the Qubes team in the `kernel-qubes-vm` packages.
 Generally, the system will keep the three newest available versions.
 You can list them with the `rpm` command:
 
@@ -152,8 +152,9 @@ The newly installed package is set as the default VM kernel.
 ## Installing different VM kernel based on dom0 kernel
 
 It is possible to package a kernel installed in dom0 as a VM kernel.
-This makes it possible to use a VM kernel which is not packaged by Qubes team.
+This makes it possible to use a VM kernel which is not packaged by the Qubes team.
 This includes:
+
  * using a Fedora kernel package
  * using a manually compiled kernel
 
@@ -297,7 +298,7 @@ Install distribution kernel image, kernel headers and the grub.
 sudo apt install linux-image-amd64 linux-headers-amd64 grub2 qubes-kernel-vm-support
 ~~~
 
-If you are doing that on a qube based on "Debian Minimal" template, a grub gui will popup during the installation, asking you where you want to install the grub loader. You must select /dev/xvda (check the box using the space bar, and validate your choice with "Enter".) If this popup does not appear during the installation, you must manually setup `grub2` by running:
+If you are doing that on a qube based on "Debian Minimal" template, a grub gui will popup during the installation, asking you where you want to install the grub loader. You must select `/dev/xvda` (check the box using the space bar, and validate your choice with "Enter".) If this popup does not appear during the installation, you must manually setup `grub2` by running:
 
 ~~~
 sudo grub-install /dev/xvda
@@ -314,8 +315,8 @@ 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.
+* `Virtualization` mode `PV`: Possible, however use of `Virtualization` mode `PV` 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`, 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. Install `grub2-xen-pvh` in dom0.
 * `Virtualization` mode `HVM`: Possible.
 

user/advanced-topics/mount-from-other-os.md

@@ -13,6 +13,7 @@ title: How to mount a Qubes partition from another OS
 When a Qubes OS install is unbootable or booting it is otherwise undesirable, this process allows for the recovery of files stored within the system.
 
 These functions are manual and do not require any Qubes specific tools. All steps assume the default Qubes install with the following components:
+
 - LUKS encrypted disk
 - LVM based VM storage
 
@@ -89,7 +90,7 @@ Reverting Changes
 -----------------------------------------
 
 Any changes which were made to the system in the above steps will need to be reverted before the disk will properly boot.
-However, LVM will not allow an VG to be renamed to a name already in use.
+However, LVM will not allow a VG to be renamed to a name already in use.
 Thes steps must occur either in an app qube or using recovery media.
 
 1. Unmount any disks that were accessed.

user/advanced-topics/rpc-policy.md

@@ -43,7 +43,7 @@ This is how we create a policy that says: "VMs tagged with 'work' are allowed to
 
 When an operation is initiated with a specific target, e.g. `qvm-copy-to-vm other_work_vm some_file` the policy mechanism looks for a row
 matching `source_work_vm other_work_vm PERMISSION`. In this case, assuming both VMs have the `work` tag, the second row would match, and
-the operation would be `allow`ed without any prompts. When an operation is initiated without a specific target, e.g. `qvm-copy some_file`,
+the operation would be `allow`-ed without any prompts. When an operation is initiated without a specific target, e.g. `qvm-copy some_file`,
 the policy mechanism looks for a row matching `source_work_vm @default PERMISSION`. In this case, the first row indicates that the user
 should be prompted for the destination. The list of destination VMs in the prompt is filtered to only include VMs that are valid as per
 the policy (so in this example, only other work VMs would be listed). If the first row was commented out, the second row would not match

user/advanced-topics/salt.md

@@ -67,9 +67,9 @@ The lowest level is a single state function, called like
 this `state.single pkg.installed name=firefox-esr`
 When the system compiles data from sls formulas, it generates *chunks* -
 low chunks are at the bottom of the compiler . You can call them with
-`state.low`
+`state.low`.
 Next up is the *lowstate* level - this is the list of all low chunks in
-order. - To see them you have `state.show_lowstate`, and use `state.lowstate` to apply them.
+order. To see them you have `state.show_lowstate`, and use `state.lowstate` to apply them.
 At the top level is *highstate* - this is an interpretation of **all** the data represented in YAML
 in sls files. You can view it with `state.show_highstate`.
 
@@ -219,7 +219,7 @@ Instead, to get this behavior, you would use a `do` statement.
 So you should take a look at the [Jinja API documentation](https://jinja.palletsprojects.com/templates/).
 Documentation about using Jinja to directly call Salt functions and get data
 about your system can be found in the official
-[Salt documentation](https://docs.saltproject.io/en/getstarted/config/jinja.html#get-data-using-salt).
+[Salt documentation](https://docs.saltproject.io/salt/user-guide/en/latest/topics/jinja.html).
 
 ## Salt Configuration, QubesOS layout
 
@@ -588,6 +588,7 @@ qube which provides network to the given qube
 The output for each qube is logged in `/var/log/qubes/mgmt-VM_NAME.log`.
 
 If the log does not contain useful information:
+
 1. Run `sudo qubesctl --skip-dom0 --target=VM_NAME state.apply`
 2. When your qube is being started (yellow) press Ctrl-z on qubesctl.
 3. Open terminal in disp-mgmt-qube_NAME.
@@ -595,12 +596,12 @@ If the log does not contain useful information:
    executed in the management qube.
 5. Get the last two lines:
 
-    ```shell_session
+```shell_session
-    $ export PATH="/usr/lib/qubes-vm-connector/ssh-wrapper:$PATH"
+$ export PATH="/usr/lib/qubes-vm-connector/ssh-wrapper:$PATH"
-    $ salt-ssh "$target_vm" $salt_command
+$ salt-ssh "$target_vm" $salt_command
-    ```
+```
-
   Adjust $target_vm (VM_NAME) and $salt_command (state.apply).
+
 6. Execute them, fix problems, repeat.
 
 ## Known Pitfalls

user/advanced-topics/secondary-storage.md

@@ -11,104 +11,183 @@ ref: 187
 title: Secondary storage
 ---
 
+# 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 app qubes 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 app qubes on another, without messy symlinks.
 
-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.
+You can query qvm-pool to list available storage drivers:
+
+``` shell_session
+qvm-pool --help-drivers
+```
+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 they will lack some features: for example, you won't be able to do backups without shutting down the qube.
+
+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 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:
 
-```
+```shell_session
 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
 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 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 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
+```
+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:
 
-```
+```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>
 ```
 
-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>
 ```
 
-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 setup of second drive. 
 
-### Example HDD setup
+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:
-
-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 /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:
+(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 editing `/etc/crypttab`, and adding this line to crypttab (replacing both "b209..." entries with your device's UUID taken from blkid) :
-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
 ```
 
-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):
 
-First create the physical volume
+##### For LVM
 
-```
+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
+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
 
-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:
+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 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:
+```
+sudo btrfs subvolume create /mnt/new_qube_storage/qubes
+```
+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:
+```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:
+
+```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 drive do the following on a dom0 terminal:
+
+```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/

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
@@ -68,6 +83,7 @@ qvm-create --class StandaloneVM --label <YOUR_COLOR> --property virt_mode=hvm --
 ```
 
 Notes:
+
 - Technically, `virt_mode=hvm` is not necessary for every standalone.
 However, it is needed if you want to use a kernel from within the qube.
 - If you want to make software installed in a template available in your standalone, pass in the name of the template using the `--template` option.
@@ -176,9 +192,40 @@ seen, e.g., in the Qube Manager in the qube's properties:
 
 Alternatively, one can use the `qvm-ls -n` command to obtain the same
 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
+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`.
-support](/doc/networking/#ipv6) for IPv6 forwarding.
+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 a worked example will 
+prove useful. This example is for an HVM running EndeavourOS. 
+
+![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 - 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](/attachment/doc/Network_Manager.png "Annotated image of KDE Network Manager")
+
+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
 
@@ -201,7 +248,7 @@ 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
-page](https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows-tools.md)
+page](/doc/templates/windows/windows-qubes-4-1/#windows-as-a-template)
 for specific advice on installing and using Windows-based templates.
 
 ## Cloning HVMs
@@ -365,9 +412,7 @@ device again. This is illustrated in the screenshot below:
 
 You can convert any VirtualBox VM to a Qubes HVM using this method.
 
-For example, Microsoft provides [free 90-day evaluation VirtualBox VMs for
+For example, Microsoft provides [virtual machines containing an evaluation version of Windows](https://developer.microsoft.com/en-us/windows/downloads/virtual-machines/).
-browser
-testing](https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/).
 
 About 60 GB of disk space is required for conversion. Use an external hard
 drive if needed. The final `root.img` size is 40 GB.
@@ -446,5 +491,5 @@ qemu-img -h | tail -n1
 
 Other documents related to HVMs:
 
-- [Windows VMs](https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows-vm.md)
+- [Windows VMs](https://forum.qubes-os.org/search?q=windows%20hvm%20%23guides)
 - [Linux HVM Tips](https://forum.qubes-os.org/t/19008)

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

@@ -17,13 +17,13 @@ shutdown. (Note that this is a different, lower level activity than the
 
 In Qubes, when you create a new VM, it's volumes are stored in one of the
 system's [Storage Pools](/doc/storage-pools/). On pool creation, a
-revisions_to_keep default value is set for the entire pool. (For a pool creation
+`revisions_to_keep` default value is set for the entire pool. (For a pool creation
 example, see [Storing app qubes on Secondary Drives](/doc/secondary-storage/).)
 Thereafter, each volume associated with a VM that is stored in this pool
-inherits the pool default revisions_to_keep.
+inherits the pool default `revisions_to_keep`.
 
-For the private volume associated with a VM named vmname, you may inspect the
+For the private volume associated with a VM named *vmname*, you may inspect the
-value of revisions_to_keep from the dom0 CLI as follows:
+value of `revisions_to_keep` from the dom0 CLI as follows:
 
 ```
 qvm-volume info vmname:private
@@ -31,11 +31,11 @@ qvm-volume info vmname:private
 
 The output of the above command will also display the "Available revisions
 (for revert)" at the bottom. For a very large volume in a small pool,
-revisions_to_keep should probably be set to the maximum value of 1 to minimize
+`revisions_to_keep` should probably be set to the maximum value of 1 to minimize
 the possibility of the pool being accidentally filled up by snapshots. For a
 smaller volume for which you would like to have the future option of reverting,
-revisions_to_keep should probably be set to at least 2. To set
+`revisions_to_keep` should probably be set to at least 2. To set
-revisions_to_keep for this same VM / volume example:
+`revisions_to_keep` for this same VM / volume example:
 
 ```
 qvm-volume config vmname:private revisions_to_keep 2

user/downloading-installing-upgrading/install-security.md

@@ -51,7 +51,7 @@ Cons:
   (If the drive is mounted to a compromised machine, the ISO could be maliciously altered after it has been written to the drive.)
 * Untrustworthy firmware.
   (Firmware can be malicious even if the drive is new.
-  Plugging a drive with rewritable firmware into a compromised machine can also [compromise the drive](https://srlabs.de/badusb/).
+  Plugging a drive with rewritable firmware into a compromised machine can also [compromise the drive](https://web.archive.org/web/20160304013434/https://srlabs.de/badusb/).
   Installing from a compromised drive could compromise even a brand new Qubes installation.)
 
 ### Optical discs

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

@@ -174,6 +174,8 @@ You can have as many keyboard layout and languages as you want. Post-install, yo
 Don't forget to select your time and date by clicking on the Time & Date entry.
 
 [![Time and date](/attachment/doc/time-and-date.png)](/attachment/doc/time-and-date.png)
+
+
 ### Installation destination
 
 Under the System section, you must choose the installation destination. Select the storage device on which you would like to install Qubes OS.

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
 

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/).

user/downloading-installing-upgrading/upgrade/2.md

@@ -34,7 +34,7 @@ Note that dom0 in R2 is based on Fedora 20, in contrast to Fedora 18 in previous
 
 1. Open terminal in Dom0. E.g. Start-\>System Settings-\>Konsole.
 
-1. Install all the updates for Dom0:
+2. Install all the updates for Dom0:
 
     ~~~
     sudo qubes-dom0-update
@@ -42,7 +42,7 @@ Note that dom0 in R2 is based on Fedora 20, in contrast to Fedora 18 in previous
 
 After this step you should have `qubes-release-2-5` in your Dom0. Important: if you happen to have `qubes-release-2-6*` then you should downgrade to `qubes-release-2-5`! The `qubes-release-2-6*` packages have been uploaded to the testing repos and were kept there for a few hours, until we realized they bring incorrect repo definitions and so we removed them and also have changed the update procedure a bit (simplifying it).
 
-1. Upgrade dom0 to R2:
+3. Upgrade dom0 to R2:
 
 Note: be sure that the VM used as a update-downloading-vm (by default its the firewallvm based on the default template) has been updated to the latest Qubes packages, specifically `qubes-core-vm-2.1.33` or later. This doesn't imply that the VM must already be upgraded to fc20 -- for Dom0 upgrade we could still use an fc18-based VM (updatevm) it is only important to install the latest Qubes packages there.
 
@@ -51,7 +51,7 @@ sudo qubes-dom0-update qubes-dom0-dist-upgrade
 sudo qubes-dom0-update
 ~~~
 
-1. If above step completed successfully you should have `qubes-release-2-9` or later. If not, repeat above step with additional `--clean` option.
+4. If above step completed successfully you should have `qubes-release-2-9` or later. If not, repeat above step with additional `--clean` option.
 
 4a. If you chose not to upgrade your fc18 templates, but instead to download our new fc20-based template you should now be able to do that by simply typing:
 
@@ -59,6 +59,6 @@ sudo qubes-dom0-update
 sudo qubes-dom0-update qubes-template-fedora-20-x64
 ~~~
 
-1. Reboot the system.
+5. Reboot the system.
 
 Please note that if you use Anti Evil Maid, then it won't be able to unseal the passphrase this time, because the Xen, kernel, and initramfs binaries have changed. Once the system boots up again, you could reseal your Anti Evil Maid's passphrase to the new configuration. Please consult Anti Evil Maid documentation for explanation on how to do that.

user/downloading-installing-upgrading/upgrade/2b1.md

@@ -13,7 +13,7 @@ title: Upgrading to R2B1
 
 **Note: Qubes R2 Beta 1 is no longer supported! Please install or upgrade to a newer Qubes R2.**
 
-**Note: This page is kept for historical reasons only! Do not follow the instructions below'''**
+**Note: This page is kept for historical reasons only! Do not follow the instructions below**
 
 Existing users of Qubes R1 (but not R1 betas!) can upgrade their systems to the latest R2 beta release by following the procedure below. As usual, it is advisable to backup the system before proceeding with the upgrade
 
@@ -51,7 +51,7 @@ By default, in Qubes R1, there is only one template, however users are free to c
 - via a legitimate RPM package previously installed (in our case it was the `qubes-upgrade-vm` RPM). Such an RPM must have been signed by one of the keys you decided to trust previously, by default this would be either via the Qubes R1 signing key, or Fedora 17 signing key.
 - via system compromise or via some illegal RPM package (e.g. Fedora released package pretending to bring new Firefox). In that case, however, your VM is already compromised, and it careful checking of the new R2 key would not change this situation to any better one. The game is lost for this VM anyway (and all VMs based on this template).
 
-1. Shut down the VM.
+4. Shut down the VM.
 
 Upgrade Dom0
 ------------

user/downloading-installing-upgrading/upgrade/2b2.md

@@ -49,7 +49,7 @@ By default, in Qubes R1, there is only one template, however users are free to c
 - via a legitimate RPM package previously installed (in our case it was the `qubes-upgrade-vm` RPM). Such an RPM must have been signed by one of the keys you decided to trust previously, by default this would be either via the Qubes R1 signing key, or Fedora 17 signing key.
 - via system compromise or via some illegal RPM package (e.g. Fedora released package pretending to bring new Firefox). In that case, however, your VM is already compromised, and it careful checking of the new R2 key would not change this situation to any better one. The game is lost for this VM anyway (and all VMs based on this template).
 
-1. Shut down the VM.
+4. Shut down the VM.
 
 Installing new template
 -----------------------

user/downloading-installing-upgrading/upgrade/3_0.md

@@ -101,7 +101,7 @@ Be sure to do steps described in this section after *all* your template and stan
 
 6. Reboot the system.
     
-    It may happen that the system hang during the reboot. Hard reset the system in such case, all the filesystems are unmounted at this stage.
+    - It may happen that the system hang during the reboot. Hard reset the system in such case, all the filesystems are unmounted at this stage.
 
 Please note that if you use Anti Evil Maid, then it won't be able to unseal the passphrase this time, because the Xen, kernel, and initramfs binaries have changed. Once the system boots up again, you could reseal your Anti Evil Maid's passphrase to the new configuration. Please consult Anti Evil Maid documentation for explanation on how to do that.
 

user/downloading-installing-upgrading/upgrade/3_1.md

@@ -98,11 +98,11 @@ complete.
 
 4. Reboot dom0.
     
-    The system may hang during the reboot. If that happens, do not panic. All
+   - The system may hang during the reboot. If that happens, do not panic. All
-    the filesystems will have already been unmounted at this stage, so you can
+     the filesystems will have already been unmounted at this stage, so you can
-    simply perform a hard reboot (e.g., hold the physical power button down
+     simply perform a hard reboot (e.g., hold the physical power button down
-    until the machine shuts off, wait a moment, then press it again to start it
+     until the machine shuts off, wait a moment, then press it again to start it
-    back up).
+     back up).
 
 Please note that if you use [Anti Evil Maid](/doc/anti-evil-maid), it won't be
 able to unseal the passphrase the first time the system boots after performing

user/downloading-installing-upgrading/upgrade/3_2.md

@@ -29,13 +29,13 @@ by following the procedure below.
     sudo qubes-dom0-update --releasever=3.2 qubes-release
     ```
 
-    If you made any manual changes to repository definitions, new definitions
+    - If you made any manual changes to repository definitions, new definitions
     will be installed as `/etc/yum.repos.d/qubes-dom0.repo.rpmnew` (you'll see
     a message about it during package installation). In such a case, you need
     to manually apply the changes to `/etc/yum.repos.d/qubes-dom0.repo` or
     simply replace it with .rpmnew file.
 
-    If you are using Debian-based VM as UpdateVM (`sys-firewall` by default),
+    - If you are using Debian-based VM as UpdateVM (`sys-firewall` by default),
     you need to download few more packages manually, but **do not install
     them** yet:
 
@@ -60,7 +60,7 @@ by following the procedure below.
     sudo qubes-dom0-update
     ```
 
-    You may wish to disable the screensaver "Lock screen" feature for this step, as
+    - You may wish to disable the screensaver "Lock screen" feature for this step, as
     during the update XScreensaver may encounter an "Authentication failed" issue,
     requiring a hard reboot. Alternatively, you may simply move the mouse regularly.
     
@@ -70,7 +70,7 @@ by following the procedure below.
 
 6. Update configuration files.
 
-    Some of configuration files were saved with `.rpmnew` extension as the
+    - Some of configuration files were saved with `.rpmnew` extension as the
     actual files were modified. During upgrade, you'll see information about
     such cases, like:
 
@@ -78,7 +78,7 @@ by following the procedure below.
     warning: /etc/salt/minion.d/f_defaults.conf created as /etc/salt/minion.d/f_defaults.conf.rpmnew
     ```
 
-    This will happen for every configuration you have modified manually and for
+    - This will happen for every configuration you have modified manually and for
     a few that has been modified by Qubes scripts. If you are not sure what to
     do about them, below is a list of commands to deal with few common cases
     (either keep the old one, or replace with the new one):

user/hardware/certified-hardware/certified-hardware.md

@@ -32,11 +32,11 @@ The current Qubes-certified models are listed below in reverse chronological ord
 | [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/)               |
+| [Nitrokey](https://www.nitrokey.com/)  | [NitroPC Pro](https://web.archive.org/web/20231027112856/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/)             |
+| [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

user/hardware/certified-hardware/dasharo-fidelisguard-z690.md

@@ -4,11 +4,12 @@ layout: doc
 permalink: /doc/certified-hardware/dasharo-fidelisguard-z690/
 title: Dasharo FidelisGuard Z690
 image: /attachment/posts/dasharo-fidelisguard-z690_2.jpg
+ref: 350
 ---
 
 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:
 

user/hardware/certified-hardware/insurgo-privacybeast-x230.md

@@ -4,6 +4,7 @@ layout: doc
 permalink: /doc/certified-hardware/insurgo-privacybeast-x230/
 title: Insurgo PrivacyBeast X230
 image: /attachment/site/insurgo-privacybeast-x230.png
+ref: 351
 ---
 
 <div class="alert alert-danger" role="alert">
@@ -19,7 +20,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.
 

user/hardware/certified-hardware/nitropad-t430.md

@@ -4,6 +4,7 @@ layout: doc
 permalink: /doc/certified-hardware/nitropad-t430/
 title: NitroPad T430
 image: /attachment/site/nitropad-t430.jpg
+ref: 352
 ---
 
 <div class="alert alert-danger" role="alert">

user/hardware/certified-hardware/nitropad-v56.md

@@ -4,6 +4,7 @@ layout: doc
 permalink: /doc/certified-hardware/nitropad-v56/
 title: NitroPad V56
 image: /attachment/site/nitropad-v56.png
+ref: 353
 ---
 
 The [NitroPad V56](https://shop.nitrokey.com/shop/nitropad-v56-684) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.

user/hardware/certified-hardware/nitropad-x230.md

@@ -4,6 +4,7 @@ layout: doc
 permalink: /doc/certified-hardware/nitropad-x230/
 title: NitroPad X230
 image: /attachment/site/nitropad-x230.jpg
+ref: 354
 ---
 
 <div class="alert alert-danger" role="alert">

user/hardware/certified-hardware/nitropc-pro-2.md

@@ -4,6 +4,7 @@ layout: doc
 permalink: /doc/certified-hardware/nitropc-pro-2/
 title: NitroPC Pro 2
 image: /attachment/posts/nitropc-pro.jpg
+ref: 355
 ---
 
 <div class="alert alert-warning" role="alert">

user/hardware/certified-hardware/nitropc-pro.md

@@ -4,6 +4,7 @@ layout: doc
 permalink: /doc/certified-hardware/nitropc-pro/
 title: NitroPC Pro
 image: /attachment/posts/nitropc-pro.jpg
+ref: 356
 ---
 
 <div class="alert alert-warning" role="alert">
@@ -16,7 +17,7 @@ image: /attachment/posts/nitropc-pro.jpg
   <b>Note:</b> Only the "Dasharo TianoCore UEFI without Measured Boot, without Nitrokey" firmware option is certified. The "HEADS with Measured Boot, requires Nitrokey!" firmware option is <em>not</em> certified.
 </div>
 
-The [NitroPC Pro](https://shop.nitrokey.com/shop/product/nitropc-pro-523) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.
+The [NitroPC Pro](https://web.archive.org/web/20231027112856/https://shop.nitrokey.com/shop/product/nitropc-pro-523) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.
 
 [![Photo of NitroPC Pro](/attachment/posts/nitropc-pro.jpg)](https://shop.nitrokey.com/shop/product/nitropc-pro-523)
 
@@ -39,7 +40,7 @@ The NitroPC Pro also comes with a "Dasharo Entry Subscription," which includes t
 - Accesses to the latest firmware releases
 - Exclusive newsletter
 - Special firmware updates, including early access to updates enhancing privacy, security, performance, and compatibility
-- Early access to new firmware releases for [newly-supported desktop platforms](https://docs.dasharo.com/variants/overview/#desktop) (please see the [roadmap](https://github.com/Dasharo/presentations/blob/main/dug2_dasharo_roadmap.md#dasharo-desktop-roadmap))
+- Early access to new firmware releases for [newly-supported desktop platforms](https://docs.dasharo.com/variants/overview/#desktop) (please see the [roadmap](https://github.com/Dasharo/presentations/blob/8f360b3e82108d1e85585c1c324a28a08dd276a5/dug2_dasharo_roadmap.md))
 - Access to the Dasharo Premier Support invite-only live chat channel on the Matrix network, allowing direct access to the Dasharo Team and fellow subscribers with personalized and priority assistance
 - Insider's view and influence on the Dasharo feature roadmap for a real impact on Dasharo development
 - [Dasharo Tools Suite Entry Subscription](https://docs.dasharo.com/osf-trivia-list/dts/#what-is-dasharo-tools-suite-supporters-entrance) keys

user/hardware/certified-hardware/novacustom-nv41-series.md

@@ -4,6 +4,7 @@ layout: doc
 permalink: /doc/certified-hardware/novacustom-nv41-series/
 title: NovaCustom NV41 Series
 image: /attachment/site/novacustom-nv41-series.png
+ref: 357
 ---
 
 The [NovaCustom NV41 Series](https://novacustom.com/product/nv41-series/) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.
@@ -15,19 +16,23 @@ The [NovaCustom NV41 Series](https://novacustom.com/product/nv41-series/) is [of
 The following configuration options are certified for Qubes OS Release 4:
 
 Processor:
+
 - Intel Core i5-1240P processor
 - Intel Core i7-1260P processor
 
 Memory:
+
 - 2 x 16 GB Kingston DDR4 SODIMM 3200 MHz (32 GB total)
 - 1 x 32 GB Kingston DDR4 SODIMM 3200 MHz (32 GB total)
 - 2 x 32 GB Kingston DDR4 SODIMM 3200 MHz (64 GB total)
 
 M.2 storage chip:
+
 - Samsung 980 SSD (all capacities)
 - Samsung 980 Pro SSD (all capacities)
 
 Wi-Fi and Bluetooth:
+
 - Intel AX-200/201 Wi-Fi module 2976 Mbps, 802.11ax/Wi-Fi 6 + Bluetooth 5.2
 - Killer (Intel) Wireless-AX 1675x M.2 Wi-Fi module 802.11ax/Wi-Fi 6E + Bluetooth 5.3
 - Blob-free: Qualcomm Atheros QCNFA222 Wi-Fi 802.11a/b/g/n + Bluetooth 4.0

user/hardware/certified-hardware/novacustom-v54-series.md

@@ -4,6 +4,7 @@ layout: doc
 permalink: /doc/certified-hardware/novacustom-v54-series/
 title: NovaCustom V54 Series
 image: /attachment/site/novacustom-v54-series.png
+ref: 358
 ---
 
 The [NovaCustom V54 Series 14.0 inch coreboot laptop](https://novacustom.com/product/v54-series/) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.
@@ -47,7 +48,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

user/hardware/certified-hardware/novacustom-v56-series.md

@@ -4,6 +4,7 @@ layout: doc
 permalink: /doc/certified-hardware/novacustom-v56-series/
 title: NovaCustom V56 Series
 image: /attachment/site/novacustom-v56-series.png
+ref: 359
 ---
 
 The [NovaCustom V56 Series 16.0 inch coreboot laptop](https://novacustom.com/product/v56-series/) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.
@@ -47,7 +48,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

user/hardware/certified-hardware/starlabs-starbook.md

@@ -4,6 +4,7 @@ layout: doc
 permalink: /doc/certified-hardware/starlabs-starbook/
 title: Star Labs StarBook
 image: /attachment/site/starlabs-starbook.png
+ref: 360
 ---
 
 The [Star Labs StarBook](https://starlabs.systems/pages/starbook) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.

user/hardware/system-requirements.md

@@ -98,7 +98,7 @@ We recommend consulting these resources when selecting hardware for Qubes OS:
   offer significant security advantages over conventional operating systems on
   the same hardware.
 
-  Intel maintains a
+  - Intel maintains a
   [list](https://www.intel.com/content/www/us/en/support/articles/000022396/processors.html)
   of end-of-support dates for its processors. However, this list seems to
   include only processors that are no longer supported or will soon no longer
@@ -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
+  - 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
@@ -131,11 +131,9 @@ We recommend consulting these resources when selecting hardware for Qubes OS:
   designated date.) By contrast, Intel has consistently made fixes available for
   new CPU vulnerabilities across its supported platforms very shortly after
   security embargoes have been lifted.
-
+  - Step (2) varies by vendor. Many vendors fail to complete step (2) at all,
-  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
-  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
   they can do.
@@ -163,3 +161,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.

user/how-to-guides/backup-emergency-restore-v3.md

@@ -52,11 +52,11 @@ any GNU/Linux system with the following procedure.
         [user@restore ~]$ cat backup-header.hmac
         (stdin)= 5b266783e116fe3b2601a54c249ca5f5f96d421dfe6828eeaeb2dcd014e9e945c27b3d7b0f952f5d55c927318906d9c360f387b0e1f069bb8195e96543e2969c
 
-    **Note:** The hash values should match. If they do not match, then the
+    - **Note:** The hash values should match. If they do not match, then the
     backup file may have been tampered with, or there may have been a storage
     error.
 
-    **Note:** If your backup was hashed with a message digest algorithm other
+    - **Note:** If your backup was hashed with a message digest algorithm other
     than `sha512`, you must substitute the correct message digest command. This
     information is contained in the `backup-header` file (see step 4), however
     it is not recommended to open this file until its integrity and
@@ -86,11 +86,11 @@ any GNU/Linux system with the following procedure.
         [user@restore vm1]$ cat private.img.000.hmac
         (stdin)= cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
 
-    **Note:** The hash values should match. If they do not match, then the
+    - **Note:** The hash values should match. If they do not match, then the
     backup file may have been tampered with, or there may have been a storage
     error.
 
-    **Note:** If your backup was hashed with a message digest algorithm other
+    - **Note:** If your backup was hashed with a message digest algorithm other
     than `sha512`, you must substitute the correct message digest command. This
     information is contained in the `backup-header` file (see step 4). A
     complete list of supported message digest algorithms can be found with
@@ -135,7 +135,7 @@ any GNU/Linux system with the following procedure.
 10. Success! If you wish to recover data from more than one VM in your backup,
     simply repeat steps 5--9 for each additional VM.
 
-    **Note:** You may wish to store a copy of these instructions with your
+    - **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

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
+The Qubes backup system is designed with emergency disaster recovery in mind. No
-mind. No special Qubes-specific tools are required to access data backed up by
+special Qubes-specific tools are required to access data backed up by Qubes. In
-Qubes. In the event a Qubes system is unavailable, you can access your data on
+the event a Qubes system is unavailable, you can access your data on any
-any GNU/Linux system with the following procedure.
+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 [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
+uses an RPM-based system (Fedora), but the same general procedure should work on
-on any GNU/Linux system.
+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
 
@@ -62,60 +66,35 @@ on 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"
 
- 6. (Optional) Create an alias for the new binary.
+## Emergency recovery instructions
-
-        [user@restore ~]$ alias scrypt="scrypt-*/usr/bin/scrypt"
-
-Emergency Recovery Instructions
--------------------------------
 
 **Note:** In the following example, the backup file is both *encrypted* and
 *compressed*.
 
- 1. Untar the main backup file.
+ 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
         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
-
-    **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
+    required, it will be handy later and will avoid saving the passphrase in the
-    the shell's history.
+    shell's history.
 
         [user@restore ~]$ read -r backup_pass
 
- 3. Verify the integrity of `backup-header`. For compatibility reasons,
+    Type in your passphrase (it will be visible on screen!) and press Enter.
-    `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" |\
@@ -123,58 +102,101 @@ 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
+    **Note:** If this command fails, it may be that the backup was tampered with
-    with or is in a different format. In the latter case, look inside
+    or is in a different format. In the latter case, look inside `backup-header`
-    `backup-header` at the `version` field. If it contains a value other than
+    at the `version` field. If it contains a value other than `version=4`, go to
-    `version=4`, go to the instructions for that format version:
+    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`:
+ 4. 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=20230405T123455-1234
 
- 5. Set `backup_id` to the value in the last line of `backup-header`:
+ 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 the integrity of your data, decrypt, decompress, and extract
+ 6. Verify and decrypt, decompress, and extract the `qubes.xml` file.
-    `private.img`:
 
-        [user@restore ~]$ find vm1 -name 'private.img.*.enc' | sort -V | while read f_enc; do \
+        [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 4). For example,
+    if your backup is compressed with `bzip2`, use `bzip2 -d` instead of `gzip
+    -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 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 ~]$ 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
+        sys-whonix
+        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.
+
+        [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
-        vm1/private.img
+        vm123/private.img
 
     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`,
+    Also see the note in step 6 about substituting a different compression
-    you must substitute the correct compression program in the command above.
+    program for `gzip`.
-    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.
 
- 7. Mount `private.img` and access your data.
+ 9. Mount `private.img` and access your data.
 
-        [user@restore vm1]$ sudo mkdir /mnt/img
+        [user@restore ~]$ sudo mkdir /mnt/img
-        [user@restore vm1]$ sudo mount -o loop vm1/private.img /mnt/img/
+        [user@restore ~]$ sudo mount -o loop vm123/private.img /mnt/img/
-        [user@restore vm1]$ cat /mnt/img/home/user/your_data.txt
+        [user@restore ~]$ ls /mnt/img/home/user/
-        This data has been successfully recovered!
+        example_data_file.txt
+        ...
 
- 8. Success! If you wish to recover data from more than one VM in your backup,
+Success! If you wish to recover data from more than one qube in your backup,
-    simply repeat steps 6 and 7 for each additional VM.
+simply repeat steps 7, 8, and 9 for each additional qube.
-
-    **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

user/how-to-guides/how-to-back-up-restore-and-migrate.md

@@ -53,44 +53,44 @@ fresh installation.
 2. Move the VMs that you want to back up to the right-hand **Selected** column.
    VMs in the left-hand **Available** column will not be backed up.
 
-   You may choose whether to compress backups by checking or unchecking the
+   - You may choose whether to compress backups by checking or unchecking the
-   **Compress the backup** box. Normally this should be left on unless you have
+     **Compress the backup** box. Normally this should be left on unless you have
-   a specific reason otherwise.
+     a specific reason otherwise.
 
-   Once you have selected all desired VMs, click **Next**.
+   - Once you have selected all desired VMs, click **Next**.
 
 3. Select the destination for the backup:
 
-   If you wish to send your backup to a (currently running) VM, select the VM
+   - If you wish to send your backup to a (currently running) VM, select the VM
-   in the drop-down box next to **Target app qube**. If you wish to send your
+     in the drop-down box next to **Target app qube**. If you wish to send your
-   backup to a [USB mass storage device](/doc/usb/), you can use the directory
+     backup to a [USB mass storage device](/doc/usb/), you can use the directory
-   selection widget to mount a connected device (under "Other locations" item
+     selection widget to mount a connected device (under "Other locations" item
-   on the left); or first mount the device in a VM, then select the mount point
+     on the left); or first mount the device in a VM, then select the mount point
-   inside that VM as the backup destination.
+     inside that VM as the backup destination.
 
-   You must also specify a directory on the device or in the VM, or a command
+   - You must also specify a directory on the device or in the VM, or a command
-   to be executed in the VM as a destination for your backup. For example, if
+     to be executed in the VM as a destination for your backup. For example, if
-   you wish to send your backup to the `~/backups` folder in the target VM, you
+     you wish to send your backup to the `~/backups` folder in the target VM, you
-   would simply browse to it using the convenient directory selection dialog
+     would simply browse to it using the convenient directory selection dialog
-   (`...`) at the right. This destination directory must already exist. If it
+     (`...`) at the right. This destination directory must already exist. If it
-   does not exist, you must create it manually prior to backing up.
+     does not exist, you must create it manually prior to backing up.
 
-   By specifying the appropriate directory as the destination in a VM, it is
+   - By specifying the appropriate directory as the destination in a VM, it is
-   possible to send the backup directly to, e.g., a USB mass storage device
+     possible to send the backup directly to, e.g., a USB mass storage device
-   attached to the VM. Likewise, it is possible to enter any command as a
+     attached to the VM. Likewise, it is possible to enter any command as a
-   backup target by specifying the command as the destination in the VM. This
+     backup target by specifying the command as the destination in the VM. This
-   can be used to send your backup directly to, e.g., a remote server using
+     can be used to send your backup directly to, e.g., a remote server using
-   SSH.
+     SSH.
 
-   **Note:** The supplied passphrase is used for **both** encryption/decryption
+   - **Note:** The supplied passphrase is used for **both** encryption/decryption
-   and integrity verification.
+     and integrity verification.
 
-   At this point, you may also choose whether to save your settings by checking
+   - At this point, you may also choose whether to save your settings by checking
-   or unchecking the **Save settings as default backup profile** box.
+     or unchecking the **Save settings as default backup profile** box.
 
-   **Warning: Saving the settings will result in your backup passphrase being
+   - **Warning: Saving the settings will result in your backup passphrase being
-   saved in plaintext in dom0, so consider your threat model before checking
+     saved in plaintext in dom0, so consider your threat model before checking
-   this box.**
+     this box.**
 
 4. You will now see the summary of VMs to be backed up. If there are any issues
    preventing the backup, they will be listed here and the **Next** button
@@ -148,10 +148,10 @@ fresh installation.
 a passphrase was supplied during the creation of your backup (regardless of
 whether it is encrypted), then you must supply it here.
 
-   **Note:** The passphrase which was supplied when the backup was created is
+   - **Note:** The passphrase which was supplied when the backup was created is
-   used for **both** encryption/decryption and integrity verification. If the
+     used for **both** encryption/decryption and integrity verification. If the
-   backup was not encrypted, the supplied passphrase is used only for integrity
+     backup was not encrypted, the supplied passphrase is used only for integrity
-   verification. All backups made from a Qubes R4.0 system will be encrypted.
+     verification. All backups made from a Qubes R4.0 system will be encrypted.
 
 5. You will now see the summary of VMs to be restored. If there are any issues
 preventing the restore, they will be listed here and the **Next** button grayed
@@ -203,23 +203,9 @@ the new machine. All of your settings and data will be preserved!
 
 Here are some things to consider when selecting a passphrase for your backups:
 
-- If you plan to store the backup for a long time or on third-party servers,
+- If you plan to store the backup for a long time or on third-party servers, you should make sure to use a very long, high-entropy passphrase. (Depending on the decryption passphrase you use for your system drive, this may necessitate selecting a stronger passphrase. If your system drive decryption passphrase is already sufficiently strong, it may not.)
-  you should make sure to use a very long, high-entropy passphrase. (Depending
+- An adversary who has access to your backups may try to substitute one backup for another. For example, when you attempt to retrieve a recent backup, the adversary may instead give you a very old backup containing a compromised VM. If you're concerned about this type of attack, you may wish to use a different passphrase for each backup, e.g., by appending a number or date to the passphrase.
-  on the decryption passphrase you use for your system drive, this may
+- If you're forced to enter your system drive decryption passphrase in plain view of others (where it can be shoulder-surfed), then you may want to use a different passphrase for your backups (even if your system drive decryption passphrase is already maximally strong). On the other hand, if you're careful to avoid shoulder-surfing and/or have a passphrase that's difficult to detect via shoulder-surfing, then this may not be a problem for you.
-  necessitate selecting a stronger passphrase. If your system drive decryption
-  passphrase is already sufficiently strong, it may not.)
-- An adversary who has access to your backups may try to substitute one backup
-  for another. For example, when you attempt to retrieve a recent backup, the
-  adversary may instead give you a very old backup containing a compromised VM.
-  If you're concerned about this type of attack, you may wish to use a
-  different passphrase for each backup, e.g., by appending a number or date to
-  the passphrase.
-- If you're forced to enter your system drive decryption passphrase in plain
-  view of others (where it can be shoulder-surfed), then you may want to use a
-  different passphrase for your backups (even if your system drive decryption
-  passphrase is already maximally strong). On the other hand, if you're careful
-  to avoid shoulder-surfing and/or have a passphrase that's difficult to detect
-  via shoulder-surfing, then this may not be a problem for you.
 
 ## Notes
 

user/how-to-guides/how-to-copy-from-dom0.md

@@ -15,7 +15,7 @@ title: How to copy from dom0
 This page covers copying files and clipboard text between [dom0](/doc/glossary/#dom0) and [domUs](/doc/glossary/#domu).
 Since dom0 is special, the processes are different from [copying and pasting text between qubes](/doc/how-to-copy-and-paste-text/) and [copying and moving files between qubes](/doc/how-to-copy-and-move-files/).
 
-## Copying **from** dom0
+## Copying *from* dom0
 
 ### Copying files from dom0
 
@@ -61,7 +61,7 @@ In order to easily copy/paste the contents of logs from dom0 to the inter-VM cli
 
 You may now paste the log contents in qube as you normally would (e.g., Ctrl+Shift+V, then Ctrl+V).
 
-## Copying **to** dom0
+## Copying *to* dom0
 
 Copying anything into dom0 is not advised, since doing so can compromise the security of your Qubes system.
 For this reason, there is no simple means of copying anything into dom0, unlike [copying from dom0](#copying-from-dom0).

user/how-to-guides/how-to-install-software.md

@@ -68,18 +68,39 @@ will appear in the Applications Menu. (If you encounter problems, see
 
 ## Installing software from other sources
 
+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.
+
+### 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
+
 **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
+This method assumes that you are trying to follow instructions to install some piece
-downloaded and installed from another source. This method assumes that you're
+of software in a normal operating system, except *that* operating system is running as a
-trying to follow the instructions to install some piece of software in a normal
+template in Qubes OS.
-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,25 +161,25 @@ 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
+not have normal network access by default. Instead, templates use an
-proxy](#updates-proxy) that allows you to install and update software using
+[updates-proxy](#updates-proxy) which allows you to install and update software using
-the distribution package manager without giving the template direct network
+the distribution's package manager over the proxy connection.
-access.**The updates proxy is already setup to work automatically
+**The updates proxy is already set up to work automatically out-of-the-box and
-out-of-the-box and requires no special action from you.** Most users should
+requires no special action from you.**
-simply follow the normal instructions for [installing software from default
+Most users should simply follow the normal instructions for [installing software
-repositories](#installing-software-from-default-repositories) and
+from default repositories](#installing-software-from-default-repositories)
-[updating](/doc/how-to-update/) software. If your software is not available in
+and [updating](/doc/how-to-update/) software. If your software is not available
-the default repositories, see [installing software from other
+in the default repositories, see [installing software from other
 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
@@ -227,10 +248,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 setopt rpmfusion-free.enabled=1
-sudo dnf config-manager --set-enabled rpmfusion-free-updates
+sudo dnf config-manager setopt rpmfusion-free-updates.enabled=1
-sudo dnf config-manager --set-enabled rpmfusion-nonfree
+sudo dnf config-manager setopt rpmfusion-nonfree.enabled=1
-sudo dnf config-manager --set-enabled rpmfusion-nonfree-updates
+sudo dnf config-manager setopt rpmfusion-nonfree-updates.enabled=1
 sudo dnf upgrade --refresh
 ~~~
 
@@ -432,10 +453,10 @@ these in an app qube you need to take the following steps:
    **app qube** launch the Qube Settings. Then go to the Applications tab and
    click "Refresh Applications"
 
-   The refresh will take a few minutes; after it's complete the Snap app will
+   - The refresh will take a few minutes; after it's complete the Snap app will
-   appear in the app qube's list of available applications. At this point the
+     appear in the app qube's list of available applications. At this point the
-   snap will be persistent within the app qube and will receive updates when
+     snap will be persistent within the app qube and will receive updates when
-   the app qube is running.
+     the app qube is running.
 
 
 ### Autostarting Installed Applications

user/how-to-guides/how-to-organize-your-qubes.md

@@ -336,7 +336,7 @@ her setup looks like this:
   reports.
 
 - **Two qubes for taxes.** Carol has a [Windows
-  qube](https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows.md)
+  qube](/doc/templates/windows/)
   for running her Windows-only tax software. She also has an offline vault
   where she stores all of her tax-related forms and documents, organized by
   year.

user/how-to-guides/how-to-reinstall-a-template.md

@@ -48,14 +48,16 @@ If you want to reinstall more than one template, repeat these instructions for e
 
 1. Clone the existing target template.
 
-   This can be a good idea if you've customized the existing template and want to keep your customizations.
+
-   On the other hand, if you suspect that this template is broken, misconfigured, or compromised, be certain you do not start any VMs using it in the below procedure.
+   - This can be a good idea if you've customized the existing template and want to keep your customizations.
+     On the other hand, if you suspect that this template is broken, misconfigured, or compromised, be certain you do not start any VMs using it in the below procedure.
 
 2. Temporarily change all VMs based on the target template to the new clone template, or remove them.
 
-   This can be a good idea if you have user data in these VMs that you want to keep.
+
-   On the other hand, if you suspect that these VMs (or the templates on which they are based) are broken, misconfigured, or compromised, you may want to remove them instead.
+   - This can be a good idea if you have user data in these VMs that you want to keep.
-   You can do this in Qubes Manager by right-clicking on the VM and clicking **Remove VM**, or you can use the command `qvm-remove <vm-name>` in dom0.
+     On the other hand, if you suspect that these VMs (or the templates on which they are based) are broken, misconfigured, or compromised, you may want to remove them instead.
+     You can do this in Qubes Manager by right-clicking on the VM and clicking **Remove VM**, or you can use the command `qvm-remove <vm-name>` in dom0.
 
 3. Uninstall the target template from dom0:
 

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
 
@@ -32,7 +33,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". 
@@ -65,10 +66,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>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. To update templates and standalones non-interactively, use the command `qubes-vm-update`, and to update dom0, use `qubes-dom0-update`. If you want to perform an update with more advanced user-configurable options (e.g., custom pre- or post-update scripts, custom workarounds), see: [update.qubes-dom0](/doc/salt/#updatequbes-dom0) and [update.qubes-vm](/doc/salt/#updatequbes-vm).
+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)
+
+- 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/).
 
@@ -83,3 +93,113 @@ 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 do not support loading microcode from
+the OS, so firmware updates are the **only** way to obtain microcode updates.
+
+## Firmware update methods
+
+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
+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.

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

@@ -90,9 +90,9 @@ If you don't see anything that looks like your drive, run `sudo udevadm trigger
     qvm-block attach work sys-usb:sdb
     ```
 
-    This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc.
+    - This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc.
 
-    You may also mount one partition at a time by using the same command with the partition number, e.g. `sdb1`.
+    - You may also mount one partition at a time by using the same command with the partition number, e.g. `sdb1`.
 
 3. The block device is now attached to the qube.
    If using a default qube, you may open the Nautilus file manager in the qube, and your drive should be visible in the **Devices** panel on the left.
@@ -106,7 +106,7 @@ If you don't see anything that looks like your drive, run `sudo udevadm trigger
 
 4. When you finish using the block device, click the eject button or right-click and select **Unmount**.
 
-    If you've manually mounted a single partition in the above step, use:
+    - If you've manually mounted a single partition in the above step, use:
 
     ```
     sudo umount mnt
@@ -179,10 +179,10 @@ To attach a file as block device to another qube, first turn it into a loopback
 2. If you want to use the GUI, you're done.
     Click the Device Manager ![device manager icon](/attachment/doc/media-removable.png) and select the `loop0`-device to attach it to another qube.
 
-    If you rather use the command line, continue:
+    - If you rather use the command line, continue:
 
-    In dom0, run `qvm-block` to display known block devices.
+    - In dom0, run `qvm-block` to display known block devices.
-    The newly created loop device should show up:
+      The newly created loop device should show up:
 
     ```shell_session
     ~]$ qvm-block

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

@@ -26,6 +26,7 @@ In Qubes 3.X, the Qubes VM Manager dealt with attachment as well.
 This functionality was moved to the Qubes Device Widget, the tool tray icon with a yellow square located in the top right of your screen by default.
 
 There are currently four categories of devices Qubes understands:
+
  - Microphones
  - Block devices
  - USB devices
@@ -64,7 +65,7 @@ A list of VMs appears, one showing the eject symbol: ![eject icon](/attachment/d
 Only `mic` should be attached to more than one running VM.
 You may *assign* a device to more than one VM (using the `--persistent` option), however, only one of them can be started at the same time.
 
-But be careful: There is a [bug in `qvm-device block` or `qvm-block`](https://github.com/QubesOS/qubes-issues/issues/4692) which will allow you to *attach* a block device to two running VMs.
+But be careful: There is a [bug in](https://github.com/QubesOS/qubes-issues/issues/4692) `qvm-device block` or `qvm-block` which will allow you to *attach* a block device to two running VMs.
 Don't do that!
 
 

user/how-to-guides/how-to-use-disposables.md

@@ -42,7 +42,7 @@ In Qubes 4.2, the qube will now appear in the menu as a disposable template (in
 
 In Qubes 4.1: named disposables can be created under **Application Menu -> Create Qubes VM**, set the qube type  to be _DisposableVM_.
 
-In Qubes 4.2: named disposables can be created by **Application Menu -> Settings -> Qubes Settings -> Create New Qube**. Set the qube type to Named disposable_
+In Qubes 4.2: named disposables can be created by **Application Menu -> Settings -> Qubes Settings -> Create New Qube**. Set the qube type to **Named disposable**.
 
 ## Security
 
@@ -171,6 +171,7 @@ In dom0, add the following line at the beginning of the file `/etc/qubes-rpc/pol
 ~~~
 
 This line means:
+
 - FROM: Any qube
 - TO: A disposable based on `<ONLINE_DISPOSABLE_TEMPLATE>`
 - WHAT: Allow sending an "Open URL" request

user/how-to-guides/how-to-use-pci-devices.md

@@ -45,7 +45,7 @@ There you can attach PCI-devices to a qube.
 
 1. To reach the settings of any qube either
 
-   - Press Alt+F3 to open the application finder, type in the VM name, select the "![appmenu](/attachment/doc/qubes-appmenu-select.png)\[VM-name\]: Qube Settings" menu entry and press enter or click "Launch"!
+   - Press Alt+F3 to open the application finder, type in the VM name, select the ![appmenu](/attachment/doc/qubes-appmenu-select.png) `[VM-name]: Qube Settings` menu entry and press enter or click `Launch`!
    - Select the VM in Qube Manager and click the settings-button or right-click the VM and select `Qube settings`.
    - Click the Domain Manager, hover the VM you want to attach a device to and select "settings" in the additional menu. (only running VMs!)
 

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)**.
@@ -28,15 +28,15 @@ 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/ctap-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.
 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,11 +44,11 @@ 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.
 
-### 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.
 
@@ -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.
 
@@ -87,20 +87,20 @@ 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`.
 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: 
   ```
@@ -111,18 +111,19 @@ 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.
-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.
+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):
@@ -141,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:
 
@@ -154,11 +155,29 @@ This should output something like:
 ```
 ../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
 ```
-
+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:
-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
-
 ```
 qvm-pci attach --persistent personal dom0:00_1a.0
 ```
+
+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
+
+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, 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".
+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 manufacturer's name.
+
+Now you should be able to tell which is the BDF address of the mainboard USB controller or the added USB controller.

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,
@@ -137,7 +144,7 @@ its net qube.
 
 ## policies
 
-In Qubes OS, "policies" govern interactions between qubes, powered by [Qubes' qrexec system](https://www.qubes-os.org/doc/qrexec/).
+In Qubes OS, "policies" govern interactions between qubes, powered by [Qubes' qrexec system](/doc/qrexec/).
 A single policy is a rule applied to a qube or set of qubes, that governs how and when information or assets may be shared with other qubes.  
 An example is the rules governing how files can be copied between qubes.  
 Policy rules are grouped together in files under `/etc/qubes/policy.d`  

user/security-in-qubes/anti-evil-maid.md

@@ -43,7 +43,7 @@ Security Considerations
 However, in its default configuration, installing and using AEM requires attaching a USB drive (i.e., [mass storage device](https://en.wikipedia.org/wiki/USB_mass_storage_device_class)) directly to dom0.
 (The other option is to install AEM to an internal disk.
 However, this carries significant security implications, as explained [here](https://blog.invisiblethings.org/2011/09/07/anti-evil-maid.html).) This presents us with a classic security trade-off: each Qubes user must make a choice between protecting dom0 from a potentially malicious USB drive, on the one hand, and protecting the system from Evil Maid attacks, on the other hand.
-Given the practical feasibility of attacks like [BadUSB](https://srlabs.de/badusb/) and revelations regarding pervasive government hardware backdoors, this is no longer a straightforward decision.
+Given the practical feasibility of attacks like [BadUSB](https://web.archive.org/web/20160304013434/https://srlabs.de/badusb/) and revelations regarding pervasive government hardware backdoors, this is no longer a straightforward decision.
 New, factory-sealed USB drives cannot simply be assumed to be "clean" (e.g., to have non-malicious microcontroller firmware).
 Therefore, it is up to each individual Qubes user to evaluate the relative risk of each attack vector against his or her security model.
 

user/security-in-qubes/data-leaks.md

@@ -48,9 +48,9 @@ Such attacks have been described in the academic literature, but it is doubtful
 3. **Unintentional leaks.** Non-malicious software which is either buggy or doesn't maintain the privacy of user data, whether by design or accident.
    For example, software which automatically sends error reports to a remote server, where these reports contain details about the system which the user did not want to share.
 
-   Both Qubes firewall and an empty NetVM (i.e., setting the NetVM of an app qube to "none") can fully protect against leaks of type 3.
+Both Qubes firewall and an empty NetVM (i.e., setting the NetVM of an app qube to "none") can fully protect against leaks of type 3.
-   However, neither Qubes firewall nor an empty NetVM are guaranteed to protect against leaks of types 1 and 2.
+However, neither Qubes firewall nor an empty NetVM are guaranteed to protect against leaks of types 1 and 2.
-   There are few effective, practical policy measures available to end-users today to stop the leaks of type 1.
+There are few effective, practical policy measures available to end-users today to stop the leaks of type 1.
-   It is likely that the only way to fully protect against leaks of type 2 is to either pause or shut down all other VMs while performing sensitive operations in the target VM(s) (such as key generation).
+It is likely that the only way to fully protect against leaks of type 2 is to either pause or shut down all other VMs while performing sensitive operations in the target VM(s) (such as key generation).
 
 For further discussion, see [this thread](https://groups.google.com/d/topic/qubes-users/t0cmNfuVduw/discussion).

user/security-in-qubes/firewall.md

@@ -14,7 +14,7 @@ title: Firewall
 Introduction
 ----------------------------------
 This page explains use of the firewall in Qubes 4.2, using `nftables`.  
-In Qubes 4.1, all firewall components used `iptables`. For details of that usage see [here](../firewall_4.1/)
+In Qubes 4.1, all firewall components used `iptables`. For details of that usage see [here](../firewall_4.1/).
 
 
 Understanding firewalling in Qubes
@@ -165,7 +165,7 @@ Consider the following example. `mytcp-service` qube has a TCP service running o
     [user@untrusted #]$ qvm-connect-tcp 444:@default:444
     ~~~
 
-> Note: The syntax is the same as SSH tunnel handler. The first `444` correspond to the localport destination of `untrusted`, `@default` the remote machine and the second `444` to the remote machine port.
+- **Note:** The syntax is the same as SSH tunnel handler. The first `444` correspond to the localport destination of `untrusted`, `@default` the remote machine and the second `444` to the remote machine port.
 
 The service of `mytcp-service` running on port `444` is now accessible in `untrusted` as `localhost:444`.
 
@@ -263,13 +263,14 @@ In order to allow a service present in a qube to be exposed to the outside world
 
 As an example we can take the use case of qube QubeDest running a web server listening on port 443 that we want to expose on our physical interface ens6, but only to our local network 192.168.x.y/24.
 
-> Note: To have all interfaces available and configured, make sure the 3 qubes are up and running
+- **Note:** To have all interfaces available and configured, make sure the 3 qubes are up and running
 
-> Note: [Issue #4028](https://github.com/QubesOS/qubes-issues/issues/4028) discusses adding a command to automate exposing the port.
+- **Note:** [Issue #4028](https://github.com/QubesOS/qubes-issues/issues/4028) discusses adding a command to automate exposing the port.
 
 **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`
@@ -278,39 +279,44 @@ You can get this information using various methods, but only the first one can b
 
 Note the IP addresses you will need, they will be required in the next steps.
 
-> Note: The vifx.0 interface is the one used by qubes connected to this netvm so it is _not_ an outside world interface.
+- **Note:** The vifx.0 interface is the one used by qubes connected to this netvm so it is _not_ an outside world interface.
 
 **2. Route packets from the outside world to the FirewallVM**
 
 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; }'
 ```
 
-> Note: the name `custom-dnat-qubeDST` is arbitrary
+- **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 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 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 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 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
+- **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 the steps 2 and 3 described above, for each interface. Alternatively, you can leave out the interface completely.
+- 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.
 
-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 +326,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
+  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;
-  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
+  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 +357,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 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 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 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 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; }'
@@ -371,16 +379,16 @@ 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
+- **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
 
 Once you have confirmed that the counters increase, store these commands in the script `/rw/config/qubes-firewall-user-script`
 
@@ -398,10 +406,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
 ~~~
 

user/security-in-qubes/firewall_4.1.md

@@ -10,8 +10,7 @@ title: Firewall 4.1
 Introduction
 ----------------------------------
 This page explains use of the firewall in Qubes 4.1, using `iptables`.  
-From Qubes 4.2, all firewall components use `nftables`. For details of that usage see [here](../firewall/)
+From Qubes 4.2, all firewall components use `nftables`. For details of that usage see [here](../firewall/).
-
 
 Understanding firewalling in Qubes
 ----------------------------------
@@ -60,14 +59,10 @@ Reconnecting qubes after a NetVM reboot
 
 Normally Qubes doesn't let the user stop a NetVM if there are other qubes running which use it as their own NetVM.
 But in case the NetVM stops for whatever reason (e.g. it crashes, or the user forces its shutdown via qvm-kill via terminal in Dom0), Qubes R4.0 will often automatically repair the connection.
-If it does not, then there is an easy way to restore the connection to the NetVM by issuing in dom0:
+If it does not, then there is an easy way to restore the connection to the NetVM by issuing in dom0: `qvm-prefs <vm> netvm <netvm>`
-
-` qvm-prefs <vm> netvm <netvm> `
 
 Normally qubes do not connect directly to the actual NetVM which has networking devices, but rather to the default sys-firewall first, and in most cases it would be the NetVM that will crash, e.g. in response to S3 sleep/restore or other issues with WiFi drivers.
-In that case it is only necessary to issue the above command once, for the sys-firewall (this assumes default VM-naming used by the default Qubes installation):
+In that case it is only necessary to issue the above command once, for the sys-firewall (this assumes default VM-naming used by the default Qubes installation): `qvm-prefs sys-firewall netvm sys-net`
-
-` qvm-prefs sys-firewall netvm sys-net `
 
 Network service qubes
 ---------------------
@@ -90,7 +85,7 @@ The sys-firewall-2 proxy ensures that:
 
 If you adopt this model, you should be aware that all traffic will arrive at the `network service qube` appearing to originate from the IP address of `sys-firewall-2`.
 
-For the VPN service please also look at the [VPN documentation](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md).
+For the VPN service please also look at the [VPN documentation](https://forum.qubes-os.org/t/configuring-a-proxyvm-vpn-gateway/19061).
 
 Enabling networking between two qubes
 -------------------------------------
@@ -155,11 +150,10 @@ Consider the following example. `mytcp-service` qube has a TCP service running o
 
 - In untrusted, use the Qubes tool `qvm-connect-tcp`:
 
-    ~~~
+    ```
     [user@untrusted #]$ qvm-connect-tcp 444:@default:444
-    ~~~
+    ```
-
+- **Note:** The syntax is the same as SSH tunnel handler. The first `444` correspond to the localport destination of `untrusted`, `@default` the remote machine and the second `444` to the remote machine port.
-> Note: The syntax is the same as SSH tunnel handler. The first `444` correspond to the localport destination of `untrusted`, `@default` the remote machine and the second `444` to the remote machine port.
 
 The service of `mytcp-service` running on port `444` is now accessible in `untrusted` as `localhost:444`.
 
@@ -257,15 +251,16 @@ In order to allow a service present in a qube to be exposed to the outside world
 
 As an example we can take the use case of a web server listening on port 443 that we want to expose on our physical interface eth0, but only to our local network 192.168.x.0/24.
 
-> Note: To have all interfaces available and configured, make sure the 3 qubes are up and running
+  - **Note:** To have all interfaces available and configured, make sure the 3 qubes are up and running
 
-> Note: [Issue #4028](https://github.com/QubesOS/qubes-issues/issues/4028) discusses adding a command to automate exposing the port.
+  - **Note:** [Issue #4028](https://github.com/QubesOS/qubes-issues/issues/4028) discusses adding a command to automate exposing the port.
 
 **1. Identify the IP addresses you will need to use for sys-net, sys-firewall and the destination qube.**
 
 You can get this information from the Settings Window for the qube, or by running this command in each qube:
 `ifconfig | grep -i cast `
 Note the IP addresses you will need.
+
 > Note: The vifx.0 interface is the one used by qubes connected to this netvm so it is _not_ an outside world interface.
 
 **2. Route packets from the outside world to the FirewallVM**
@@ -280,23 +275,23 @@ iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 192.168.x.y -j DNAT
 
 Code the appropriate new filtering firewall rule to allow new connections for the service
 
-```
+  ```
-iptables -I FORWARD 2 -i eth0 -d 10.137.1.z -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT
+  iptables -I FORWARD 2 -i eth0 -d 10.137.1.z -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT
-```
+  ```
 
-> If you want to expose the service on multiple interfaces, repeat the steps described in part 1 for each interface.
+  - If you want to expose the service on multiple interfaces, repeat the steps described in part 1 for each interface.
-> In Qubes R4, at the moment ([QubesOS/qubes-issues#3644](https://github.com/QubesOS/qubes-issues/issues/3644)), nftables is also used which imply that additional rules need to be set in a `qubes-firewall` nft table with a forward chain.
+  - In Qubes R4, at the moment ([QubesOS/qubes-issues#3644](https://github.com/QubesOS/qubes-issues/issues/3644)), nftables is also used which imply that additional rules need to be set in a `qubes-firewall` nft table with a forward chain.
 
 `nft add rule ip qubes-firewall forward meta iifname eth0 ip daddr 10.137.1.z tcp dport 443 ct state new counter accept`
 
 Verify you are cutting through the sys-net VM firewall by looking at its counters (column 2)
 
-```
+  ```
-iptables -t nat -L -v -n
+  iptables -t nat -L -v -n
-iptables -L -v -n
+  iptables -L -v -n
-```
+  ```
+  - **Note:** On Qubes R4, you can also check the nft counters
 
-> Note: On Qubes R4, you can also check the nft counters
 
 ```
 nft list table ip qubes-firewall
@@ -358,7 +353,9 @@ if ! iptables -w -n -L FORWARD | grep --quiet MY-HTTPS; then
 fi
 ~~~
 
-> Note: Again in R4 the following needs to be added:
+
+  - **Note:** Again in R4 the following needs to be added:
+
 
 ~~~
 #############
@@ -389,9 +386,9 @@ Code the appropriate new filtering firewall rule to allow new connections for th
 iptables -I FORWARD 2 -i eth0 -s 192.168.x.0/24 -d 10.137.0.xx -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT
 ```
 
-> Note: If you do not wish to limit the IP addresses connecting to the service, remove the ` -s 192.168.0.1/24 `
+  - **Note:** If you do not wish to limit the IP addresses connecting to the service, remove the ` -s 192.168.0.1/24 `
 
-> Note: On Qubes R4
+  - **Note:** On Qubes R4
 
 ```
 nft add rule ip qubes-firewall forward meta iifname eth0 ip saddr 192.168.x.0/24 ip daddr 10.137.0.xx tcp dport 443 ct state new counter accept

user/security-in-qubes/mfa.md

@@ -46,7 +46,7 @@ and then use it as an additional factor to login to your Qubes system.
     google-authenticator
     ```
 
-3. Walk through the setup instructions 2 which will also generate your QR code for your auth app of choice:
+3. Walk through the setup instructions which will also generate your QR code for your auth app of choice:
 
    ```
    Do you want me to update your “/home/user/.google_authenticator” file (y/n) y
@@ -60,13 +60,13 @@ and then use it as an additional factor to login to your Qubes system.
 
 > **Warning**: in the next session if incorrectly performed, there is the risk of locking yourself out. Before procedding ensure that you have an up-to-date backup.
 >
-> For advanced users, to make sure you can quickly recover, you can also open another loging session in a tty. To do this, you do <kbd>ctrl</kbd>+<kbd>alt</kbd>+<kbd>F2</kbd> and login normally. Should anything go wrong, as long as you don't shut the computer down, you can still access this tty by entering the same key combination and reverting the changes. After you've opened this "backup" login, you can get to your graphical desktop with <kbd>ctrl</kbd>+<kbd>alt</kbd>+<kbd>F1</kbd>.
+> For advanced users, to make sure you can quickly recover, you can also open another loging session in a tty. To do this, you do `ctrl` + `alt` + `F2` and login normally. Should anything go wrong, as long as you don't shut the computer down, you can still access this tty by entering the same key combination and reverting the changes. After you've opened this "backup" login, you can get to your graphical desktop with `ctrl` + `alt` + `F1`.
 
 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 in `/etc/authselect/custom/mfa/system-auth`.
 
    Add the following line right after `auth required pam_faildelay.so delay=2000000`:
 
@@ -89,7 +89,7 @@ Now we are going to add the authenticator as a login requirement:
    sudo authselect select custom/mfa
    ```
 
-Now you can test by locking the screen with <kbd>ctrl</kbd>+<kbd>alt</kbd>+<kbd>l</kbd>. If it was successful and you are pleased with the results, restart your computer.
+Now you can test by locking the screen with `ctrl` + `alt` + `l` . If it was successful and you are pleased with the results, restart your computer.
 
 **Note**: When logging in. the first thing you put is the TOTP secret and then the password. This is true in the screen locker and as well as the session manager (the login window that shows right after you put the disk encryption passphrase).
 
@@ -99,12 +99,12 @@ After this is done, its recommended to do a backup. This is because as long as y
 
 The following assumes you haven't restarted your computer since setting up TOTP secret.
 
-1. Switch to TTY2 with <kbd>ctrl</kbd>+<kbd>alt</kbd>+<kbd>F2</kbd>.
+1. Switch to TTY2 with `ctrl` + `alt` + `F2` .
 2. Revert to the original policy with:
    ```
    sudo authselect select sssd
    ```
-3. Switch back to the graphical desktop with <kbd>ctrl</kbd>+<kbd>alt</kbd>+<kbd>F1</kbd>. You should be able to login normally (without multi-factor authentication).
+3. Switch back to the graphical desktop with `ctrl` + `alt` + `F1` . You should be able to login normally (without multi-factor authentication).
 4. Change the mfa custom policy and apply it again.
 
 #### Lost TOTP / authentication device?
@@ -120,7 +120,8 @@ The second option is recovery from a backup. It will work as long as you include
 The YubiKey / NitroKey3 is a hardware authentication device manufactured by Yubico / NitroKey
 to protect access to computers, networks, and online services that supports
 one-time passwords (OTP), public-key cryptography, and authentication, and the
-Universal 2nd Factor (U2F) and FIDO2 protocols[1] developed by the FIDO Alliance.
+Universal 2nd Factor [(U2F)](https://en.wikipedia.org/wiki/Universal_2nd_Factor)
+and FIDO2 protocols developed by the [FIDO Alliance](https://en.wikipedia.org/wiki/FIDO_Alliance).
 
 You can use a YubiKey / NitroKey3 to enhance the user authentication in Qubes. The following
 instructions explain how to setup the YubiKey / NitroKey3 as an *additional* way to login.
@@ -157,26 +158,28 @@ Note that setting up both a YubiKey and a NitroKey3 is not supported.
 1. Install YubiKey / NitroKey3 software in the template on which your USB VM is based.
    Without this software the challenge-response / HOTP mechanism won't work.
 
-   **YubiKey**
+   - **YubiKey**
 
-   For Fedora.
+     - For Fedora.
 
-    ```
+     ```
-    sudo dnf install ykpers
+     sudo dnf install ykpers
-    ```
+     ```
 
-   For Debian.
+     - For Debian.
 
-    ```
+     ```
-    sudo apt-get install yubikey-personalization
+     sudo apt-get install yubikey-personalization
-    ```
+     ```
    
-   **NitroKey3**
+   - **NitroKey3**
 
-   Follow the installation instructions on the official [NitroKey 
+
+     - Follow the installation instructions on the official [NitroKey 
 website](https://docs.nitrokey.com/software/nitropy/all-platforms/installation).
+
    
-   **WARNING**: *as of April 2024 the official instructions involve using pipx to
+     - **WARNING**: *as of April 2024 the official instructions involve using pipx to
             install the pynitrokey package and its dependencies without any GPG
             verification! This is not a recommended practice, but will soon be
             fixed by NitroKey when they start providing release artifacts with
@@ -184,10 +187,12 @@ website](https://docs.nitrokey.com/software/nitropy/all-platforms/installation).
             Proper packaging and distribution for Debian and perhaps Fedora is
             also planned for the mid-long term.*
             **Installing packages using pip or pipx is not recommended!**
-   
-   **both**
 
-   Shut down your template. Then, either reboot your USB VM (so changes inside
+
+   - **both**
+
+
+     - Shut down your template. Then, either reboot your USB VM (so changes inside
    the template take effect in your USB app qube) or install the packages inside
    your USB VM as well if you would like to avoid rebooting it.
 
@@ -199,64 +204,72 @@ website](https://docs.nitrokey.com/software/nitropy/all-platforms/installation).
     ```
 
 3. Configure your YubiKey / NitroKey3:
+
    
-   **YubiKey**
+   - **YubiKey**
+
    
-   Configure your YubiKey for challenge-response `HMAC-SHA1` mode. This can be
+     - Configure your YubiKey for challenge-response `HMAC-SHA1` mode. This can be
    done on any qube, e.g. a disposable (you need to [attach the
 YubiKey](https://www.qubes-os.org/doc/how-to-use-usb-devices/) to this app qube
-though) or directly on the sys-usb vm.
+though) or directly on the sys-usb vm. You need to (temporarily) install the package "yubikey-personalization-gui" and
-
-   You need to (temporarily) install the package "yubikey-personalization-gui" and
    run it by typing `yubikey-personalization-gui` in the command line.
 
-   - In the program go to `Challenge-Response`,
+       - In the program go to `Challenge-Response`,
-   - select `HMAC-SHA1`,
+       - select `HMAC-SHA1`,
-   - choose `Configuration Slot 2`,
+       - choose `Configuration Slot 2`,
-   - optional: enable `Require user input (button press)` (recommended),
+       - optional: enable `Require user input (button press)` (recommended),
-   - use `fixed 64 bit input` for `HMAC-SHA1 mode`,
+       - use `fixed 64 bit input` for `HMAC-SHA1 mode`,
-   - insert the YubiKey (if not done already) and make sure that it is attached
+       - insert the YubiKey (if not done already) and make sure that it is attached
-     to the vm,
+         to the vm,
-   - press `Write Configuration` once you are ready.
+       - press `Write Configuration` once you are ready.
 
-   **NitroKey3**
+   - **NitroKey3**
 
-   Set up a new NK3 Secrets App HOTP secret by attaching the NitroKey to your
+
+     - Set up a new NK3 Secrets App HOTP secret by attaching the NitroKey to your
    USB qube and running the following commands in it:
-   ```
+
-   AESKEY=$(echo -n "your-20-digit-secret" | base32)
+       ```
-   nitropy nk3 secrets register --kind hotp --hash sha256 --digits-str 8 --counter-start 1 --touch-button loginxs $AESKEY
+       AESKEY=$(echo -n "your-20-digit-secret" | base32)
-   ```
+       nitropy nk3 secrets register --kind hotp --hash sha256 --digits-str 8 --counter-start 1 --touch-button loginxs $AESKEY
-   Note that the 20 digit sequence can contain any printable ASCII character,
+       ```
+
+     - Note that the 20 digit sequence can contain any printable ASCII character,
    e.g. letters, numbers, punctuation marks. The actual `Secret Key (base 32)`
    is the base32 encoded form of that sequence.
 
-   **both**
 
-   We will call the `Secret Key (20 bytes hex)` (YubiKey) or `Secret Key (base 32)` `AESKEY`.
+   - **both**
 
-   - It is recommended to keep a backup of your `AESKEY` in an offline VM used as a vault.
+
-   - Consider keeping a backup of your `AESKEY` on paper and storing it in a safe place.
+     - We will call the `Secret Key (20 bytes hex)` (YubiKey) or `Secret Key (base 32)` `AESKEY`.
-   - If you have multiple YubiKeys for backup purposes (in case one gets
+
-     lost, stolen or breaks) you can write the same settings into other
+       - It is recommended to keep a backup of your `AESKEY` in an offline VM used as a vault.
-YubiKeys. For YubiKeys you can choose "Program multiple YubiKeys" in the program;
+       - Consider keeping a backup of your `AESKEY` on paper and storing it in a safe place.
- make sure to select `Same secret for all keys` in this case. For NitroKeys you can set up
+       - If you have multiple YubiKeys for backup purposes (in case one gets 
-the secret for multiple of them, but you must always use the same NitroKey, because the
+         lost, stolen or breaks) you can write the same settings into other
-HOTP counter will be incremented in dom0 as well as the used NitroKey whenever you make use
+         YubiKeys. For YubiKeys you can choose "Program multiple YubiKeys" in the program;
-of this method. If you want to switch to a different NitroKey later, delete the file
+         make sure to select `Same secret for all keys` in this case. For NitroKeys you can set up
-`/etc/qubes/yk-keys/nk-hotp-counter` in dom0 first to make it work with a fresh NitroKey 3.
+         the secret for multiple of them, but you must always use the same NitroKey, because the
-Do the same if for some reason your counters get desynchronized (it stops working), e.g. due
+         HOTP counter will be incremented in dom0 as well as the used NitroKey whenever you make use
-to connectivity issues (NitroKey3A Minis are known to wear out quickly).
+         of this method. If you want to switch to a different NitroKey later, delete the file
+         `/etc/qubes/yk-keys/nk-hotp-counter` in dom0 first to make it work with a fresh NitroKey 3.
+         Do the same if for some reason your counters get desynchronized (it stops working), e.g. due
+         to connectivity issues (NitroKey3A Minis are known to wear out quickly).
 
 4. **YubiKey**
 
-   Paste your `AESKEY` into `/etc/qubes/yk-keys/yk-secret-key.hex` in dom0.
+
+   - Paste your `AESKEY` into `/etc/qubes/yk-keys/yk-secret-key.hex` in dom0.
    Note that if you had previously used a NitroKey3 with this package, you *must* delete
    the file `/etc/qubes/yk-keys/nk-hotp-secret` or its content!
 
-   **NitroKey3**
 
-   Create the file `/etc/qubes/yk-keys/nk-hotp-secret` in dom0 and paste your `AESKEY` 
+   - **NitroKey3**
+
+
+     - Create the file `/etc/qubes/yk-keys/nk-hotp-secret` in dom0 and paste your `AESKEY` 
    (in base 32 format) into it.
 
 5. As mentioned before, you need to define a new password that is only used in
@@ -264,22 +277,24 @@ to connectivity issues (NitroKey3A Minis are known to wear out quickly).
 `/etc/qubes/yk-keys/login-pass` in dom0. This is considered safe as dom0 is
 ultimately trusted anyway.
 
-    However, if you prefer you can paste a hashed password instead into
+
+    - However, if you prefer you can paste a hashed password instead into
 `/etc/qubes/yk-keys/login-pass-hashed.hex` in dom0.
 
-    You can calculate your hashed password using the following two commands.
+
+    - You can calculate your hashed password using the following two commands.
     First run the following command to store your password in a temporary variable `password`.
     (This way your password will not leak to the terminal command history file.)
 
-    ```
+      ```
-    read -r password
+      read -r password
-    ```
+      ```
 
-    Now run the following command to calculate your hashed password.
+    - Now run the following command to calculate your hashed password.
 
-    ```
+      ```
-    echo -n "$password" | openssl dgst -sha1 | cut -f2 -d ' '
+      echo -n "$password" | openssl dgst -sha1 | cut -f2 -d ' '
-    ```
+      ```
 
 6. To enable multi-factor authentication for a service, you need to add
 
@@ -353,7 +368,7 @@ In dom0:
 
 In your USB VM:
 
-3. Create udev hook.
+1. Create udev hook.
    Store it in `/rw/config` to have it persist across VM restarts.
    For example name the file `/rw/config/yubikey.rules`.
    Add the following line:
@@ -362,7 +377,7 @@ In your USB VM:
    ACTION=="remove", SUBSYSTEM=="usb", ENV{ID_SECURITY_TOKEN}=="1", RUN+="/usr/bin/qrexec-client-vm dom0 custom.LockScreen"
    ```
 
-4. Ensure that the udev hook is placed in the right place after VM restart.
+2. Ensure that the udev hook is placed in the right place after VM restart.
    Append to `/rw/config/rc.local`:
 
    ```
@@ -370,13 +385,13 @@ In your USB VM:
    udevadm control --reload
    ```
 
-5. Then make `/rw/config/rc.local` executable.
+3. Then make `/rw/config/rc.local` executable.
 
    ```
    sudo chmod +x /rw/config/rc.local
    ```
 
-6. For changes to take effect, you need to call this script manually for the first time.
+4. For changes to take effect, you need to call this script manually for the first time.
 
    ```
    sudo /rw/config/rc.local

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.

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.
@@ -297,7 +303,7 @@ In this example, the following keys are stored in the following locations (see b
 
 * `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.
+   - 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).
@@ -306,7 +312,7 @@ In this example, the following keys are stored in the following locations (see b
    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.
+   - 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.
@@ -314,40 +320,40 @@ In this example, the following keys are stored in the following locations (see b
 
 * `ssb` (secret subkey)
 
-   Depending on your needs, you may wish to create two different subkeys: one for **signing (S)** and one for **encryption (E)**.
+   - 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.
+   - 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.
+   - 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.
+   - 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.
+   - 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 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.
+   - 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.
 

user/security-in-qubes/vm-sudo.md

@@ -59,9 +59,11 @@ user ALL=(ALL) NOPASSWD: ALL
 #
 # joanna.
 ```
+
 The core of this statement continues to reflect the views of the Qubes developers.
 
 Passwordless root is provided by the `qubes-core-agent-passwordless-root` package.  
+
 Details of the implementation are [here](/doc/vm-sudo-implementation).
 
 [Minimal templates](/doc/templates/minimal/), which are intended for use by advanced users, do not have this package installed by default.

user/templates/debian/debian-upgrade.md

@@ -179,7 +179,7 @@ command is required:
 ### Debian 10 ("Buster")
 
 Please see [Debian's Buster upgrade
-instructions](https://www.debian.org/releases/buster/amd64/release-notes/ch-upgrading.en.html).
+instructions](https://www.debian.org/releases/buster/amd64/release-notes.en.txt).
 
 ### Debian 9 ("Stretch")
 
@@ -189,13 +189,11 @@ instructions](https://www.debian.org/releases/buster/amd64/release-notes/ch-upgr
 
 * If sound is not working, you may need to enable the Qubes testing repository
   to get the testing version of `qubes-gui-agent`. This can be done by editing
-  the `/etc/apt/sources.list.d/qubes-r4.list` file and uncommenting the `Qubes
+  the `/etc/apt/sources.list.d/qubes-r4.list` file and uncommenting the `Qubes Updates Candidates` repo.
-  Updates Candidates` repo.
 
 * User-initiated updates/upgrades may not run when a template first starts.
   This is due to a new Debian config setting that attempts to update
-  automatically; it should be disabled with `sudo systemctl disable
+  automatically; it should be disabled with `sudo systemctl disable apt-daily.{service,timer}`.
-  apt-daily.{service,timer}`.
 
 Relevant discussions:
 
@@ -205,12 +203,12 @@ Relevant discussions:
 * [User apt commands blocked on startup](https://github.com/QubesOS/qubes-issues/issues/2621)
 
 Also see [Debian's Stretch upgrade
-instructions](https://www.debian.org/releases/stretch/amd64/release-notes/ch-upgrading.en.html).
+instructions](https://www.debian.org/releases/stretch/amd64/release-notes.en.txt).
 
 ### Debian 8 ("Jessie")
 
 Please see [Debian's Jessie upgrade
-instructions](https://www.debian.org/releases/jessie/amd64/release-notes/ch-upgrading.en.html).
+instructions](https://www.debian.org/releases/jessie/amd64/release-notes.en.txt).
 
 ### End-of-life (EOL) releases
 

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 name of the template you wish to install.)
-   (Replace `XX` with the Debian version number 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/).
 
@@ -60,7 +59,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.
 
 ```
@@ -98,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

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
@@ -97,10 +97,10 @@ The same general procedure may be used to upgrade any template based on the stan
 
     This key was already checked when it was installed (notice that the "From" line refers to a location on your local disk), so you can safely say yes to this prompt.
 
-    **Note:** If you encounter no errors, proceed to step 4.
+     - **Note:** If you encounter no errors, proceed to step 4.
     If you do encounter errors, see the next two points first.
 
-     * If `dnf` reports that you do not have enough free disk space to proceed
+     - If `dnf` reports that you do not have enough free disk space to proceed
        with the upgrade process, create an empty file in dom0 to use as a cache
        and attach it to the template as a virtual disk.
 
@@ -116,16 +116,12 @@ 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.
 
-     * `dnf` may complain:
+     - `dnf` may error with the text: `At least X MB more space needed on the / filesystem.`
-
-        `
-        At least X MB more space needed on the / filesystem.
-        `
 
        In this case, one option is to [resize the template's disk image](/doc/resize-disk-image/) before reattempting the upgrade process.
        (See [Additional Information](#additional-information) below for other options.)
@@ -185,7 +181,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>
 ```

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 name of the Fedora template you wish to install.)
-   (Replace `XX` with the Fedora version number of the 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/).
 

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).
+software. Software that you use in most everyday tasks, is installed within [templates](/doc/glossary/#template).
-Each template shares its root filesystem (i.e., all of its programs and system
+When using Qubes OS, you normally work in [app qubes](/doc/glossary/#app-qube).
-files) with all the qubes based on it. [App qubes](/doc/glossary/#app-qube) are
+App qubes are based on a *template* qube (or more simply, just *a template*).
-where you run your software and store your data.
+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,21 +117,24 @@ 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. :
+
 ```
 $ qvm-template  --enablerepo qubes-templates-community install <template_name>
 ```
+
 To permanently enable a repo, set the line `enabled = 1` in the repo definition in `/etc/qubes/repo-templates`.  
 To permanently disable, set the line to `enabled = 0`.
 
@@ -145,7 +156,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
@@ -158,68 +169,21 @@ 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.
+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.
-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:
 
+Alternatively, to remove a template via the command line in dom0:
 ```
-$ qvm-template 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_NAME> is the first column from the output of:
-template package.
-
-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
+$ qvm-template list --installed
-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
+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.
-address these warnings.
 
-If the uninstallation command doesn't work, pay close attention to
+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).
-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:
-
-```
-$ 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>
-```
 
 ## Reinstalling
 
@@ -434,8 +398,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
+  Builder](https://github.com/QubesOS/qubes-builderv2/). In particular, some
-  available in source code form only. For the technical details of the template
+  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.

user/templates/windows/migrate-to-4-1.md

@@ -33,6 +33,7 @@ While this is somewhat straightforward, things get difficult if QWT 4.0.1.3 was
 ## Preparation for Windows 10 and 11
 
 If there is a drive `D:` from this earlier installation of Qubes Windows Tools, it will probably contain incomplete private data; especially the folder `AppData` containing program configuration data will be missing. In this situation, it may be better to perform a new Windows installation, because repair may be difficult and trouble-prone.
+
 - First, be sure that the automatic repair function is disabled. In a command window, execute `bcdedit /set recoveryenabled NO`, and check that this worked by issuing the command `bcdedit`, without parameters, again.
 - Now, uninstall QWT 4.0.1.3, using the Apps and Features function of Windows. This will most likely result in a crash.
 - Restart Windows again, possibly two or three times, until repair options are offered. By hitting the F8 key, select the restart menu, and there select a start in safe mode (in German, it's option number 4).
@@ -51,4 +52,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>

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

@@ -32,16 +32,16 @@ Below is a breakdown of the feature availability depending on the windows versio
 
 |             Feature                  |  Windows 7 x64 | Windows 10 x64 |
 | ------------------------------------ | :------------: | :------------: |
-| Qubes Video Driver                   |        +       |       -        |
+| Qubes Video Driver                   |        y       |       n        |
-| Qubes Network Setup                  |        +       |       +        |
+| Qubes Network Setup                  |        y       |       y        |
-| Private Volume Setup (move profiles) |        +       |       +        |
+| Private Volume Setup (move profiles)  |        y       |       y        |
-| File sender/receiver                 |        +       |       +        |
+| File sender/receiver                 |        y       |       y        |
-| Clipboard Copy/Paste                 |        +       |       +        |
+| Clipboard Copy/Paste                 |        y       |       y        |
-| Application shortcuts                |        +       |       +        |
+| Application shortcuts                |        y       |       y        |
-| Copy/Edit in Disposable VM           |        +       |       +        |
+| Copy/Edit in Disposable VM           |        y       |       y        |
-| Block device                         |        +       |       +        |
+| Block device                         |        y       |       y        |
-| USB device                           |        +       |       +        |
+| USB device                           |        y       |       y        |
-| Audio                                |        -       |       -        |
+| Audio                                |        n       |       n        |
 
 Qubes Windows Tools are open source and are distributed under a GPL license.
 
@@ -79,9 +79,9 @@ This will allow you to install the Qubes Windows Tools on Windows 10 both as a S
         
 		certutil -hashfile C:\qubes-tools-4.0.1.3.exe SHA256
 
-	And compare it the value to `148A2A993F0C746B48FA6C5C9A5D1B504E09A7CFBA3FB931A4DCF86FDA4EC9B1` (**it has to exactly match for security reasons**). If it matches, feel free to continue the installation. If not, repeat the download to make sure it was not corrupted due to a network problem. If keeps on not matching it might be an attacker attempting to do something nasty to your system -- Ask for support.
+	- And compare it the value to `148A2A993F0C746B48FA6C5C9A5D1B504E09A7CFBA3FB931A4DCF86FDA4EC9B1` (**it has to exactly match for security reasons**). If it matches, feel free to continue the installation. If not, repeat the download to make sure it was not corrupted due to a network problem. If keeps on not matching it might be an attacker attempting to do something nasty to your system -- Ask for support.
 
-    **Note**: This is a workaround for installing the qubes windows tools on windows 10 since the standard way is broken.
+    - **Note**: This is a workaround for installing the qubes windows tools on windows 10 since the standard way is broken.
 
  7. Install Qubes Windows Tools 4.0.1.3 by starting `qubes-tools-4.0.1.3.exe`, not selecting the `Xen PV disk drivers` and the `Move user profiles` (which would probably lead to problems in Windows, anyhow). If during installation, the Xen driver requests a reboot, select "No" and let the installation continue - the system will be rebooted later.
 
@@ -98,7 +98,9 @@ This will allow you to install the Qubes Windows Tools on Windows 10 both as a S
  
  12. Lastly to enable file copy operations to a Windows 10 VM the `default_user` property should be set the `<username>` that you use to login to the Windows VM. This can be done via the following command on a `dom0` terminal: *(where `<VMname>` is the name of your Windows 10 VM)*
         
-		`qvm-prefs <VMname> default_user <username> `
+        ```
+        qvm-prefs <VMname> default_user <username> 
+        ```
 
   **Note:** If this property is not set or set to a wrong value, files copied to this VM are stored in the folder
 		
@@ -165,6 +167,7 @@ Installing Xen's PV drivers in the VM will lower its resources usage when using
 2. installing Qubes Windows Tools (QWT), which bundles Xen's PV drivers.
 
 Notes about using Xen's VBD (storage) PV driver:
+
 - **Windows 7:** installing the driver requires a fully updated VM or else you'll likely get a BSOD and a VM in a difficult to fix state. Updating Windows takes *hours* and for casual usage there isn't much of a performance between the disk PV driver and the default one; so there is likely no need to go through the lengthy Windows Update process if your VM doesn't have access to untrusted networks and if you don't use I/O intensive apps. If you plan to update your newly installed Windows VM it is recommended that you do so *before* installing Qubes Windows Tools (QWT). If QWT are installed, you should temporarily re-enable the standard VGA adapter in Windows and disable Qubes' (see the section above).
 - the option to install the storage PV driver is disabled by default in Qubes Windows Tools 
 - in case you already had QWT installed without the storage PV driver and you then updated the VM, you may then install the driver from Xen's site (xenvbd.tar).
@@ -317,8 +320,8 @@ To override global settings for a specific component, create a new key under the
 
 Component-specific settings currently available:
 
-|**Component**|**Setting**|**Type**|**Description**|**Default value**|
+|   Component   |   Setting   |   Type     |   Description                                   |   Default value   |
-|:------------|:----------|:-------|:--------------|:----------------|
+|:--------------|:------------|:-----------|:------------------------------------------------|:------------------|
 |qga|DisableCursor|DWORD|Disable cursor in the VM. Useful for integration with Qubes desktop so you don't see two cursors. Can be disabled if you plan to use the VM through a remote desktop connection of some sort. Needs gui agent restart to apply change (locking OS/logoff should be enough since qga is restarted on desktop change).|1|
 
 Troubleshooting
@@ -332,11 +335,12 @@ 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`.
-Xen logs (/var/log/xen/console/guest-*) are also useful as they contain pvdrivers diagnostic output.
+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:
 
-||
+| Component  |  Description                                                                                                           |
+|:-----------|:-----------------------------------------------------------------------------------------------------------------------|
 |qrexec-agent|Responsible for most communication with Qubes (dom0 and other domains), secure clipboard, file copying, qrexec services.|
 |qrexec-wrapper|Helper executable that's responsible for launching qrexec services, handling their I/O and vchan communication.|
 |qrexec-client-vm|Used for communications by the qrexec protocol.|

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

@@ -42,26 +42,27 @@ If you prefer to download the corresponding .rpm files for manual QWT installati
 
 **Note**: If you choose to move profiles, drive letter `Q:` must be assigned to the secondary (private) disk.
 
-**Note**: Xen PV disk drivers are not installed by default. This is because they seem to cause problems (BSOD = Blue Screen Of Death). We're working with upstream devs to fix this. *However*, the BSOD seems to only occur after the first boot and everything works fine after that. **Enable the drivers at your own risk** of course, but we welcome reports of success/failure in any case (backup your VM first!). With disk PV drivers absent `qvm-block` will not work for the VM, but you can still use standard Qubes inter-VM file copying mechanisms. On the other hand, the Xen PV drivers allow USB device access even without QWT installation if `qvm-features stubdom-qrexec` is set as `1`
+**Note**: Xen PV disk drivers are not installed by default. This is because they seem to cause problems (BSOD = Blue Screen Of Death). We're working with upstream devs to fix this. *However*, the BSOD seems to only occur after the first boot and everything works fine after that. **Enable the drivers at your own risk** of course, but we welcome reports of success/failure in any case (backup your VM first!). With disk PV drivers absent `qvm-block` will not work for the VM, but you can still use standard Qubes inter-VM file copying mechanisms. On the other hand, the Xen PV drivers allow USB device access even without QWT installation if `qvm-features stubdom-qrexec` is set as `1`.
 
 Below is a breakdown of the feature availability depending on the windows version:
 
 |             Feature                  |  Windows 7 x64 | Windows 8.1/10/11 x64 |
 | ------------------------------------ | :------------: | :-------------------: |
-| Qubes Video Driver                   |        +       |           -           |
+| Qubes Video Driver                   |        y       |           n           |
-| Qubes Network Setup                  |        +       |           +           |
+| Qubes Network Setup                  |        y       |           y           |
-| Private Volume Setup (move profiles) |        +       |           +           |
+| Private Volume Setup (move profiles)  |        y       |           y           |
-| File sender/receiver                 |        +       |           +           |
+| File sender/receiver                 |        y       |           y           |
-| Clipboard Copy/Paste                 |        +       |           +           |
+| Clipboard Copy/Paste                 |        y       |           y           |
-| Application shortcuts                |        +       |           +           |
+| Application shortcuts                |        y       |           y           |
-| Copy/Edit in Disposable VM           |        +       |           +           |
+| Copy/Edit in Disposable VM           |        y       |           y           |
-| Block device                         |        +       |           +           |
+| Block device                         |        y       |           y           |
-| USB device                           |        +       |           +           |
+| USB device                           |        y       |           y           |
-| Audio                                |        +       |           +           |
+| Audio                                |        y       |           y           |
 
 Qubes Windows Tools are open source and are distributed under a GPL license.
 
 **Notes:**
+
 - Currently only 64-bit versions of Windows 7, 8.1, 10 and 11 are supported by Qubes Windows Tools. Only emulated SVGA GPU is supported (although [there has been reports](https://groups.google.com/forum/#!topic/qubes-users/cmPRMOkxkdA) on working GPU passthrough).
 - This page documents the process of installing Qubes Windows Tools in version **R4.1**.
 - *In testing VMs only* it's probably a good idea to install a VNC server before installing QWT. If something goes very wrong with the Qubes gui agent, a VNC server should still allow access to the OS.
@@ -75,11 +76,11 @@ Qubes Windows Tools are open source and are distributed under a GPL license.
  2. In the command prompt type `bcdedit /set testsigning on`
  3. Reboot your Windows VM
 
-In the future this step will not be necessary anymore, because we will sign our drivers with a publicly verifiable certificate. However, it should be noted that even now, the fact that those drivers are not digitally signed, this doesn't affect security of the Windows VM in 'any' way. This is because the actual installation `iso` file can be verified as described in step 3 below. The only downside of those drivers not being signed is the inconvenience to the user that he or she must disable the signature enforcement policy before installing the tools.
+In the future this step will not be necessary anymore, because we will sign our drivers with a publicly verifiable certificate. However, it should be noted that even, given the fact that those drivers are not digitally signed, this doesn't affect security of the Windows VM in 'any' way. This is because the actual installation `iso` file can be verified as described in step 3 below. The only downside of those drivers not being signed is the inconvenience to the user that he or she must disable the signature enforcement policy before installing the tools.
 
 The Xen PV Drivers bundled with QWT are signed by a Linux Foundation certificate. Thus Windows 10 and 11 do not require this security mitigation.
 
-**Warning:** it is recommended to increase the default value of Windows VM's `qrexec_timeout` property from 60 (seconds) to, for example, 300. During one of the first reboots after Windows Tools installation Windows user profiles are moved onto the private VM's virtual disk (private.img) and this operation can take some time. Moving profiles and, later on, updating a Windows installation, is performed in an early boot phase when `qrexec` is not yet running, so timeout may occur with the default value. To change the property use this command in `dom0`: *(where `<VMname>` is the name of your Windows VM)*
+**Warning:** it is recommended to increase the default value of Windows VM's `qrexec_timeout` property from 60 (seconds) to, for example, 300. During one of the first reboots after Windows Tools installation Windows user profiles are moved onto the private VM's virtual disk (private.img) and this operation can take some time. Moving profiles and, later on, updating a Windows installation, is performed in an early boot phase when `qrexec` is not yet running, so timeout may occur with the default value. To change the property use this command in `dom0`: *(where* `<VMname>` *is the name of your Windows VM)*
 
 		[user@dom0 ~] $ qvm-prefs <VMname> qrexec_timeout 7200
 
@@ -125,33 +126,40 @@ Installing the Qubes Windows Tools on Windows 7, 8.1, 10 and 11 both as a Standa
 
  4. Install Qubes Windows Tools by starting `qubes-tools-x64.msi` (logged in as administrator), optionally selecting the `Xen PV disk drivers`. For installation in a template, you should select `Move user profiles`.
 	
-	[![QWT_install_select](/attachment/doc/QWT_install_select.png)](/attachment/doc/QWT_install_select.png)
+    [![QWT_install_select](/attachment/doc/QWT_install_select.png)](/attachment/doc/QWT_install_select.png)
 
-	Several times, Windows security may ask for confirmation of driver installation. Driver installation has to be allowed; otherwise the installation of Qubes Windows Tools will abort.
+    Several times, Windows security may ask for confirmation of driver installation. Driver installation has to be allowed; otherwise the installation of Qubes Windows Tools will abort.
 	
-	[![QWT_install_driver](/attachment/doc/QWT_install_driver.png)](/attachment/doc/QWT_install_driver.png)
+    [![QWT_install_driver](/attachment/doc/QWT_install_driver.png)](/attachment/doc/QWT_install_driver.png)
 
-	If during installation, the Xen driver requests a reboot, select "No" and let the installation continue - the system will be rebooted later.
+    If during installation, the Xen driver requests a reboot, select "No" and let the installation continue - the system will be rebooted later.
 
-	[![QWT_install_no_restart](/attachment/doc/QWT_install_no_restart.png)](/attachment/doc/QWT_install_no_restart.png)
+    [![QWT_install_no_restart](/attachment/doc/QWT_install_no_restart.png)](/attachment/doc/QWT_install_no_restart.png)
 
  5. After successful installation, the Windows VM must be shut down and started again, possibly a couple of times. On each shutdown, wait until the VM is really stopped, i.e. Qubes shows no more activity.
 
- 6. Qubes will automatically detect that the tools have been installed in the VM and will set appropriate properties for the VM, such as `qrexec_installed`, `guiagent_installed`, and `default_user`. This can be verified (but is not required) using the `qvm-prefs` command  *(where `<VMname>` is the name of your Windows VM)*:
+ 6. Qubes will automatically detect that the tools have been installed in the VM and will set appropriate properties for the VM, such as `qrexec_installed`, `guiagent_installed`, and `default_user`. This can be verified (but is not required) using the `qvm-prefs` command  *(where* `<VMname>` *is the name of your Windows VM)*:
 
-	        [user@dom0 ~] $ qvm-prefs <VMname>
+
+    ```
+        [user@dom0 ~] $ qvm-prefs <VMname>
+    ```
 
  	It is advisable to set some other parameters in order to enable audio and USB block device access, synchronize the Windows clock with the Qubes clock, and so on:
 	        
-	        [user@dom0 ~] $ qvm-features <VMname> audio-model ich9
+    ```
-	        [user@dom0 ~] $ qvm-features <VMname> stubdom-qrexec 1
+	    [user@dom0 ~] $ qvm-features <VMname> audio-model ich9
-	        [user@dom0 ~] $ qvm-features <VMname> timezone localtime
+	    [user@dom0 ~] $ qvm-features <VMname> stubdom-qrexec 1
+	    [user@dom0 ~] $ qvm-features <VMname> timezone localtime
+    ```
 
-	For audio, the parameter `audio-model`can be selected as `ich6` or `ich9`; select the value that gives the best audio quality. Audio quality may also be improved by setting the following parameters, but this can depend on the Windows version and on your hardware:
+	For audio, the parameter `audio-model` can be selected as `ich6` or `ich9`; select the value that gives the best audio quality. Audio quality may also be improved by setting the following parameters, but this can depend on the Windows version and on your hardware:
-
+    
-	        [user@dom0 ~] $ qvm-features <VMname> timer-period 1000
+    ```
-	        [user@dom0 ~] $ qvm-features <VMname> out.latency 10000
+	    [user@dom0 ~] $ qvm-features <VMname> timer-period 1000
-	        [user@dom0 ~] $ qvm-features <VMname> out.buffer-length 4000
+	    [user@dom0 ~] $ qvm-features <VMname> out.latency 10000
+	    [user@dom0 ~] $ qvm-features <VMname> out.buffer-length 4000
+    ```
 
 	With the value `localtime` the dom0 `timezone` will be provided to virtual hardware, effectively setting the Windows clock to that of Qubes. With a digit value (negative or positive) the guest clock will have an offset (in seconds) applied relative to UTC.
 
@@ -170,16 +178,11 @@ Installing the Qubes Windows Tools on Windows 7, 8.1, 10 and 11 both as a Standa
 	 - Terminate the registry editor.
 	
  	 After the next boot, the VM will start in seamless mode.
-	
 	 If Windows is used in a TemplateVM / AppVM combination, this registry fix has to be applied to the TemplateVM, as the `HKLM` registry key belongs to the template-based part of the registry.
 	
- 10. Lastly to enable file copy operations to a Windows VM, the `default_user` property of this VM should be set to the `<username>` that you use to login to the Windows VM. This can be done via the following command on a `dom0` terminal: *(where `<VMname>` is the name of your Windows VM)*
+ 10. Lastly to enable file copy operations to a Windows VM, the `default_user` property of this VM should be set to the `<username>` that you use to login to the Windows VM. This can be done via the following command on a `dom0` terminal: `[user@dom0 ~] $ qvm-prefs <VMname> default_user <username>` *(where* `<VMname>` *is the name of your Windows VM)*.
-	
-		`[user@dom0 ~] $ qvm-prefs <VMname> default_user <username>`
   
-  **Warning:** If this property is not set or set to a wrong value, files copied to this VM are stored in the folder
+  **Warning:** If this property is not set or set to a wrong value, files copied to this VM are stored in the folder `C:\Windows\System32\config\systemprofile\Documents\QubesIncoming\<source_VM>`.
- 
- 		C:\Windows\System32\config\systemprofile\Documents\QubesIncoming\<source_VM>
 
  If the target VM is an AppVM, this has the consequence that the files are stored in the corresponding TemplateVM and so are lost on AppVM shutdown.
 
@@ -188,6 +191,7 @@ Installing the Qubes Windows Tools on Windows 7, 8.1, 10 and 11 both as a Standa
 Installing Xen's PV drivers in the VM will lower its resources usage when using network and/or I/O intensive applications, but *may* come at the price of system stability (although Xen's PV drivers on a Windows VM are usually very stable). They can be installed as an optional part of Qubes Windows Tools (QWT), which bundles Xen's PV drivers.
 
 **Notes** about using Xen's VBD (storage) PV driver:
+
 - **Windows 7:** Installing the driver requires a fully updated VM or else you'll likely get a BSOD ("Blue Screen Of Death") and a VM in a difficult to fix state. Updating Windows takes *hours* and for casual usage there isn't much of a performance between the disk PV driver and the default one; so there is likely no need to go through the lengthy Windows Update process if your VM doesn't have access to untrusted networks and if you don't use I/O intensive apps or attach block devices. If you plan to update your newly installed Windows VM it is recommended that you do so *before* installing Qubes Windows Tools.  Installing the driver will probably cause Windows 7 activation to become invalid, but the activation can be restored using the Microsoft telephone activation method. 
 - The option to install the storage PV driver is disabled by default in Qubes Windows Tools 
 - In case you already had QWT installed without the storage PV driver and you then updated the VM, you may then install the driver by again starting the QWT installer and selecting the change option.
@@ -267,7 +271,7 @@ Windows qubes can be used as disposables, like any other Linux-based qubes. On c
 	- Name the link, e.g. as `Command Prompt`.
 	- Close the Window with `OK`.
 	- Shut down this AppVM.
-- In the Qube Manager, refresh the applications of the newly created AppVM and select those applications that you want to make available from the disposable. Alternatively, in dom0 execute the command `qvm-sync-appmenus <VMname>`, *where `<VMname>` is the name of your windows qube*.
+- In the Qube Manager, refresh the applications of the newly created AppVM and select those applications that you want to make available from the disposable. Alternatively, in dom0 execute the command `qvm-sync-appmenus <VMname>`, *where* `<VMname>` *is the name of your windows qube*.
 - In the Qube Manager, go to the "Advanced" tab and enable the option `Disposable template` for your Windows qube.  Alternatively, in dom0 execute the commands `qvm-prefs <VMname> template_for_dispvms True` and `qvm-features <VMname> appmenus-dispvm 1`.
 - Click `Apply`.
 - 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>`.
@@ -277,7 +281,7 @@ Now you should have a menu `Disposable: <VMname>` containing the applications th
 
 For further information on usage of disposables, see [How to use disposables](/doc/how-to-use-disposables/).
 
-**Caution:** *If a Windows-based disposable is used from another qube via the `Open/Edit in DisposableVM` command, this disposable may not close automatically, due to the command prompt window still running in this dispvm. In this case, the disposable has to be shut down  manually.*
+**Caution:** *If a Windows-based disposable is used from another qube via the* `Open/Edit in DisposableVM` *command, this disposable may not close automatically, due to the command prompt window still running in this dispvm. In this case, the disposable has to be shut down  manually.*
 
 ## Installation logs
 
@@ -311,8 +315,8 @@ To override global settings for a specific component, create a new key under the
 	
 Component-specific settings currently available:
 
-|**Component**|**Setting**|**Type**|**Description**|**Default value**|
+|   Component   |   Setting   |   Type     |   Description                                   |   Default value   |
-|:------------|:----------|:-------|:--------------|:----------------|
+|:--------------|:------------|:-----------|:------------------------------------------------|:------------------|
 |qga|DisableCursor|DWORD|Disable cursor in the VM. Useful for integration with Qubes desktop so you don't see two cursors. Can be disabled if you plan to use the VM through a remote desktop connection of some sort. Needs gui agent restart to apply change (locking OS/logoff should be enough since qga is restarted on desktop change).|1|
 
 ## Troubleshooting

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

@@ -16,11 +16,13 @@ title: How to install Windows qubes in Qubes OS 4.0
 If you just want something simple and you can live without some features.
 
 Works:
+
 - display (1440x900 or 1280x1024 are a nice fit onto FHD hw display)
 - keyboard (incl. correct mapping), pointing device
 - network (emulated Realtek NIC)
 
 Does not work:
+
 - copy & paste (the qubes way)
 - copying files into / out of the VM (the qubes way)
 - assigning USB devices (the qubes way via the tray applet)
@@ -29,6 +31,7 @@ Does not work:
 - all other features/hardware needing special tool/driver support
 
 Installation procedure:
+
 - Have the Windows 10 ISO image (I used the 64-bit version) downloaded in some qube.
 - Create a new Qube:
   - Name: Win10, Color: red
@@ -219,6 +222,7 @@ At that point you should have a functional and stable Windows VM, although witho
 ## Windows as a template
 
 Windows 7 and 10 can be installed as TemplateVM by selecting
+
 ~~~
 qvm-create --class TemplateVM --property virt_mode=HVM --property kernel='' --label black Windows-template
 ~~~
@@ -231,6 +235,7 @@ when creating the VM. To have the user data stored in AppVMs depending on this t
 For Windows 10, configuration data like those stored in directories like `AppData` still remain in the TemplateVM, such that their changes are lost each time the AppVM shuts down. In order to make permanent changes to these configuration data, they have to be changed in the TemplateVM, meaning that applications have to be started there, which violates and perhaps even endangers the security of the TemplateVM. Such changes should be done only if absolutely necessary and with great care. It is a good idea to test them first in a cloned TemplateVM before applying them in the production VM.
 
 AppVMs based on these templates can be created the normal way by using the Qube Manager or by specifying
+
 ~~~
 qvm-create --class=AppVM --template=<VMname> 
 ~~~

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

@@ -34,7 +34,7 @@ For better integration, a set of drivers and services, called Qubes Windows Tool
 
 ## Importing a Windows VM from an earlier version of Qubes
 
-- Importing from R3.2 or earlier will not work, because  Qubes R3.2 has the old stubdomain by default and this is preserved over backup and restore (as Windows otherwise won't boot.
+- Importing from R3.2 or earlier will not work, because  Qubes R3.2 has the old stubdomain by default and this is preserved over backup and restore (as Windows otherwise won't boot).
 
 - Importing from R4.0 should work, see [Migrate backups of Windows VMs created under Qubes R4.0 to R4.1](/doc/templates/windows/migrate-to-4-1).
 
@@ -46,6 +46,7 @@ For better integration, a set of drivers and services, called Qubes Windows Tool
 However, if you are an expert or want to do it manually you may continue below.
 
 **Notes:**
+
 - The instructions may work on other versions than Windows 7, 8.1, 10 and 11 x64 but haven't been tested.
 - Qubes Windows Tools (QWT) only supports Windows 7, 8.1, 10 and 11 x64. For installation, see [Qubes Windows Tools](/doc/templates/windows/qubes-windows-tools-4-1).
 
@@ -61,46 +62,49 @@ Unofficial “debloated” ISOs from projects like reviOS 18 or ameliorated 10 c
 
 Create a VM named WindowsNew in [HVM](/doc/hvm/) mode (Xen's current PVH limitations precludes from using PVH). This can be done in either of two ways:
 
-- Using Qube Manager
+- Using Qube Manager: In order to create the new qube, select the command Qube -> New Qube in the Qube Manager:
 
-   In order to create the new qube, select the command Qube -> New Qube in the Qube Manager::
+  - Name: `WindowsNew`, Color: `orange` (for a standalone qubes, `black` for a template)
-     - Name: `WindowsNew`, Color: `orange` (for a standalone qubes, `black` for a template)
+  - Type: `StandaloneVM (fully persistent)` or `TemplateVM (template home, persistent root)`
-     - Type: `StandaloneVM (fully persistent)` or `TemplateVM (template home, persistent root)`
+  - Template: `(none)`
-     - Template: `(none)`
+  - Networking: `sys-firewall (default)`
-     - Networking: `sys-firewall (default)`
+  - Launch settings after creation: check
-     - Launch settings after creation: check
+  - Click "OK".
-     - Click "OK".
+    - Settings:
-  
+      - Basic:
-     - Settings:
+        - System storage: 60.0+ GB
-        - Basic:
+      - Advanced:
-          - System storage: 60.0+ GB
+        - Include in memory balancing: uncheck
-        - Advanced:
+        - Initial memory: 4096+ MB
-          - Include in memory balancing: uncheck
+        - Kernel: `(none)`
-          - Initial memory: 4096+ MB
+        - Mode: `HVM`
-          - Kernel: `(none)`
+      - Click "Apply".
-          - Mode: `HVM`
-        - Click "Apply".
 
    After creation, set `qvm-prefs WindowsNew qrexec_timeout 7200` via CLI in a dom0 terminal.
 
 - Using CLI in a dom0 terminal
  
    - This can also be done via the following CLI commands in dom0, for a standalone qube:
-      ~~~
+
-      qvm-create --class StandaloneVM --label orange --property virt_mode=hvm WindowsNew
+    ~~~
-      ~~~
+    qvm-create --class StandaloneVM --label orange --property virt_mode=hvm WindowsNew
-     and for a template:
+    ~~~
-      ~~~
+
-      qvm-create --class TemplateVM --label black --property virt_mode=hvm WindowsNew
+    and for a template:
-      ~~~
+
+    ~~~
+    qvm-create --class TemplateVM --label black --property virt_mode=hvm WindowsNew
+    ~~~
+   
    - After creation, set the following parameters via CLI in a dom0 terminal:
-      ~~~
+
-      qvm-volume extend WindowsNew:root 60g
+    ~~~
-      qvm-prefs WindowsNew memory 4096
+    qvm-volume extend WindowsNew:root 60g
-      qvm-prefs WindowsNew maxmem 4096
+    qvm-prefs WindowsNew memory 4096
-      qvm-prefs WindowsNew kernel ''
+    qvm-prefs WindowsNew maxmem 4096
-      qvm-prefs WindowsNew qrexec_timeout 7200
+    qvm-prefs WindowsNew kernel ''
-      ~~~
+    qvm-prefs WindowsNew qrexec_timeout 7200
+    ~~~
 
 These parameters are set for the following reasons:
   
@@ -109,19 +113,26 @@ These parameters are set for the following reasons:
 - Setting memory to 4096MB may work in most cases, but using 6144MB (or even 8192MB) may reduce the likelihood of crashes during installation, especially for Windows 10 or 11. This is important as Windows qubes have to be created without memory balancing, as requested by the parameter settings described above.
 
 - The Windows' installer requires a significant amount of memory or else the VM will crash with such errors:
-  ~~~
-  /var/log/xen/console/hypervisor.log:
 
-  p2m_pod_demand_populate: Dom120 out of PoD memory! (tot=102411 ents=921600 dom120)
+    ~~~
-  (XEN) domain_crash called from p2m-pod.c:1218
+    /var/log/xen/console/hypervisor.log:
-  (XEN) Domain 120 (vcpu#0) crashed on cpu#3:
+
-  ~~~
+    p2m_pod_demand_populate: Dom120 out of PoD memory! (tot=102411 ents=921600 dom120)
+    (XEN) domain_crash called from p2m-pod.c:1218
+    (XEN) Domain 120 (vcpu#0) crashed on cpu#3:
+    ~~~
+    
   So, increase the VM's memory to 4096MB (memory = maxmem because we don't use memory balancing), or 6144MB / 8192MB, as recommended above.
      
 - Disable direct boot so that the VM will go through the standard cdrom/HDD boot sequence. This is done by setting the qube's kernel to an empty value.
 
 - After creating the new qube, increase the VM's `qrexec_timeout`: in case you happen to get a BSOD or a similar crash in the VM, utilities like `chkdsk` won't complete on restart before `qrexec_timeout` automatically halts the VM. That can really put the VM in a totally unrecoverable state, whereas with higher `qrexec_timeout`, `chkdsk` or the appropriate utility has plenty of time to fix the VM. Note that Qubes Windows Tools also require a larger timeout to move the user profiles to the private volume the first time the VM reboots after the tools' installation. So set the parameter via the following CLI command from a dom0 terminal, because the Qube manager does not support this setting:
+
+    ~~~
+    qvm-prefs WindowsNew qrexec_timeout 7200
+    ~~~
   
+
 **Start Windows VM**
 
 - The VM is now ready to be started; the best practice is to use an installation ISO [located in a VM](/doc/standalones-and-hvms/#installing-an-os-in-an-hvm). Now boot the newly created qube from the Windows installation media. In the Qubes Manager:
@@ -135,6 +146,7 @@ These parameters are set for the following reasons:
      - Click "OK" to boot into the windows installer.
 
    This can also be done via the following CLI command in dom0 (assuming that the Windows installer ISO is stored in the directory `/home/user/` in the AppVM `untrusted`):
+
     ~~~
     qvm-start --cdrom=untrusted:/home/user/windows_install.iso WindowsNew
     ~~~
@@ -146,37 +158,49 @@ 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*.
+    -  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.
-    -  Typing Shift-F10 then opens 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.
-   
+<div class="alert alert-warning" role="alert">
-    :warning: **Caution:** This temporary patch may cease to work if it so pleases Microsoft some time.
+    <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.
-    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:
+</div>
-    
-    - 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.
-    - Expand the Task Manager by clicking the “More Details” button, and then find “Network Connection Flow.”
-    - Select this process and then hit the “End Task” button.
-    - Now you can close these newly opened windows and return to the Windows 11 setup, where you will enter local account information.
- 
-    For Windows 11 version 22H2, the following sequence of actions to use a local account instead of a Microsoft account has been published:
 
-    - Enter `no@thankyou.com` (or some other senseless address) as the email address and click `Next` when Windows 11 setup prompts you to log into your Microsoft account.
+    - 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:
-    - Enter any text you want in the password field and click `Sign in`. If this method works, you'll get a message saying "Oops, something went wrong."
+    
-    - Click `Next`. A screen appears saying "Who's going to use this device?" This is the local account creation screen.
+      - When you reach the “Let’s Connect You To A Network” page, type Shift-F10 to open a console window.
-    - Enter the username you want to use and click `Next`.
+      - Here you type `taskmgr` to start the Task Manager window so you can see all running processes.
-    - Enter a password and click `Next`. You can leave the field blank but it's not recommended.
+      - Expand the Task Manager by clicking the “More Details” button, and then find “Network Connection Flow.”
+      - Select this process and then hit the “End Task” button.
+      - Now you can close these newly opened windows and return to the Windows 11 setup, where you will enter local account information.
+ 
+    - For Windows 11 version 22H2, the following sequence of actions to use a local account instead of a Microsoft account has been published:
+
+      - Enter `no@thankyou.com` (or some other senseless address) as the email address and click `Next` when Windows 11 setup prompts you to log into your Microsoft account.
+      - Enter any text you want in the password field and click `Sign in`. If this method works, you'll get a message saying "Oops, something went wrong."
+      - 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 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`
 
+
     Alternatively, you can also try a Windows 7 license key (as of 2018/11 they are still accepted for a free upgrade to Windows 10).
     
  - The VM will shutdown after the installer completes the extraction of Windows installation files. It's a good idea to clone the VM now (eg. `qvm-clone WindowsNew WindowsNewbkp1`). Then, (re)start the VM via the Qubes Manager or with `qvm-start WindowsNew` from a dom0 terminal (without the `--cdrom` parameter!).
@@ -186,9 +210,11 @@ These parameters are set for the following reasons:
 **After Windows installation**
 
   - From the Windows command line, disable hibernation in order to avoid incomplete Windows shutdown, which could lead to corruption of the VM's disk. 
+
      ~~~
      powercfg -H off
      ~~~
+
     Also, recent versions of Windows won’t show the CD-ROM drive after starting the qube with `qvm-start vm --cdrom ...` (or using the GUI). The solution is to disable hibernation in Windows with this command. (That command is included in QWT’s setup but it’s necessary to run it manually in order to be able to open QWT’s setup ISO/CD-ROM in Windows).
 
   - In case you switch from `sys-firewall` to `sys-whonix`, you'll need a static IP network configuration, DHCP won't work for `sys-whonix`. Sometimes this may also happen if you keep using `sys-firewall`. In both cases, proceed as follows:
@@ -202,6 +228,7 @@ These parameters are set for the following reasons:
 
   - Given the higher than usual memory requirements of Windows, you may get a `Not enough memory to start domain 'WindowsNew'` error. In that case try to shutdown unneeded VMs to free memory before starting the Windows VM.
 
+
     At this point you may open a tab in dom0 for debugging, in case something goes amiss:
 
      ~~~
@@ -231,9 +258,19 @@ 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
+
 ~~~
 qvm-create --class=AppVM --template=<VMname> 
 ~~~
@@ -242,7 +279,8 @@ On starting the AppVM, sometimes a message is displayed that the Xen PV Network
 
 **Caution:** These AppVMs must not be started while the corresponding TemplateVM is running, because they share the TemplateVM's license data. Even if this could work sometimes, it would be a violation of the license terms.
 
-Furthermore, if manual IP setup was used for the template, the IP address selected for the template will also be used for the AppVM, as it inherits this address from the template. Qubes, however, will have assigned a different address to the AppVM, which will have to changed to that of the template (e.g. 10.137.0.x) so that the AppVM can access the network, vis the CLI command in a dom0 terminal:
+Furthermore, if manual IP setup was used for the template, the IP address selected for the template will also be used for the AppVM, as it inherits this address from the template. Qubes, however, will have assigned a different address to the AppVM, which will have to be changed to that of the template (e.g. 10.137.0.x) so that the AppVM can access the network, via the CLI command in a dom0 terminal:
+
 ~~~
 qvm-prefs WindowsNew ip 10.137.0.x
 ~~~