Commit changes from #1286 - Update Windows pages

developer/building/development-workflow.md

@@ -15,7 +15,7 @@ A workflow for developing Qubes OS+
 First things first, setup [QubesBuilder](/doc/qubes-builder/). This guide
 assumes you're using qubes-builder to build Qubes.
 
-# Repositories and committing Code
+## Repositories and committing Code
 
 Qubes is split into a bunch of git repos. These are all contained in the
 `qubes-src` directory under qubes-builder. Subdirectories there are separate

developer/building/qubes-builder.md

@@ -24,6 +24,7 @@ In order to use it, you should use an rpm-based distro, like Fedora :), and shou
 - git
 - createrepo
 - rpm-build
+- dnf-plugins-core
 - make
 - wget
 - rpmdevtools

developer/building/qubes-iso-building.md

@@ -15,7 +15,7 @@ title: Qubes ISO building
 Build Environment
 -----------------
 
-Fedora 32 has been successfully used to build Qubes R4.1 with the below steps.
+Fedora 36 (and 37) has been successfully used to build Qubes R4.1 with the below steps.
 Other rpm-based operating systems may also work.
 Travis-CI uses Ubuntu 18.04 to perform test builds, except it can not test the `./setup` script.
 
@@ -29,13 +29,13 @@ sudo setenforce 0
 ~~~
 
 
-In `dom0`, install the Fedora 32 template if you don't already have it.
+In `dom0`, install the Fedora 36 (or 37) template if you don't already have it.
 
 ~~~
-sudo qubes-dom0-update qubes-template-fedora-32
+sudo qubes-dom0-update qubes-template-fedora-36
 ~~~
 
-Create a standalone AppVM from the Fedora 32 template.
+Create a standalone AppVM from the Fedora template.
 Set private storage to at least 60 GB if you will be building only the default templates; 100 GB or more if you plan on additional.
 It's not required, but if you allocate additional CPU cores, the build process can utilize them at some steps such as the kernel build.
 Likewise, more memory (up to 16 GB) can help.

developer/code/coding-style.md

@@ -123,7 +123,7 @@ Source Code management (Git) guidelines
 
 - Use git to maintain all code for Qubes project.
 
-- Before you start using git, make sure you understand that git is a decentralized Source Code Management system, and that it doesn't behave like traditional, centralized source code management systems, such as SVN. Here's a good [introductory book on git](http://git-scm.com/book). Read it.
+- Before you start using git, make sure you understand that git is a decentralized Source Code Management system, and that it doesn't behave like traditional, centralized source code management systems, such as SVN. Here's a good [introductory book on git](https://git-scm.com/book). Read it.
 
 - Qubes code is divided into many git repositories. There are several reasons for that:
   - This creates natural boundaries between different code blocks, enforcing proper interfaces, and easing independent development to be conducted on various code parts at the same time, without the fear of running into conflicts.
@@ -169,7 +169,7 @@ Security coding guidelines
 Python-specific guidelines
 --------------------------
 
-- Please follow the guidelines [here](http://www.python.org/dev/peps/pep-0008/), unless they were in conflict with what is written on this page.
+- Please follow the guidelines [here](https://peps.python.org/pep-0008/), unless they were in conflict with what is written on this page.
 
 C and C++ specific guidelines
 -----------------------------

developer/debugging/automated-tests.md

@@ -121,7 +121,7 @@ Tests are also compatible with nose2 test runner, so you can use this instead:
 sudo systemctl stop qubesd; sudo -E nose2 -v --plugin nose2.plugins.loader.loadtests qubes.tests; sudo systemctl start qubesd
 ```
 
-This may be especially useful together with various nose2 plugins to store tests results (for example `nose2.plugins.junitxml`), to ease presenting results. This is what we use on [OpenQA](http://open.qa/).
+This may be especially useful together with various nose2 plugins to store tests results (for example `nose2.plugins.junitxml`), to ease presenting results. This is what we use on [OpenQA](https://open.qa/).
 
 ### Unit testing inside a VM
 
@@ -248,7 +248,7 @@ class SomeTestCase(unittest.TestCase):
 **Tests:** <https://github.com/marmarek/openqa-tests-qubesos>
 
 Manually testing Qubes OS and its installation is a time-consuming process.
-We use [OpenQA](http://open.qa/) to automate this process.
+We use [OpenQA](https://open.qa/) to automate this process.
 It works by installing Qubes in KVM and interacting with it as a user would, including simulating mouse clicks and keyboard presses.
 Then, it checks the output to see whether various tests were passed, e.g. by comparing the virtual screen output to screenshots of a successful installation.
 

developer/debugging/vm-interface.md

@@ -34,7 +34,7 @@ Qubes VM have some settings set by dom0 based on VM settings. There are multiple
 - `/qubes-debug-mode` - flag whether VM has debug mode enabled (qvm-prefs setting). One of `1`, `0`
 - `/qubes-service/SERVICE_NAME` - subtree for VM services controlled from dom0 (using the `qvm-service` command or Qubes Manager). One of `1`, `0`. Note that not every service will be listed here, if entry is missing, it means "use VM default". A list of currently supported services is in the `qvm-service` man page.
 - `/qubes-netmask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0"
-- `/qubes-ip - IP address for this VM (only when VM has netvm set)
+- `/qubes-ip` - IP address for this VM (only when VM has netvm set)
 - `/qubes-gateway` - default gateway IP (only when VM has netvm set); VM should add host route to this address directly via eth0 (or whatever default interface name is)
 - `/qubes-primary-dns` - primary DNS address (only when VM has netvm set)
 - `/qubes-secondary-dns` - secondary DNS address (only when VM has netvm set)

developer/general/documentation-style-guide.md

@@ -13,88 +13,52 @@ title: Documentation style guide
 
 _Also see [how to edit the documentation](/doc/how-to-edit-the-documentation/)._
 
-Qubes OS documentation pages are stored as plain text Markdown files in the
+Qubes OS documentation pages are stored as plain text Markdown files in the [qubes-doc](https://github.com/QubesOS/qubes-doc) repository. By cloning and regularly pulling from this repo, users can maintain their own up-to-date offline copy of all Qubes documentation rather than relying solely on the web.
-[qubes-doc](https://github.com/QubesOS/qubes-doc) repository. By cloning and
-regularly pulling from this repo, users can maintain their own up-to-date
-offline copy of all Qubes documentation rather than relying solely on the web.
 
-The documentation is a volunteer community effort. People like you are
+The documentation is a volunteer community effort. People like you are constantly working to make it better. If you notice something that can be fixed or improved, please [edit the documentation](/doc/how-to-edit-the-documentation/)!
-constantly working to make it better. If you notice something that can be fixed
-or improved, please [edit the
-documentation](/doc/how-to-edit-the-documentation/)!
 
-This page explains the standards we follow for writing, formatting, and
+This page explains the standards we follow for writing, formatting, and organizing the documentation. Please follow these guidelines and conventions when editing the documentation. For the standards governing the website as a whole, please see the [website style guide](/doc/website-style-guide).
-organizing the documentation. Please follow these guidelines and conventions
-when editing the documentation. For the standards governing the website as a
-whole, please see the [website style guide](/doc/website-style-guide).
 
 ## Markdown conventions
 
-All the documentation is written in Markdown for maximum accessibility. When
+All the documentation is written in Markdown for maximum accessibility. When making contributions, please observe the following style conventions. If you're not familiar with Markdown syntax, [this](https://daringfireball.net/projects/markdown/) is a great resource.
-making contributions, please observe the following style conventions. If you're
-not familiar with Markdown syntax,
-[this](https://daringfireball.net/projects/markdown/) is a great resource.
 
 ### Hyperlink syntax
 
-Use non-reference-style links like `[website](https://example.com/)`. Do *not*
+Use non-reference-style links like `[website](https://example.com/)`. Do *not* use reference-style links like `[website][example]`, `[website][]` or `[website]`. This facilitates the localization process.
-use reference-style links like `[website][example]`, `[website][]` or
-`[website]`. This facilitates the localization process.
 
 ### Relative vs. absolute links
 
-Always use relative rather than absolute paths for internal website links. For
+Always use relative rather than absolute paths for internal website links. For example, use `/doc/documentation-style-guide/` instead of `https://www.qubes-os.org/doc/documentation-style-guide/`.
-example, use `/doc/documentation-style-guide/` instead of
-`https://www.qubes-os.org/doc/documentation-style-guide/`.
 
 You may use absolute URLs in the following cases:
 
 - External links
-- URLs that appear inside code blocks (e.g., in comments and document
+- URLs that appear inside code blocks (e.g., in comments and document templates, and the plain text reproductions of [QSBs](/security/qsb/) and [Canaries](/security/canary/)), since they're not hyperlinks
-  templates, and the plain text reproductions of [QSBs](/security/qsb/) and
+- Git repo files like `README.md` and `CONTRIBUTING.md`, since they're not part of the website itself but rather of the auxiliary infrastructure supporting the website
-  [Canaries](/security/canary/)), since they're not hyperlinks
-- Git repo files like `README.md` and `CONTRIBUTING.md`, since they're not part
-  of the website itself but rather of the auxiliary infrastructure supporting
-  the website
 
-This rule is important because using absolute URLs for internal website links
+This rule is important because using absolute URLs for internal website links breaks:
-breaks:
 
 - Serving the website offline
 - Website localization
 - Generating offline documentation
-- Automatically redirecting Tor Browser visitors to the correct page on the
+- Automatically redirecting Tor Browser visitors to the correct page on the onion service mirror
-  onion service mirror
 
 ### Image linking
 
-See [how to add images](/doc/how-to-edit-the-documentation/#how-to-add-images)
+See [how to add images](/doc/how-to-edit-the-documentation/#how-to-add-images) for the required syntax. This will make the image a hyperlink to the image file, allowing the reader to click on the image in order to view the full image by itself. This is important. Following best practices, our website has a responsive design, which allows the website to render appropriately across all screen sizes. When viewing this page on a smaller screen, such as on a mobile device, the image will automatically shrink down to fit the screen. If visitors cannot click on the image to view it in full size, then, depending on their device, they may have no way see the details in the image clearly.
-for the required syntax. This will make the image a hyperlink to the image
-file, allowing the reader to click on the image in order to view the full image
-by itself. This is important. Following best practices, our website has a
-responsive design, which allows the website to render appropriately across all
-screen sizes. When viewing this page on a smaller screen, such as on a mobile
-device, the image will automatically shrink down to fit the screen. If visitors
-cannot click on the image to view it in full size, then, depending on their
-device, they may have no way see the details in the image clearly.
 
-In addition, make sure to link only to images in the
+In addition, make sure to link only to images in the [qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository. Do not attempt to link to images hosted on other websites.
-[qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository. Do
-not attempt to link to images hosted on other websites.
 
 ### HTML and CSS
 
-Do not write HTML inside Markdown documents (except in rare, unavoidable cases,
+Do not write HTML inside Markdown documents (except in rare, unavoidable cases, such as [alerts](#alerts)). In particular, never include HTML or CSS for styling, formatting, or white space control. That belongs in the (S)CSS files instead.
-such as alerts). In particular, never include HTML or CSS for styling,
-formatting, or white space control. That belongs in the (S)CSS files instead.
 
 ### Headings
 
-Do not use `h1` headings (single `#` or `======` underline). These are
+Do not use `h1` headings (single `#` or `======` underline). These are automatically generated from the `title:` line in the YAML front matter.
-automatically generated from the `title:` line in the YAML front matter.
 
-Use Atx-style syntax for headings: `##h2`, `### h3`, etc. Do not use
+Use Atx-style syntax for headings: `##h2`, `### h3`, etc. Do not use underlining syntax (`-----`).
-underlining syntax (`-----`).
 
 ### Indentation
 
@@ -102,49 +66,131 @@ Use spaces instead of tabs. Use hanging indentations where appropriate.
 
 ### Lists
 
-If appropriate, make numerals in numbered lists match between Markdown source
+If appropriate, make numerals in numbered lists match between Markdown source and HTML output. Some users read the Markdown source directly, and this makes numbered lists easier to follow.
-and HTML output. Some users read the Markdown source directly, and this makes
-numbered lists easier to follow.
 
 ### Code blocks
 
-When writing code blocks, use [syntax
+When writing code blocks, use [syntax highlighting](https://github.github.com/gfm/#info-string) where possible (see [here](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers) for a list of supported languages). Use `[...]` for anything omitted.
-highlighting](https://github.github.com/gfm/#info-string) where possible (see
-[here](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers)
-for a list of supported languages). Use `[...]` for anything omitted.
 
 ### Line wrapping
 
-Hard wrap Markdown lines at 80 characters, unless the line can't be broken
+Do not hard wrap text, except where necessary (e.g., inside code blocks).
-(e.g., code or a URL).
+
+### Do not use Markdown syntax for styling
+
+For example, there is a common temptation to use block quotations (created by beginning lines with the `>` character) in order to stylistically distinguish some portion of text from the rest of the document, e.g.:
+
+```
+> Note: This is an important note!
+```
+
+This renders as:
+
+> Note: This is an important note!
+
+There are two problems with this:
+
+1. It is a violation of the [separation of content and presentation](https://en.wikipedia.org/wiki/Separation_of_content_and_presentation), since it abuses markup syntax in order to achieve unintended stylistic results. The Markdown (and HTML, if any) should embody the *content* of the documentation, while the *presentation* is handled by (S)CSS.
+
+2. It is an abuse of quotation syntax for text that is not actually a quotation. (You are not quoting anyone here. You're just telling the reader to note something and trying to draw their attention to your note visually.)
+
+Instead, an example of an appropriate way to stylistically distinguish a portion of text is by using [alerts](#alerts). Consider also that extra styling and visual distinction may not even be necessary. In most cases, traditional writing methods are perfectly sufficient, e.g.,:
+
+```
+**Note:** This is an important note.
+```
+
+This renders as:
+
+**Note:** This is an important note.
+
+### Alerts
+
+Alerts are sections of HTML used to draw the reader's attention to important information, such as warnings, and for stylistic purposes. They are typically styled as colored text boxes, usually accompanied by icons. Alerts should generally be used somewhat sparingly, so as not to cause [alert fatigue](https://en.wikipedia.org/wiki/Alarm_fatigue) and since they must be written in HTML instead of Markdown, which makes the source less readable and more difficult to work with for localization and automation purposes. Here are examples of several types of alerts and their recommended icons:
+
+```
+<div class="alert alert-success" role="alert">
+  <i class="fa fa-check-circle"></i>
+  <b>Did you know?</b> The Qubes OS installer is completely offline. It doesn't
+  even load any networking drivers, so there is no possibility of
+  internet-based data leaks or attacks during the installation process.
+</div>
+
+<div class="alert alert-info" role="alert">
+  <i class="fa fa-info-circle"></i>
+  <b>Note:</b> Using Rufus to create the installation medium means that you <a
+  href="https://github.com/QubesOS/qubes-issues/issues/2051">won't be able</a>
+  to choose the "Test this media and install Qubes OS" option mentioned in the
+  example below. Instead, choose the "Install Qubes OS" option.
+</div>
+
+<div class="alert alert-warning" role="alert">
+  <i class="fa fa-exclamation-circle"></i>
+  <b>Note:</b> Qubes OS is not meant to be installed inside a virtual machine
+  as a guest hypervisor. In other words, <b>nested virtualization</b> is not
+  supported. In order for a strict compartmentalization to be enforced, Qubes
+  OS needs to be able to manage the hardware directly.
+</div>
+
+<div class="alert alert-danger" role="alert">
+  <i class="fa fa-exclamation-triangle"></i>
+  <b>Warning:</b> Qubes has no control over what happens on your computer
+  before you install it. No software can provide security if it is installed on
+  compromised hardware. Do not install Qubes on a computer you don't trust. See
+  <a href="/doc/install-security/">installation security</a> for more
+  information.
+</div>
+```
+
+These render as:
+
+<div class="alert alert-success" role="alert">
+  <i class="fa fa-check-circle"></i>
+  <b>Did you know?</b> The Qubes OS installer is completely offline. It doesn't
+  even load any networking drivers, so there is no possibility of
+  internet-based data leaks or attacks during the installation process.
+</div>
+
+<div class="alert alert-info" role="alert">
+  <i class="fa fa-info-circle"></i>
+  <b>Note:</b> Using Rufus to create the installation medium means that you <a
+  href="https://github.com/QubesOS/qubes-issues/issues/2051">won't be able</a>
+  to choose the "Test this media and install Qubes OS" option mentioned in the
+  example below. Instead, choose the "Install Qubes OS" option.
+</div>
+
+<div class="alert alert-warning" role="alert">
+  <i class="fa fa-exclamation-circle"></i>
+  <b>Note:</b> Qubes OS is not meant to be installed inside a virtual machine
+  as a guest hypervisor. In other words, <b>nested virtualization</b> is not
+  supported. In order for a strict compartmentalization to be enforced, Qubes
+  OS needs to be able to manage the hardware directly.
+</div>
+
+<div class="alert alert-danger" role="alert">
+  <i class="fa fa-exclamation-triangle"></i>
+  <b>Warning:</b> Qubes has no control over what happens on your computer
+  before you install it. No software can provide security if it is installed on
+  compromised hardware. Do not install Qubes on a computer you don't trust. See
+  <a href="/doc/install-security/">installation security</a> for more
+  information.
+</div>
 
 ## Writing guidelines
 
 ### Correct use of terminology
 
-Familiarize yourself with the terms defined in the [glossary](/doc/glossary/).
+Familiarize yourself with the terms defined in the [glossary](/doc/glossary/). Use these terms consistently and accurately throughout your writing.
-Use these terms consistently and accurately throughout your writing.
 
 ### Sentence case in headings
 
-Use sentence case (rather than title case) in headings for the reasons
+Use sentence case (rather than title case) in headings for the reasons explained [here](https://www.sallybagshaw.com.au/articles/sentence-case-v-title-case/). In particular, since the authorship of the Qubes documentation is decentralized and widely distributed among users from around the world, many contributors come from regions with different conventions for implementing title case, not to mention that there are often differing style guide recommendations even within a single region. It is much easier for all of us to implement sentence case consistently across our growing body of pages, which is very important for managing the ongoing maintenance burden and sustainability of the documentation.
-explained
-[here](https://www.sallybagshaw.com.au/articles/sentence-case-v-title-case/).
-In particular, since the authorship of the Qubes documentation is decentralized
-and widely distributed among users from around the world, many contributors
-come from regions with different conventions for implementing title case, not
-to mention that there are often differing style guide recommendations even
-within a single region. It is much easier for all of us to implement sentence
-case consistently across our growing body of pages, which is very important for
-managing the ongoing maintenance burden and sustainability of the
-documentation.
 
 ### Writing command-line examples
 
 When providing command-line examples:
 
-- Tell the reader where to open a terminal (dom0 or a specific domU), and show
+- Tell the reader where to open a terminal (dom0 or a specific domU), and show the command along with its output (if any) in a code block, e.g.:
-  the command along with its output (if any) in a code block, e.g.:
 
   ~~~markdown
   Open a terminal in dom0 and run:
@@ -155,12 +201,9 @@ When providing command-line examples:
   ```
   ~~~
 
-- Precede each command with the appropriate command prompt: At a minimum, the
+- Precede each command with the appropriate command prompt: At a minimum, the prompt should contain a trailing `#` (for the user `root`) or `$` (for other users) on Linux systems and `>` on Windows systems, respectively.
-  prompt should contain a trailing `#` (for the user `root`) or `$` (for other
-  users) on Linux systems and `>` on Windows systems, respectively.
 
-- Don't try to add comments inside the code block. For example, *don't* do
+- Don't try to add comments inside the code block. For example, *don't* do this:
-  this:
 
    ~~~markdown
    Open a terminal in dom0 and run:
@@ -173,14 +216,11 @@ When providing command-line examples:
    ```
    ~~~
 
-   The `#` symbol preceding each comment is ambiguous with a root command
+   The `#` symbol preceding each comment is ambiguous with a root command prompt. Instead, put your comments *outside* of the code block in normal prose.
-   prompt. Instead, put your comments *outside* of the code block in normal
-   prose.
 
 ### Variable names in commands
 
-Syntactically distinguish variables in commands. For example, this is
+Syntactically distinguish variables in commands. For example, this is ambiguous:
-ambiguous:
 
     $ qvm-run --dispvm=disposable-template --service qubes.StartApp+xterm
 
@@ -194,135 +234,53 @@ Note that we syntactically distinguish variables in three ways:
 2. Using underscores (`_`) instead of spaces between words
 3. Using all capital letters
 
-We have observed that many novices make the mistake of typing the surrounding
+We have observed that many novices make the mistake of typing the surrounding angled brackets (`< >`) on the command line, even after substituting the desired real value between them. Therefore, in documentation aimed at novices, we also recommend clarifying that the angled brackets should not be typed. This can be accomplished in one of several ways:
-angled brackets (`< >`) on the command line, even after substituting the
-desired real value between them. Therefore, in documentation aimed at novices,
-we also recommend clarifying that the angled brackets should not be typed. This
-can be accomplished in one of several ways:
 
 - Explicitly say something like "without the angled brackets."
-- Provide an example command using real values that excludes the angled
+- Provide an example command using real values that excludes the angled brackets.
-  brackets.
+- If you know that almost all users will want to use (or should use) a specific command containing all real values and no variables, you might consider providing exactly that command and forgoing the version with variables. Novices may not realize which parts of the command they can substitute with different values, but if you've correctly judged that they should use the command you've provided as is, then this shouldn't matter.
-- If you know that almost all users will want to use (or should use) a specific
+
-  command containing all real values and no variables, you might consider
+### Capitalization of "qube"
-  providing exactly that command and forgoing the version with variables.
+
-  Novices may not realize which parts of the command they can substitute with
+We introduced the term ["qube"](/doc/glossary/#qube) as a user-friendly alternative to the term ["virtual machine" ("VM")](/doc/glossary/#vm) in the context of Qubes OS. Nonetheless, "qube" is a common noun like the words "compartment" and "container." Therefore, in English, "qube" follows the standard capitalization rules for common nouns. For example, "I have three qubes" is correct, while "I have three Qubes" is incorrect. Like other common nouns, "qube" should still be capitalized at the beginnings of sentences, the beginnings of sentence-case headings, and in title-case headings. Note, however, that starting a sentence with the plural of "qube" (e.g., "Qubes can be shut down...") can be ambiguous, since it may not be clear whether the referent is a plurality of qubes, [Qubes OS](/doc/glossary/#qubes-os), or even the Qubes OS Project itself. Hence, it is generally a good idea to rephrase such sentences in order to avoid this ambiguity.
-  different values, but if you've correctly judged that they should use the
+
-  command you've provided as is, then this shouldn't matter.
+Many people feel a strong temptation to capitalize the word "qube" all the time, like a proper noun, perhaps because it's a new and unfamiliar term that's closely associated with a particular piece of software (namely, Qubes OS). However, these factors are not relevant to the capitalization rules of English. In fact, it's not unusual for new common nouns to be introduced into English, especially in the context of technology. For example, "blockchain" is a relatively recent technical term that's a common noun. Why is it a common noun rather than a proper noun? Because proper nouns refer to *particular* people, places, things, and ideas. There are many different blockchains. However, even when there was just one, the word still denoted a collection of things rather than a particular thing. It happened to be the case that there was only one member in that collection at the time. For example, if there happened to be only one tree in the world, that wouldn't change the way we capitalize sentences like, "John sat under a tree." Intuitively, it makes sense that the addition and removal of objects from the world shouldn't cause published books to become orthographicallly incorrect while sitting on their shelves.
+
+Accordingly, the reason "qube" is a common noun rather than a proper noun is because it doesn't refer to any one specific thing (in this case, any one specific virtual machine). Rather, it's the term for any virtual machine in a Qubes OS installation. (Technically, while qubes are currently implemented as virtual machines, Qubes OS is independent of its underlying compartmentalization technology. Virtual machines could be replaced with a different technology, and qubes would still be called "qubes.")
+
+I have several qubes in my Qubes OS installation, and you have several in yours. Every Qubes OS user has their own set of qubes, just as each of us lives in some neighborhood on some street. Yet we aren't tempted to treat words like "neighborhood" or "street" as proper nouns (unless, of course, they're part of a name, like "Acorn Street"). Again, while this might seem odd because "qube" is a new word that we invented, that doesn't change how English works. After all, *every* word was a new word that someone invented at some point (otherwise we wouldn't have any words at all). We treat "telephone," "computer," "network," "program," and so on as common nouns, even though those were all new technological inventions in the not-too-distant past (on a historical scale, at least). So, we shouldn't allow ourselves to be confused by irrelevant factors, like the fact that the inventors happened to be *us* or that the invention was *recent* or is not in widespread use among humanity.
+
+### English language conventions
+
+For the sake of consistency and uniformity, the Qubes documentation aims to follow the conventions of American English, where applicable. (Please note that this is an arbitrary convention for the sake consistency and not a value judgment about the relative merits of British versus American English.)
 
 ## Organizational guidelines
 
 ### Do not duplicate documentation
 
-Duplicating documentation is almost always a bad idea. There are many reasons
+Duplicating documentation is almost always a bad idea. There are many reasons for this. The main one is that almost all documentation has to be updated as some point. When similar documentation appears in more than one place, it is very easy for it to get updated in one place but not the others (perhaps because the person updating it doesn't realize it's in more than once place). When this happens, the documentation as a whole is now inconsistent, and the outdated documentation becomes a trap, especially for novice users. Such traps are often more harmful than if the documentation never existed in the first place. The solution is to **link** to existing documentation rather than duplicating it. There are some exceptions to this policy (e.g., information that is certain not to change for a very long time), but they are rare.
-for this. The main one is that almost all documentation has to be updated as
-some point. When similar documentation appears in more than one place, it is
-very easy for it to get updated in one place but not the others (perhaps
-because the person updating it doesn't realize it's in more than once place).
-When this happens, the documentation as a whole is now inconsistent, and the
-outdated documentation becomes a trap, especially for novice users. Such traps
-are often more harmful than if the documentation never existed in the first
-place. The solution is to **link** to existing documentation rather than
-duplicating it. There are some exceptions to this policy (e.g., information
-that is certain not to change for a very long time), but they are rare.
 
 ### Core vs. external documentation
 
-Core documentation resides in the [Qubes OS Project's official
+Core documentation resides in the [Qubes OS Project's official repositories](https://github.com/QubesOS/), mainly in [qubes-doc](https://github.com/QubesOS/qubes-doc). External documentation can be anywhere else (such as forums, community websites, and blogs), but there is an especially large collection in the [Qubes Community](https://github.com/Qubes-Community) project. External documentation should not be submitted to [qubes-doc](https://github.com/QubesOS/qubes-doc). If you've written a piece of documentation that is not appropriate for [qubes-doc](https://github.com/QubesOS/qubes-doc), we encourage you to submit it to the [Qubes Community](https://github.com/Qubes-Community) project instead. However, *linking* to external documentation from [qubes-doc](https://github.com/QubesOS/qubes-doc) is perfectly fine. Indeed, the maintainers of the [Qubes Community](https://github.com/Qubes-Community) project should regularly submit PRs against the documentation index (see [How to edit the documentation index](/doc/how-to-edit-the-documentation/#how-to-edit-the-documentation-index)) to add and update Qubes Community links in the ["External documentation"](/doc/#external-documentation) section of the documentation table of contents.
-repositories](https://github.com/QubesOS/), mainly in
-[qubes-doc](https://github.com/QubesOS/qubes-doc). External documentation can
-be anywhere else (such as forums, community websites, and blogs), but there is
-an especially large collection in the [Qubes
-Community](https://github.com/Qubes-Community) project. External documentation
-should not be submitted to [qubes-doc](https://github.com/QubesOS/qubes-doc).
-If you've written a piece of documentation that is not appropriate for
-[qubes-doc](https://github.com/QubesOS/qubes-doc), we encourage you to submit
-it to the [Qubes Community](https://github.com/Qubes-Community) project
-instead. However, *linking* to external documentation from
-[qubes-doc](https://github.com/QubesOS/qubes-doc) is perfectly fine. Indeed,
-the maintainers of the [Qubes Community](https://github.com/Qubes-Community)
-project should regularly submit PRs against the documentation index (see [How
-to edit the documentation
-index](/doc/how-to-edit-the-documentation/#how-to-edit-the-documentation-index))
-to add and update Qubes Community links in the ["External
-documentation"](/doc/#external-documentation) section of the documentation
-table of contents.
 
-The main difference between **core** (or **official**) and **external** (or
+The main difference between **core** (or **official**) and **external** (or **community** or **unofficial**) documentation is whether it documents software that is officially written and maintained by the Qubes OS Project. The purpose of this distinction is to keep the core docs maintainable and high-quality by limiting them to the software output by the Qubes OS Project. In other words, we take responsibility for documenting all of the software we put out into the world, but it doesn't make sense for us to take on the responsibility of documenting or maintaining documentation for anything else. For example, Qubes OS may use a popular Linux distribution for an official [TemplateVM](/doc/templates/). However, it would not make sense for a comparatively small project like ours, with modest funding and a lean workforce, to attempt to document software belonging to a large, richly-funded project with an army of paid and volunteer contributors, especially when they probably already have documentation of their own. This is particularly true when it comes to Linux in general. Although many users who are new to Qubes are also new to Linux, it makes absolutely no sense for our comparatively tiny project to try to document Linux in general when there is already a plethora of documentation out there.
-**community** or **unofficial**) documentation is whether it documents software
-that is officially written and maintained by the Qubes OS Project. The purpose
-of this distinction is to keep the core docs maintainable and high-quality by
-limiting them to the software output by the Qubes OS Project. In other words,
-we take responsibility for documenting all of the software we put out into the
-world, but it doesn't make sense for us to take on the responsibility of
-documenting or maintaining documentation for anything else. For example, Qubes
-OS may use a popular Linux distribution for an official
-[TemplateVM](/doc/templates/). However, it would not make sense for a
-comparatively small project like ours, with modest funding and a lean
-workforce, to attempt to document software belonging to a large, richly-funded
-project with an army of paid and volunteer contributors, especially when they
-probably already have documentation of their own. This is particularly true
-when it comes to Linux in general. Although many users who are new to Qubes are
-also new to Linux, it makes absolutely no sense for our comparatively tiny
-project to try to document Linux in general when there is already a plethora of
-documentation out there.
 
-Many contributors do not realize that there is a significant amount of work
+Many contributors do not realize that there is a significant amount of work involved in *maintaining* documentation after it has been written. They may wish to write documentation and submit it to the core docs, but they see only their own writing process and fail to consider that it will have to be kept up-to-date and consistent with the rest of the docs for years afterward. Submissions to the core docs also have to [undergo a review process](/doc/how-to-edit-the-documentation/#security) to ensure accuracy before being merged, which takes up valuable time from the team. We aim to maintain high quality standards for the core docs (style and mechanics, formatting), which also takes up a lot of time. If the documentation involves anything external to the Qubes OS Project (such as a website, platform, program, protocol, framework, practice, or even a reference to a version number), the documentation is likely to become outdated when that external thing changes. It's also important to periodically review and update this documentation, especially when a new Qubes release comes out. Periodically, there may be technical or policy changes that affect all the core documentation. The more documentation there is relative to maintainers, the harder all of this will be. Since there are many more people who are willing to write documentation than to maintain it, these individually small incremental additions amount to a significant maintenance burden for the project.
-involved in *maintaining* documentation after it has been written. They may
-wish to write documentation and submit it to the core docs, but they see only
-their own writing process and fail to consider that it will have to be kept
-up-to-date and consistent with the rest of the docs for years afterward.
-Submissions to the core docs also have to [undergo a review
-process](/doc/how-to-edit-the-documentation/#security) to ensure accuracy before
-being merged, which takes up valuable time from the team. We aim to maintain
-high quality standards for the core docs (style and mechanics, formatting),
-which also takes up a lot of time. If the documentation involves anything
-external to the Qubes OS Project (such as a website, platform, program,
-protocol, framework, practice, or even a reference to a version number), the
-documentation is likely to become outdated when that external thing changes.
-It's also important to periodically review and update this documentation,
-especially when a new Qubes release comes out. Periodically, there may be
-technical or policy changes that affect all the core documentation. The more
-documentation there is relative to maintainers, the harder all of this will be.
-Since there are many more people who are willing to write documentation than to
-maintain it, these individually small incremental additions amount to a
-significant maintenance burden for the project.
 
-On the positive side, we consider the existence of community documentation to
+On the positive side, we consider the existence of community documentation to be a sign of a healthy ecosystem, and this is quite common in the software world. The community is better positioned to write and maintain documentation that applies, combines, and simplifies the official documentation, e.g., tutorials that explain how to install and use various programs in Qubes, how to create custom VM setups, and introductory tutorials that teach basic Linux concepts and commands in the context of Qubes. In addition, just because the Qubes OS Project has officially written and maintains some flexible framework, such as `qrexec`, it does not make sense to include every tutorial that says "here's how to do something cool with `qrexec`" in the core docs. Such tutorials generally also belong in the community documentation.
-be a sign of a healthy ecosystem, and this is quite common in the software
-world. The community is better positioned to write and maintain documentation
-that applies, combines, and simplifies the official documentation, e.g.,
-tutorials that explain how to install and use various programs in Qubes, how to
-create custom VM setups, and introductory tutorials that teach basic Linux
-concepts and commands in the context of Qubes. In addition, just because the
-Qubes OS Project has officially written and maintains some flexible framework,
-such as `qrexec`, it does not make sense to include every tutorial that says
-"here's how to do something cool with `qrexec`" in the core docs. Such
-tutorials generally also belong in the community documentation.
 
-See [#4693](https://github.com/QubesOS/qubes-issues/issues/4693) for more
+See [#4693](https://github.com/QubesOS/qubes-issues/issues/4693) for more background information.
-background information.
 
 ### Release-specific documentation
 
-*See [#5308](https://github.com/QubesOS/qubes-issues/issues/5308) for pending
+*See [#5308](https://github.com/QubesOS/qubes-issues/issues/5308) for pending changes to this policy.*
-changes to this policy.*
 
-We maintain only one set of documentation for Qubes OS. We do not maintain a
+We maintain only one set of documentation for Qubes OS. We do not maintain a different set of documentation for each release of Qubes. Our single set of Qubes OS documentation is updated on a continual, rolling basis. Our first priority is to document all **current, stable releases** of Qubes. Our second priority is to document the next, upcoming release (if any) that is currently in the beta or release candidate stage.
-different set of documentation for each release of Qubes. Our single set of
-Qubes OS documentation is updated on a continual, rolling basis. Our first
-priority is to document all **current, stable releases** of Qubes. Our second
-priority is to document the next, upcoming release (if any) that is currently
-in the beta or release candidate stage.
 
-In cases where a documentation page covers functionality that differs
+In cases where a documentation page covers functionality that differs considerably between Qubes OS releases, the page should be subdivided into clearly-labeled sections that cover the different functionality in different releases (examples below).
-considerably between Qubes OS releases, the page should be subdivided into
-clearly-labeled sections that cover the different functionality in different
-releases (examples below).
 
-In general, avoid mentioning specific Qubes versions in the body text of
+In general, avoid mentioning specific Qubes versions in the body text of documentation, as these references rapidly go out of date and become misleading to readers.
-documentation, as these references rapidly go out of date and become misleading
-to readers.
 
 #### Incorrect Example
 
@@ -381,65 +339,17 @@ general `qubes-baz` command:
 Once you foo, make sure to close the baz before fooing the next bar.
 ```
 
-Subdividing the page into clearly-labeled sections for each release has several
+Subdividing the page into clearly-labeled sections for each release has several benefits:
-benefits:
 
-- It preserves good content for older (but still supported) releases. Many
+- It preserves good content for older (but still supported) releases. Many documentation contributors are also people who prefer to use the latest release. Many of them are tempted to *replace* existing content that applies to an older, supported release with content that applies only to the latest release. This is somewhat understandable. Since they only use the latest release, they may be focused on their own experience, and they may even regard the older release as deprecated, even when it's actually still supported. However, allowing this replacement of content would do a great disservice to those who still rely on the older, supported release. In many cases, these users value the stability and reliability of the older, supported release. With the older, supported release, there has been more time to fix bugs and make improvements in both the software and the documentation. Consequently, much of the documentation content for this release may have gone through several rounds of editing, review, and revision. It would be a tragedy for this content to vanish while the very set of users who most prize stability and reliability are depending on it.
-  documentation contributors are also people who prefer to use the latest
+- It's easy for readers to quickly find the information they're looking for, since they can go directly to the section that applies to their release.
-  release. Many of them are tempted to *replace* existing content that applies
+- It's hard for readers to miss information they need, since it's all in one place. In the incorrect example, information that the reader needs could be in any paragraph in the entire document, and there's no way to tell without reading the entire page. In the correct example, the reader can simply skim the headings in order to know which parts of the page need to be read and which can be safely ignored. The fact that some content is repeated in the two release-specific sections is not a problem, since no reader has to read the same thing twice. Moreover, as one release gets updated, it's likely that the documentation for that release will also be updated. Therefore, content that is initially duplicated between release-specific sections will not necessarily stay that way, and this is a good thing: We want the documentation for a release that *doesn't* change to stay the same, and we want the documentation for a release that *does* change to change along with the software.
-  to an older, supported release with content that applies only to the latest
+- It's easy for documentation contributors and maintainers to know which file to edit and update, since there's only one page for all Qubes OS releases. Initially creating the new headings and duplicating content that applies to both is only a one-time cost for each page, and many pages don't even require this treatment, since they apply to all currently-supported Qubes OS releases.
-  release. This is somewhat understandable. Since they only use the latest
-  release, they may be focused on their own experience, and they may even
-  regard the older release as deprecated, even when it's actually still
-  supported. However, allowing this replacement of content would do a great
-  disservice to those who still rely on the older, supported release. In many
-  cases, these users value the stability and reliability of the older,
-  supported release. With the older, supported release, there has been more
-  time to fix bugs and make improvements in both the software and the
-  documentation. Consequently, much of the documentation content for this
-  release may have gone through several rounds of editing, review, and
-  revision. It would be a tragedy for this content to vanish while the very set
-  of users who most prize stability and reliability are depending on it.
-- It's easy for readers to quickly find the information they're looking for,
-  since they can go directly to the section that applies to their release.
-- It's hard for readers to miss information they need, since it's all in one
-  place. In the incorrect example, information that the reader needs could be
-  in any paragraph in the entire document, and there's no way to tell without
-  reading the entire page. In the correct example, the reader can simply skim
-  the headings in order to know which parts of the page need to be read and
-  which can be safely ignored. The fact that some content is repeated in the
-  two release-specific sections is not a problem, since no reader has to read
-  the same thing twice. Moreover, as one release gets updated, it's likely that
-  the documentation for that release will also be updated. Therefore, content
-  that is initially duplicated between release-specific sections will not
-  necessarily stay that way, and this is a good thing: We want the
-  documentation for a release that *doesn't* change to stay the same, and we
-  want the documentation for a release that *does* change to change along with
-  the software.
-- It's easy for documentation contributors and maintainers to know which file
-  to edit and update, since there's only one page for all Qubes OS releases.
-  Initially creating the new headings and duplicating content that applies to
-  both is only a one-time cost for each page, and many pages don't even require
-  this treatment, since they apply to all currently-supported Qubes OS
-  releases.
 
-By contrast, an alternative approach, such as segregating the documentation
+By contrast, an alternative approach, such as segregating the documentation into two different branches, would mean that contributions that apply to both Qubes releases would only end up in one branch, unless someone remembered to manually submit the same thing to the other branch and actually made the effort to do so. Most of the time, this wouldn't happen. When it did, it would mean a second pull request that would have to be reviewed. Over time, the different branches would diverge in non-release-specific content. Good general content that was submitted only to one branch would effectively disappear once that release was deprecated. (Even if it were still on the website, no one would look at it, since it would explicitly be in the subdirectory of a deprecated release, and there would be a motivation to remove it from the website so that search results wouldn't be populated with out-of-date information.)
-into two different branches, would mean that contributions that apply to both
-Qubes releases would only end up in one branch, unless someone remembered to
-manually submit the same thing to the other branch and actually made the effort
-to do so. Most of the time, this wouldn't happen. When it did, it would mean a
-second pull request that would have to be reviewed. Over time, the different
-branches would diverge in non-release-specific content. Good general content
-that was submitted only to one branch would effectively disappear once that
-release was deprecated. (Even if it were still on the website, no one would
-look at it, since it would explicitly be in the subdirectory of a deprecated
-release, and there would be a motivation to remove it from the website so that
-search results wouldn't be populated with out-of-date information.)
 
-For further discussion about release-specific documentation in Qubes, see
+For further discussion about release-specific documentation in Qubes, see [here](https://groups.google.com/d/topic/qubes-users/H9BZX4K9Ptk/discussion).
-[here](https://groups.google.com/d/topic/qubes-users/H9BZX4K9Ptk/discussion).
 
 ## Git conventions
 
-Please follow our [Git commit message
+Please follow our [Git commit message guidelines](/doc/coding-style/#commit-message-guidelines).
-guidelines](/doc/coding-style/#commit-message-guidelines).

developer/general/gsod.md

@@ -6,78 +6,95 @@ ref: 242
 title: Google Season of Docs (GSoD)
 ---
 
-Thank you for your interest in participating in the [2021 Google Season of Docs](https://developers.google.com/season-of-docs/) program with the [Qubes OS team](/team/). You can read more about the Google Season of Docs in the official [guides](https://developers.google.com/season-of-docs/docs/) and [FAQ](https://developers.google.com/season-of-docs/docs/faq).
+Thank you for your interest in participating in the [2023 Google Season of Docs](https://developers.google.com/season-of-docs/) program with the [Qubes OS team](/team/). This page details our 2023 project idea as well as completed past projects. You can read more about the Google Season of Docs in the official [guides](https://developers.google.com/season-of-docs/docs/) and [FAQ](https://developers.google.com/season-of-docs/docs/faq).
 
-## 2021 Project Idea 
+## Instructional video series -- Qubes OS
 
-### Qubes OS on Virtual Machines and Disposable VMs documentation - Qubes OS
+### About the Qubes OS Project
 
-#### About your organization
+Qubes OS is a security-focused operating system that allows you to organize your digital life into compartments called "qubes." If one qube is compromised, the others remain safe, so a single cyberattack can no longer take down your entire digital life in one fell swoop. You can think of using Qubes OS as having many different computers on your desk for different activities but with the convenience of a single physical machine, a single unified desktop environment, and a set of tools for using qubes together securely as parts of a unified system.
 
-Qubes OS is a free and open source operating system uniquely designed to protect the security and privacy of the user. Its architecture is built to enable a user to define different security environments ("qubes") on their computer and visually manage their interaction with each other and the world.
+Qubes OS was launched in 2011 and has [received praise from security experts and organizations](/endorsements/) like Edward Snowden, the Freedom of the Press Foundation, Micah Lee, and Let's Encrypt. Qubes has [over 40,000 active users](/statistics/). From network-level to software-level protections, as well as protections against firmware and hardware attacks, Qubes OS is trying to protect the user from the most significant attacks they encounter so that they can get their work done safely.
 
-Qubes OS was launched in 2011 and has [received praise from security experts](https://www.qubes-os.org/endorsements/) like Edward Snowden, Bill Buddington (EFF), Isis Lovecruft (Tor Project), and Kenn White (Open Crypto Audit), and has over [30,000 active users](https://www.qubes-os.org/statistics/).
+### The project's problem
 
-From network-level to software-level protections, as well as protections against firmware and hardware attacks, Qubes OS is trying to protect the user from the most significant attacks they encounter so that they can get their work done, safely.
+There is user demand for high-quality, up-to-date video guides that take users from zero Linux knowledge to using Qubes as a daily driver and performing specific tasks inside of Qubes, but almost no such videos exist. Although most of the required knowledge is documented, many users report that they would prefer to watch videos rather than read text or that they would find videos easier to understand and follow along with.
 
-#### The Project
+### The project's scope
 
-The goal of the project is to improve the documentation related to Disposable VMs and installing Qubes OS on Virtual Machines.
+This project consists of creating a series of instructional videos that satisfy the following criteria:
 
-The current Disposable VMs documentation is scarce, inconsistent in places and is scattered across multiple pages, sometimes hard to find. This project involves consolidating it into one or few easy to find pages, covering all related subjects. It should be written in way easy to follow and understand, clearly separating basic use cases, advanced ones and internal details. The terminology should also be used consistently.
+- Prospective users who are not yet familiar with Linux or Qubes OS can easily understand and follow the videos.
+- The videos make a good effort to catch and keep the attention of their target audience.
+- Users can follow the videos step-by-step to install Qubes OS and accomplish various tasks.
+- The videos show the actual software being used (i.e., Qubes OS and any relevant software running inside of it).
+- The videos are technically accurate, include security warnings where appropriate, and use terminology in a way that is consistent with the rest of the documentation (also see the [glossary](/doc/glossary/)).
+- The video series is comprehensive enough that users do not need to consult the documentation or ask questions (e.g., on the forum) in order to accomplish the most popular tasks and activities.
+- The videos include voice narration. (Showing the speaker is optional.)
+- The quality of the videos is consistent with current standards regarding things like editing, transitions, animations, lighting, and audio quality.
+- The videos are in high definition (minimum 1080p, preferably 4k).
+- The videos are separated into a series, where each video is an appropriate length and is appropriately connected to the other videos in the series.
+- The videos are suitable for upload and sharing on popular video-sharing and social-media platforms, such as YouTube and Twitter. (The account or channel under which the videos are uploaded is open to discussion on platforms where the Qubes OS Project does not already have a significant established presence, such as YouTube.)
+- The videos are suitable for embedding in appropriate places in the Qubes documentation. (E.g., a video on how to update Qubes OS should be appropriate for appearing on the [how to update](/doc/how-to-update/) page.)
+- Where possible, the videos should strive to be version-independent. (For example, a video explaining the template system should still be relevant many releases from now if the template system has not changed.)
 
-Additionally, Qubes OS is missing an installation guide for virtual machines. Users are installing an outdated and unsupported version of Qubes OS (3.2) instead of the supported version. There is unofficial existing installation guide for Qubes OS on a virtual box but it is misleading and lacks documentation. Usually, users face some errors and bugs while installing Qubes OS on a virtual machine. This project also involves writing an installation guide that details how to install Qubes on virtual machines, and how to troubleshoot any issues that may arise. 
+Below is an example of the content (which is already [documented](/doc/)) that the video series is likely to cover. The precise scope of content is to be determined in consultation with the video creator.
 
-#### Project’s scope
+- Introduction to Qubes
+- Selecting appropriate hardware
+- How to install Qubes OS
+- First steps after installing
+- How to organize your qubes
+- How to update
+- How to back up, restore, and migrate
+- How to copy and paste text (including dom0)
+- How to copy and move files (including dom0)
+- How to install software
+- How to use and customize disposables
+- How to enter fullscreen mode
+- How to use devices (including block storage, USB, PCI, and optical)
+- Templates: understanding, installing, uninstalling, reinstalling, etc.
+- Common troubleshooting (preferably included in previous videos at appropriate points)
+- The Qubes firewall
+- Passwordless root
+- Anti Evil Maid
+- Split GPG
+- U2F proxy
+- YubiKey
+- Whonix
+- How to install and use a VPN in Qubes
+- How to install and use Windows in Qubes
+- Other popular topics, as time permits
 
-The technical writer will:
+The project is estimated to need around six months to complete (see the timeline below). Qubes team members, including Michael Carbone, Andrew Wong, and Marek Marczykowski-Górecki, will supervise and support the creator.
 
-* Review existing Disposable VM documentation
+### Measuring the project's success
 
-* Propose new documentation layout, including split between pages
+We will consider the project successful if, after publication of the video series:
 
-* Propose updated and clarified content
+- Actual prospective users with no prior familiarity with Linux or Qubes OS are able to successfully install and use Qubes OS as intended by following along with the videos.
+- The reception to the videos is generally positive and complaints about quality and accuracy are minimal.
+- Appropriate analytics (e.g., YouTube metrics) are average or better for videos of this type (to be determined in consultation with the creator).
 
-* Provide a new option of installation guide for users working on virtual machines. 
+### Timeline
 
-* Review existing problems and provide solutions to them. 
+| Dates          | Action items                            |
+| -------------- | --------------------------------------- |
+| March          | Orientation                             |
+| April--October | Create Qubes OS video series            |
+| November       | Final project evaluation and case study |
 
-* Giving a warning for using outdated versions of Qubes.
 
-Knowledge prerequisites:
+### Project budget
 
-* Basic Qubes OS knowledge - intro, getting started.
+| Expense                                 | Amount  |
+| --------------------------------------- | ------- |
+| Video creator (20 hours/week, 6 months) | $12,000 |
+| TOTAL                                   | $12,000 |
 
-* Markdown.
+### Additional information
 
-* Experience in virtual boxes and machines.
+Qubes OS regularly participates in Google Summer of Code and Google Season of Docs. This is our third time participating in Google Season of Docs. Our mentorships for GSoD 2019 and 2020 were successes, and both projects were completed within the times allotted. The past Google Season of Docs projects have given us experience in working with technical writers and have helped us to understand the benefits that technical writers can bring to our project. While our experience in working with video creators is more limited, we are keenly aware of the benefits of high-quality video content, as well as the significant time, resources, and talent required to create it.
-
-* Basic knowledge about Fedora Linux architecture.
-
-The project is estimated to need around 6 months, with a part-time (20hr/week) workload. Qubes OS team members focused on documentation (Michael Carbone, Andrew David Wong, Marek Marczykowski-Górecki) have committed to supporting the project.
-
-#### Measuring the project’s success
-
-We will consider the project successful if, after publication of the new documentation:
-
-* The Disposable VM documentation is consilidated into a few pages and easier to find.
-
-* Disposable VM terminology is consistent across all pages
-
-* There is a new installation guide detailing how to install Qubes on virtual machines (VirtualBox), complete with screenshots and troubleshooting steps where necessary. 
-
-* There is a decrease (by ~20%) in the number of issues and questions raised for topics covered in the documentation, whether in the official Github issues tracker, the Qubes mailing list, or the Qubes community forum.
-
-#### Budget
-
-| Budget item | Amount | Running total | Note / Justification |
-|-|-|-|-|
-| Technical writer audit, update, and write new documentation | $12000 | $12000 | based on a 20hr/week for 6 months at 25$/hr |
-| TOTAL |  | $12000 |  |
-
-#### Additional information 
-Qubes OS regularly participates in the Google Summer of Code and Google Season of Docs. This is our third time in a row participating in Google Season of Docs. Our mentorships for GSoD 2019 and 2020 were successes and both projects were completed 
-within the times allotted. The past Google Season of Docs projects have given us experience in working with technical writers, and has helped us to understand the benefits of technical writers can to our project
 
 ## Past Projects
 
@@ -110,7 +127,7 @@ This could be helped by writing a consolidated guide with a clear list of sympto
 
 **Project**: Improve Getting Started page
 
-**Brief explanation**: The [Getting Started page](https://www.qubes-os.org/doc/getting-started/) is the place a new user would go to understand better how to use Qubes. It is currently has old screenshots not using the default desktop environment and could have much better flow. In addition, this improved page content may end up being served more directly to the user via the [offline documentation](https://github.com/QubesOS/qubes-issues/issues/1019) or the firstboot guide. 
+**Brief explanation**: The [Getting Started page](/doc/getting-started/) is the place a new user would go to understand better how to use Qubes. It is currently has old screenshots not using the default desktop environment and could have much better flow. In addition, this improved page content may end up being served more directly to the user via the [offline documentation](https://github.com/QubesOS/qubes-issues/issues/1019) or the firstboot guide. 
 
 **Expected results**: 
 
@@ -128,14 +145,14 @@ This could be helped by writing a consolidated guide with a clear list of sympto
 
 **Project**: Rewrite qrexec documentation
 
-**Brief explanation**: Current qrexec (qubes remote exec) documentation is hard to follow, important informations are hidden within a wall of text.
+**Brief explanation**: Current qrexec (qubes remote exec) documentation is hard to follow, important information is hidden within a wall of text.
 Some parts are split into multiple sections, for example version specific to avoid duplication, but it doesn't help reading it.
 Additionally, protocol documentation describes only few specific use cases, instead of being clear and precise protocol specification.
 Fixing this last point may require very close cooperation with developers, as the current documentation doesn't multiple corner cases (that's one of the issue with its current shape).
 
 **Expected results**:
 
-- Review existing [qrexec documentation](https://www.qubes-os.org/doc/qrexec3/) and an [issue about it](https://github.com/QubesOS/qubes-issues/issues/1392)
+- Review existing [qrexec documentation](/doc/qrexec3/) and an [issue about it](https://github.com/QubesOS/qubes-issues/issues/1392)
 - Propose updated, consolidated admin documentation (policy writing, adding services)
 - Propose consolidated protocol specification, based on the current documentation, and cooperation with developers
 

developer/general/usability-ux.md

@@ -206,14 +206,14 @@ Clearly, cutting out something as simple as navigating through the file system c
 
 ## GNOME, KDE, and Xfce
 
-The desktop GUIs that QubesOS versions 1 - 3.1 offer are [KDE](https://www.kde.org) and [Xfce](https://xfce.org). We are currently migrating towards using [GNOME](https://www.gnome.org). We know some people prefer KDE, but we believe Gnome is easier to use for average non-technical users. Xfce will always be supported, and technical users will always have the choice to use KDE or other desktop environments.
+The desktop GUIs that QubesOS versions 1 - 4.1 offer are [KDE](https://kde.org) and [Xfce](https://xfce.org). We are currently migrating towards using [GNOME](https://www.gnome.org). We know some people prefer KDE, but we believe Gnome is easier to use for average non-technical users. Xfce will always be supported, and technical users will always have the choice to use KDE or other desktop environments.
 
-This change means you should use [GTK](https://www.gtk.org/) rather than Qt for new GUIs.
+This change means you should use [GTK](https://gtk.org/) rather than Qt for new GUIs.
 
 All three of these mentioned desktop environments have their own [human interface guidelines](https://en.wikipedia.org/wiki/Human_interface_guidelines), and we suggest you familiarize yourself with the platform you developing for.
 
-- [GNOME Human Interface Guidelines](https://developer.gnome.org/hig/3.18/)
+- [GNOME Human Interface Guidelines](https://developer.gnome.org/hig/)
-- [KDE HIG](https://techbase.kde.org/Projects/Usability/HIG)
+- [KDE HIG](https://hig.kde.org/)
 - [Xfce UI Guidlines](https://wiki.xfce.org/dev/hig/general)
 
 ---
@@ -222,9 +222,9 @@ All three of these mentioned desktop environments have their own [human interfac
 
 Learning to make well designing intuitive interfaces and software is specialized skillset that can take years to cultivate, but if you are interested in furthering your understanding, we suggest the following resources:
 
-- [Learn Design Principles](http://learndesignprinciples.com) by Melissa Mandelbaum
+- [Learn Design Principles](https://web.archive.org/web/20180101172357/http://learndesignprinciples.com/) by Melissa Mandelbaum
-- [Usability in Free Software](http://jancborchardt.net/usability-in-free-software) by Jan C. Borchardt
+- [Usability in Free Software](https://jancborchardt.net/usability-in-free-software) by Jan C. Borchardt
 - [Superheroes & Villains in Design](https://vimeo.com/70030549) by Aral Balkan
-- [First Rule of Usability? Don’t Listen to Users](http://www.nngroup.com/articles/first-rule-of-usability-dont-listen-to-users/) by Jakob Nielsen
+- [First Rule of Usability? Don’t Listen to Users](https://www.nngroup.com/articles/first-rule-of-usability-dont-listen-to-users/) by Jakob Nielsen
 - [10 Usability Heuristics for User Interface Design](https://www.nngroup.com/articles/ten-usability-heuristics/) by Jakob Nielsen
 - [Hack Design](https://hackdesign.org/) - online learning program

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

@@ -0,0 +1,48 @@
+---
+layout: doc
+title: Qubes OS 4.2.0 release notes
+permalink: /doc/releases/4.2/release-notes/
+---
+
+_**Please note:** This page is still an unfinished draft in progress. It is being updated as Qubes 4.2 development and testing continues._
+
+## New features and improvements since Qubes 4.1
+
+- Dom0 upgraded to Fedora 37 ([#6982](https://github.com/QubesOS/qubes-issues/issues/6982))
+- Xen upgraded to version 4.17
+- Default Debian template upgraded to Debian 12
+- Default Fedora and Debian templates use Xfce instead of GNOME ([#7784](https://github.com/QubesOS/qubes-issues/issues/7784))
+- SELinux support in Fedora templates ([#4239](https://github.com/QubesOS/qubes-issues/issues/4239))
+- Several GUI applications rewritten, including:
+  - Applications Menu (also available as preview in R4.1) ([#6665](https://github.com/QubesOS/qubes-issues/issues/6665)), ([#5677](https://github.com/QubesOS/qubes-issues/issues/5677))
+  - Qubes Global Settings ([#6898](https://github.com/QubesOS/qubes-issues/issues/6898))
+  - Create New Qube
+  - Qubes Update ([#7443](https://github.com/QubesOS/qubes-issues/issues/7443))
+- Unified `grub.cfg` location for both UEFI and legacy boot ([#7985](https://github.com/QubesOS/qubes-issues/issues/7985))
+- PipeWire support ([#6358](https://github.com/QubesOS/qubes-issues/issues/6358))
+- fwupd integration for firmware updates ([#4855](https://github.com/QubesOS/qubes-issues/issues/4855))
+- Optional automatic clipboard clearing ([#3415](https://github.com/QubesOS/qubes-issues/issues/3415))
+- Official packages built using Qubes Builder v2 ([#6486](https://github.com/QubesOS/qubes-issues/issues/6486))
+- Split GPG and Split SSH management in Qubes Global Settings
+- Qrexec services use new qrexec policy format by default (but old format is still supported) ([#8000](https://github.com/QubesOS/qubes-issues/issues/8000))
+
+For a full list, including more detailed descriptions, please see
+[here](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+4.2%22+label%3A%22release+notes%22+is%3Aclosed).
+
+## Known issues
+
+- DomU firewalls have completely switched to nftables. Users should add their custom rules to the `custom-input` and `custom-forward` chains. ([#5031](https://github.com/QubesOS/qubes-issues/issues/5031), [#6062](https://github.com/QubesOS/qubes-issues/issues/6062))
+
+For a full list of open bug reports affecting 4.2, please see [here](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+label%3Aaffects-4.2+label%3A%22T%3A+bug%22+is%3Aopen). We strongly recommend [updating Qubes OS](/doc/how-to-update/) immediately after installation in order to apply any and all available bug fixes.
+
+## Download
+
+All Qubes ISOs and associated [verification files](/security/verifying-signatures/) are available on the [downloads](/downloads/) page.
+
+## Installation instructions
+
+See the [installation guide](/doc/installation-guide/).
+
+## Upgrading
+
+Please see [how to upgrade to Qubes 4.2](/doc/upgrade/4.2/).

developer/releases/4_2/schedule.md

@@ -0,0 +1,18 @@
+---
+lang: en
+layout: doc
+permalink: /doc/releases/4.2/schedule/
+redirect_from:
+- /en/doc/releases/4.2/schedule/
+title: Qubes R4.2 release schedule
+---
+
+_**Please note:** This page is still an unfinished draft in progress. It is being updated as Qubes 4.2 development and testing continues._
+
+The table below is based on our [release schedule
+policy](/doc/version-scheme/#release-schedule).
+
+|  Date      | Stage                                     |
+| ----------:| ----------------------------------------- |
+| 2023-06-02 | 4.2.0-rc1 release                         |
+| TODO       | current-testing freeze before 4.2.0-rc2   |

developer/releases/notes.md

@@ -6,10 +6,11 @@ ref: 13
 title: Release notes
 ---
 
-* [Qubes R1.0 release notes](/doc/releases/1.0/release-notes/)
+- [Qubes R1.0 release notes](/doc/releases/1.0/release-notes/)
-* [Qubes R2.0 release notes](/doc/releases/2.0/release-notes/)
+- [Qubes R2.0 release notes](/doc/releases/2.0/release-notes/)
-* [Qubes R3.0 release notes](/doc/releases/3.0/release-notes/)
+- [Qubes R3.0 release notes](/doc/releases/3.0/release-notes/)
-* [Qubes R3.1 release notes](/doc/releases/3.1/release-notes/)
+- [Qubes R3.1 release notes](/doc/releases/3.1/release-notes/)
-* [Qubes R3.2 release notes](/doc/releases/3.2/release-notes/)
+- [Qubes R3.2 release notes](/doc/releases/3.2/release-notes/)
-* [Qubes R4.0 release notes](/doc/releases/4.0/release-notes/)
+- [Qubes R4.0 release notes](/doc/releases/4.0/release-notes/)
-* [Qubes R4.1 release notes](/doc/releases/4.1/release-notes/)
+- [Qubes R4.1 release notes](/doc/releases/4.1/release-notes/)
+- [Qubes R4.2 release notes](/doc/releases/4.2/release-notes/)

developer/releases/schedules.md

@@ -6,8 +6,9 @@ ref: 15
 title: Release schedules
 ---
 
-* [Qubes R3.0 release schedule](/doc/releases/3.0/schedule/)
+- [Qubes R3.0 release schedule](/doc/releases/3.0/schedule/)
-* [Qubes R3.1 release schedule](/doc/releases/3.1/schedule/)
+- [Qubes R3.1 release schedule](/doc/releases/3.1/schedule/)
-* [Qubes R3.2 release schedule](/doc/releases/3.2/schedule/)
+- [Qubes R3.2 release schedule](/doc/releases/3.2/schedule/)
-* [Qubes R4.0 release schedule](/doc/releases/4.0/schedule/)
+- [Qubes R4.0 release schedule](/doc/releases/4.0/schedule/)
-* [Qubes R4.1 release schedule](/doc/releases/4.1/schedule/)
+- [Qubes R4.1 release schedule](/doc/releases/4.1/schedule/)
+- [Qubes R4.2 release schedule](/doc/releases/4.2/schedule/)

developer/releases/version-scheme.md

@@ -27,6 +27,13 @@ notable exception, as upstream OSes almost always have their own release
 schedules.) Bug fixes are allowed in all releases, and backward-compatible
 changes are allowed in all major and minor releases.
 
+Qubes OS minor releases generally include new features, new templates, and
+occasionally new defaults, but they are still backward-compatible in the sense
+that qubes and features that worked in the previous release still function,
+though the UI may be different in some cases. In general, deprecated features
+are removed only in major releases, and in-place upgrades between major versions
+are not guaranteed.
+
 Following standard practice, **version** refers to any build that has been
 assigned a version name or number, e.g., `3.2-rc2`, `4.0.4`, `4.1-beta1`. By
 contrast, **release** refers to any version that is intended for consumption by
@@ -52,47 +59,48 @@ Qubes OS. Another remix may have its own version series.
 
 ## Release versioning
 
-Qubes OS as a whole is released from time to time. When preparing a new
+Qubes OS as a whole is released from time to time. When preparing a new release,
-release, we decide on the `<major>.<minor>` numbers (e.g., `3.0`). We then
+we decide on the `<major>.<minor>` numbers (e.g., `3.0`, which is short for
-publish the first release candidate, `3.0-rc1`. When we feel that enough
+`3.0.0`). We then publish the first release candidate, e.g., `3.0.0-rc1`. When
-progress has been made, we'll release `3.0-rc2` and so on. All these versions
+we feel that enough progress has been made, we'll release `3.0.0-rc2` and so on.
-(not yet releases) are considered unstable and not for production use. You are
+All these versions (which are not yet releases) are considered unstable and are
-welcome to [help us test](/doc/testing/) these versions.
+not intended for production use. You are welcome to [help us
+test](/doc/testing/) these versions.
 
 When enough progress has been made, we announce the first stable release, e.g.
-`3.0.0`. This not only a version but an actual release. It is considered stable
+`3.0.0`. This is not only a version but an actual release. It is considered
-and we commit to supporting it according to our [support
+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 master branch. Please see [help,
 support, mailing lists, and forum](/support/) for places to ask questions about
-stable releases. No major features and interface incompatibilities are to be
+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`,
 `3.0.2`, and so on), while backward-compatible enhancements and new features
 are introduced in the next minor release (e.g., `3.1`). Any
 backward-incompatible changes are introduced in the next major release (e.g.,
 `4.0`).
 
-Issues in our [issue tracker](/doc/issue-tracking/) are sorted by release
+Please see [issue tracking](/doc/issue-tracking/) for information about how
-[milestones](/doc/issue-tracking/#milestones).
+releases are handled in the issue tracker.
 
 ## Release schedule
 
-There is no specific schedule for releases other that more general roadmap.
+There is no specific schedule for releases other than a general roadmap.
-When time comes, Supreme Committee declares feature freeze and tags `-rc1` and
+When the time comes, we declare a feature freeze, tag `-rc1`, and
-releases ISO image. From this time on, no new features are accepted. Also a
+release an ISO. From this point on, no new features are accepted, and our
-strict time schedule kicks in.
+schedule begins.
 
-Each release candidate period is as follows. For the first two weeks we accept
+Each release candidate period is as follows: For the first two weeks, we accept
-and assign bug reports to be fixed before next release candidate. For the next
+and assign bug reports to be fixed before the next release candidate. For the
-two weeks we generally focus on fixing assigned bug reports, so issues
+next two weeks, we generally focus on fixing assigned bug reports, so issues
-discovered during this time may be postponed until later RC. Finally after that
+discovered during this period may be postponed until a later RC. Finally,
-there is one week of current-testing freeze, during which time no new packages
+there is a one week current-testing freeze, during which time no new packages
-are released, in hope that they will be installed by wider user base and
+are released, in the hope that they will be installed and tested by wider user
-tested.
+base.
 
-The next RC is released five weeks after the former. All packets are published
+The next RC is released five weeks after the former. All packages are published
-in `current` repository and the cycle starts over. There should be no less than
+in the `current` repository, and the cycle starts over. There should always be
-1 and no more than 3 release candidates before final release.
+at least one release candidate before the final release.
 
 | Stage                    | Duration  |
 | ------------------------ | --------- |
@@ -100,11 +108,11 @@ in `current` repository and the cycle starts over. There should be no less than
 | bug fixing               | two weeks |
 | `current-testing` freeze | one week  |
 
-Starting with second cycle (that is, after `-rc1`) two weeks into the cycle
+Starting with the second cycle (that is, after `-rc1`), two weeks into the cycle
-(after primary bug-reporting period) the Supreme Committee decides whether
+(after the primary bug-reporting period), we decide whether there should be
-there should be another RC. If, based on remaining issues, the Committee
+another RC. If, based on the bugs that have been reported, we decide that the
-decides to release final, then the Committee agrees upon the release date,
+latest RC will be designated as the stable release, then we decide on its
-which should be no later than a week after.
+release date, which should be no more than one week later.
 
 [![Release cycle](/attachment/doc/release-cycle.svg)](/attachment/doc/release-cycle.svg)
 

developer/system/security-critical-code.md

@@ -15,7 +15,7 @@ Below is a list of security-critical (i.e., trusted) code components in Qubes OS
 A successful attack against any of these components could compromise the system's security.
 This code can be thought of as the Trusted Computing Base (TCB) of Qubes OS.
 One of the main goals of the project is to keep the TCB to an absolute minimum.
-The size of the current TCB is on the order order of hundreds of thousands of lines of C code, which is several orders of magnitude less than other OSes.
+The size of the current TCB is on the order of hundreds of thousands of lines of C code, which is several orders of magnitude less than other OSes.
 (In Windows, Linux, and Mac OSes, the amount of trusted code is typically on the order of tens of *millions* of lines of C code.)
 
 For more information, see [Qubes Security Goals](/security/goals/).

developer/system/template-implementation.md

@@ -10,6 +10,8 @@ ref: 58
 title: Template implementation
 ---
 
+## Block devices of a VM
+
 Every VM has 4 block devices connected:
 
 - **xvda** – base root device (/) – details described below
@@ -17,7 +19,7 @@ Every VM has 4 block devices connected:
 - **xvdc** – volatile.img, discarded at each VM restart – here is placed swap and temporal "/" modifications (see below)
 - **xvdd** – modules.img – kernel modules and firmware
 
-## private.img (xvdb)
+### private.img (xvdb)
 
 This is mounted as /rw and here is placed all VM private data. This includes:
 
@@ -25,9 +27,9 @@ 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`. 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 `/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.
 
-## modules.img (xvdd)
+### modules.img (xvdd)
 
 As the kernel is chosen in dom0, there must be some way to provide matching kernel modules to VM. Qubes kernel directory consists of 3 files:
 
@@ -37,9 +39,9 @@ As the kernel is chosen in dom0, there must be some way to provide matching kern
 
 Normally kernel "package" is common for many VMs (can be set using qvm-prefs). One of them can be set as default (qvm-set-default-kernel) to simplify kernel updates (by default all VMs use the default kernel). All installed kernels are placed in /var/lib/qubes/vm-kernels as separate subdirs. In this case, modules.img is attached to the VM as R/O device.
 
-There is a special case when the VM can have a custom kernel – when it is updateable (StandaloneVM or TemplateVM) and the kernel is set to "none" (by qvm-prefs). In this case the VM uses the kernel from the "kernels" VM subdir and modules.img is attached as R/W device. FIXME: "none" should be renamed to "custom".
+There is a special case when the VM can have a custom kernel – when it is updateable (StandaloneVM or TemplateVM) and the kernel is set to "none" (by qvm-prefs). In this case the VM uses the kernel from the "kernels" VM subdir and modules.img is attached as R/W device.
 
-# Qubes TemplateVM implementation
+## Qubes TemplateVM implementation
 
 TemplateVM has a shared root.img across all AppVMs that are based on it. This mechanism has some advantages over a simple common device connected to multiple VMs:
 
@@ -50,7 +52,7 @@ There are two layers of the device-mapper snapshot device; the first one enables
 
 ![TemplateSharing2.png](/attachment/doc/TemplateSharing2.png)
 
-## Snapshot device in Dom0
+### Snapshot device in Dom0
 
 This device consists of:
 
@@ -61,7 +63,7 @@ The above is achieved through creating device-mapper snapshots for each version
 
 When an AppVM is stopped the xen hotplug script checks whether the device is still in use – if it is not, the script removes the snapshot and frees the loop device.
 
-### Changes to template filesystem
+#### Changes to template filesystem
 
 In order for the full potential of the snapshot device to be realized, every change in root.img must save the original version of the modified block in root-cow.img. This is achieved by a snapshot-origin device.
 
@@ -69,7 +71,7 @@ When TemplateVM is started, it receives the snapshot-origin device connected as
 
 When TemplateVM is stopped, the xen script moves root-cow.img to root-cow.img.old and creates a new one (using the `qvm-template-commit` tool). The snapshot device will remain untouched due to the loop device, which uses an actual file on the disk (by inode, not by name). Linux kernel frees the old root-cow.img files as soon as they are unused by all snapshot devices (to be exact, loop devices). The new root-cow.img file will get a new inode number, and so new AppVMs will get new snapshot devices (with different names).
 
-### Rollback template changes
+#### Rollback template changes
 
 There is possibility to rollback last template changes. Saved root-cow.img.old contains all changes made during last TemplateVM run. Rolling back changes is done by reverting this "binary patch".
 
@@ -85,7 +87,7 @@ Steps performed by **qvm-revert-template-changes**:
 6. Cleanup snapshot device (if nobody uses it at the moment).
 7. Move *root-cow.img.old* to *root-cow.img* (overriding existing file).
 
-## Snapshot device in AppVM
+### Snapshot device in AppVM
 
 Root device is exposed to AppVM in read-only mode. AppVM can write only in:
 
@@ -99,7 +101,7 @@ volatile.img is divided into two partitions:
 
 Inside of an AppVM, the root device is wrapped by the snapshot in the first partition of volatile.img. Therefore, the AppVM can write anything to its filesystem – however, such changes will be discarded after a restart.
 
-## StandaloneVM
+### StandaloneVM
 
 Standalone VM enables user to modify root filesystem persistently. It can be created using *--standalone* switch to *qvm-create*.
 

introduction/contributing.md

@@ -48,10 +48,10 @@ interest and experience. For example, here are some common issue labels:
 
 * [Help wanted](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22&utf8=%E2%9C%93)
 * [UX and usability](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3AUX)
-* [Windows tools](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+windows+tools%22)
+* [Windows tools](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+windows-tools%22)
 * [Documentation](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+doc%22)
 * [Privacy](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3A%22privacy%22%20)
-* [Debian](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+Debian%22)
+* [Debian/Ubuntu](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+Debian%2FUbuntu%22)
 
 Before you engage in an activity that will take you a significant amount of
 time, like implementing a new feature, it's always good to contact us first,

introduction/faq.md

@@ -186,10 +186,7 @@ We believe that this is currently the only practically viable approach to implem
 
 ### Does Qubes use full disk encryption (FDE)?
 
-Yes, of course!
+By default, Qubes OS uses [LUKS](https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup)/[dm-crypt](https://en.wikipedia.org/wiki/Dm-crypt) to encrypt everything except the `/boot` partition.
-Full disk encryption is enabled by default.
-Specifically, we use [LUKS](https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup)/[dm-crypt](https://en.wikipedia.org/wiki/Dm-crypt).
-You can even [manually configure your encryption parameters](/doc/custom-install/) if you like!
 
 ### What do all these terms mean?
 
@@ -331,6 +328,16 @@ So, if feature X isn't enabled, it's most likely for one of three reasons:
 
 If it seems like a feature that we can and should enable, please [let us know](/doc/issue-tracking/)!
 
+### Why do the mailing lists require a Google account?
+
+They don't. This is a common misconception. The mailing lists have never required a Google account. It has always been possible to use them purely via email (see the [mailing lists](/support/#mailing-lists) section for instructions).
+
+A lot of people probably see that the mailing lists use Google Groups and just assume that a Google account must be required, but it's not true. Google Groups is simply used for the infrastructure. Of course, you *can* use the web interface with a Google account, but there are many people in the Qubes community who participate on the mailing lists without one.
+
+### Why do you use Google Groups for the mailing lists?
+
+For the same general reasons as listed in [FAQ: Why do you use GitHub?](/faq/#why-do-you-use-github)
+
 ## Users
 
 ### Can I watch YouTube videos in qubes?
@@ -787,7 +794,7 @@ UEFI Secure Boot is not supported out of the box as UEFI support in Xen is very
 Arguably secure boot reliance on UEFI integrity is not the best design.
 The relevant binaries (shim.efi, xen.efi, kernel / initramfs) are not signed by the Qubes Team and secure boot has not been tested.
 Intel TXT (used in [Anti Evil Maid](/doc/anti-evil-maid/)) at least tries to avoid or limit trust in BIOS.
-See the Heads project [[1]](https://trmm.net/Heads) [[2]](http://osresearch.net/) for a better-designed non-UEFI-based secure boot scheme with very good support for Qubes.
+See the Heads project [[1]](https://trmm.net/Heads) [[2]](https://osresearch.net/) for a better-designed non-UEFI-based secure boot scheme with very good support for Qubes.
 
 ### What is the canonical way to detect Qubes VM?
 

introduction/issue-tracking.md

@@ -16,11 +16,7 @@ ref: 121
 title: Issue tracking
 ---
 
-We use [GitHub Issues](https://docs.github.com/en/issues) as our [issue
+We use [GitHub Issues](https://docs.github.com/en/issues) as our [issue tracking system](https://en.wikipedia.org/wiki/Issue_tracking_system). All issues pertaining to the Qubes OS Project (including auxiliary infrastructure such as this website) are tracked in [qubes-issues](https://github.com/QubesOS/qubes-issues/issues).
-tracking system](https://en.wikipedia.org/wiki/Issue_tracking_system). All
-issues pertaining to the Qubes OS Project (including auxiliary infrastructure
-such as this website) are tracked in
-[qubes-issues](https://github.com/QubesOS/qubes-issues/issues).
 
 ## How to open a new issue
 
@@ -28,306 +24,155 @@ First, let's make sure the issue tracker is the right place.
 
 ### I need help, have a question, or want to discuss something.
 
-We're happy to help, answer questions, and have discussions, but the issue
+We're happy to help, answer questions, and have discussions, but the issue tracker is not the right place for these activities. Instead, please see [Help, Support, Mailing Lists, and Forum](/support/).
-tracker is not the right place for these activities. Instead, please see [Help,
-Support, Mailing Lists, and Forum](/support/).
 
 ### I see something that should be changed in the documentation.
 
-We encourage you to submit the change yourself! Please see the [how to edit the
+We encourage you to submit the change yourself! Please see the [how to edit the documentation](/doc/how-to-edit-the-documentation/) for instructions on how to do so. If it's something you can't do yourself, please proceed to open an issue.
-documentation](/doc/how-to-edit-the-documentation/) for instructions on how to
-do so. If it's something you can't do yourself, please proceed to open an issue.
 
 ### I would like to report a security vulnerability.
 
-Thank you! If the vulnerability is confidential, please do not report it in our
+Thank you! If the vulnerability is confidential, please do not report it in our public issue tracker. Instead, please see [Reporting Security Issues in Qubes OS](/security/#reporting-security-issues-in-qubes-os).
-public issue tracker. Instead, please see [Reporting Security Issues in Qubes
-OS](/security/#reporting-security-issues-in-qubes-os).
 
 ### I still want to open an issue.
 
-Great! Thank you for taking the time and effort to help improve Qubes! To
+Great! Thank you for taking the time and effort to help improve Qubes! To ensure the process is efficient and productive for everyone involved, please follow these steps:
-ensure the process is efficient and productive for everyone involved, please
-follow these steps:
 
- 1. Carefully read our issue tracking [guidelines](#guidelines). If your issue
+ 1. Carefully read our issue tracking [guidelines](#guidelines). If your issue would violate any of the guidelines, **stop**. Please do not submit it.
-    would violate any of the guidelines, **stop**. Please do not submit it.
+ 2. [Search through the existing issues](#search-tips), both open and closed, to see if your issue already exists. If it does, **stop**. [Do not open a duplicate.](/doc/issue-tracking/#new-issues-should-not-be-duplicates-of-existing-issues) Instead, comment on the existing issue.
- 2. [Search through the existing issues](#search-tips), both open and closed,
-    to see if your issue already exists. If it does, **stop**. [Do not open a
-    duplicate.](/doc/issue-tracking/#new-issues-should-not-be-duplicates-of-existing-issues)
-    Instead, comment on the existing issue.
  3. Go [here](https://github.com/QubesOS/qubes-issues/issues/new/choose).
  4. Select the [type](#type) of issue you want to open.
  5. Enter a descriptive title.
- 6. Do not delete the provided issue template. Fill out every applicable
+ 6. Do not delete the provided issue template. Fill out every applicable section.
-    section.
+ 7. Make sure to mention any relevant documentation and other issues you've already seen. We don't know what you've seen unless you tell us. If you don't list it, we'll assume you haven't seen it.
- 7. Make sure to mention any relevant documentation and other issues you've
+ 8. If any sections of the issue template are *truly* not applicable, you may remove them.
-    already seen. We don't know what you've seen unless you tell us. If you
-    don't list it, we'll assume you haven't seen it.
- 8. If any sections of the issue template are *truly* not applicable, you may
-    remove them.
  9. Submit your issue.
-10. Respond to any questions the official team asks. For example, you may be
+10. Respond to any questions the official team asks. For example, you may be asked to provide specific logs or other additional information.
-    asked to provide specific logs or other additional information.
 
-Eventually, your issue may be closed. See [how issues get
+Eventually, your issue may be closed. See [how issues get closed](/doc/issue-tracking/#how-issues-get-closed) for details about when, why, and how this occurs.
-closed](/doc/issue-tracking/#how-issues-get-closed) for details about when,
-why, and how this occurs.
 
 ## Labels, milestones, and projects
 
-Labels, milestones, and projects are features of GitHub's issue tracking system
+Labels, milestones, and projects are features of GitHub's issue tracking system that we use to keep [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) organized.
-that we use to keep
-[qubes-issues](https://github.com/QubesOS/qubes-issues/issues) organized.
 
 ### Labels
 
-Only Qubes team members have permission to modify
+When an issue is first created, certain labels may automatically be applied to it based on the type of issue the reporter selected. For example, if someone selects the "Bug report" template, then the `T: bug` label will automatically be applied to that issue. After that, only Qubes team members have permission to modify [labels](https://github.com/QubesOS/qubes-issues/labels) and [milestones](https://github.com/QubesOS/qubes-issues/milestones). Many labels and milestones have descriptions on them that can be viewed either in their respective lists or by hovering over them. Let's go over some of the most important ones.
-[labels](https://github.com/QubesOS/qubes-issues/labels) and
-[milestones](https://github.com/QubesOS/qubes-issues/milestones). Many labels
-and milestones have descriptions on them that can be viewed either in their
-respective lists or by hovering over them. Let's go over some of the most
-important ones.
 
 #### Type
 
-There are three **types**: `T: bug`, `T: enhancement`, and `T: task`.
+There are three issue **types**: `T: bug`, `T: enhancement`, and `T: task`.
 
-- `T: bug` --- Type: bug report. A problem or defect resulting in unintended
+- `T: bug` --- Type: bug report. A problem or defect resulting in unintended behavior in something that exists.
-  behavior in something that exists.
+- `T: enhancement` --- Type: enhancement. A new feature that does not yet exist **or** improvement of existing functionality.
-- `T: enhancement` --- Type: enhancement. A new feature that does not yet exist
+- `T: task` --- Type: task. An action item that is neither a bug nor an enhancement.
-  **or** improvement of existing functionality.
-- `T: task` --- Type: task. An action item that is neither a bug nor an
-  enhancement.
 
-Every open issue should have **exactly one** type. An open issue should not
+Every open issue should have **exactly one** type. An open issue should not have more than one type, and it should not lack a type entirely. Bug reports are for problems in things that already exist. If something doesn't exist yet, but you think it ought to exist, then use `T: enhancement` instead. If something already exists, but you think it could be improved in some way, you should again use `T: enhancement`. `T: task` is for issues that fall under under neither `T: bug` nor `T: enhancement`.
-have more than one type, and it should not lack a type entirely. Bug reports
-are for things that already exist. If something doesn't exist yet, but you
-think it should exist, then `T: enhancement`. If something already exists and
-could be improved in some way, `T: enhancement` is appropriate. `T: task` is
-for issues that fall under under neither `T: bug` nor `T: enhancement`.
 
 #### Priority
 
-There are several **priority** levels ranging from `P: minor` to `P: blocker`
+There are several issue **priority** levels ranging from `P: minor` to `P: blocker` (see [here](https://github.com/QubesOS/qubes-issues/labels?q=P%3A) for the full list). Every open issue should have **exactly one** priority. An open issue should not have more than one priority, and it should not lack a priority entirely. See [here](/doc/version-scheme/#bug-priorities) for details about how the developers use these priorities.
-(see [here](https://github.com/QubesOS/qubes-issues/labels?q=P%3A) for the full
-list). Every open issue should have **exactly one** priority. An open issue
-should not have more than one priority, and it should not lack a priority
-entirely. See [here](/doc/version-scheme/#bug-priorities) for details about how
-the developers use these priorities.
 
 #### Component
 
-There are many **component** labels, each beginning with `C:` (see
+There are many **component** labels, each beginning with `C:` (see [here](https://github.com/QubesOS/qubes-issues/labels?page=2&q=C%3A) for the full list). Every open issue should have **at least one** component. An open issue may have more than one component, but it should not lack a component entirely. When no other component applies, use `C: other`.
-[here](https://github.com/QubesOS/qubes-issues/labels?page=2&q=C%3A) for the
+
-full list). Every open issue should have **at least one** component. An open
+#### Affected release
-issue may have more than one component, but it should not lack a component
+
-entirely. When no other component applies, use `C: other`.
+A label of the form `affects-<RELEASE_NUMBER>` indicates that an issue affects the corresponding Qubes OS release. An issue can have more than one of these labels if it affects multiple releases.
 
 ### Milestones
 
-The issue tracker has several
+The issue tracker has several [milestones](https://github.com/QubesOS/qubes-issues/milestones). Individual issues can be assigned to milestones. The issue tracker does not allow an issue to be assigned to more than one milestone. If an issue is already assigned to a milestone, assigning it to a different one will *replace* the existing milestone assignment. Each milestone has a progress indicator showing how close that milestone is to completion.
-[milestones](https://github.com/QubesOS/qubes-issues/milestones). Every issue
-should be assigned to **exactly one** milestone. The issue tracker does not
-allow assigning an issue to more than one milestone. If an issue is already
-assigned to a milestone, assigning it to a different one will *replace* the
-existing milestone assignment. No open issue should lack a milestone
-assignment.
 
-Most milestones correspond to specific Qubes OS releases. A bug report assigned
+Most milestones correspond to specific Qubes OS releases. The Qubes developers decide which issues will be assigned to specific milestones. The general idea is that each milestone's progress indicator should provide a rough idea of how much progress has been made on that milestone and how much work remains until the milestone is complete. Most issues will not be assigned to any milestone at all until a Qubes developer manually assigns it to one. While anyone is free to open an issue, this does not create an obligation on the Qubes developers to act on that issue. Every open issue should be understood to be merely "under consideration" unless or until a Qubes developer decides to assign it to a milestone. Issues that are assigned to a milestone are issues that either the Qubes developers or another contributor plans to complete *for* that milestone. The Qubes developers reserve the right to modify or remove milestones at any time at their discretion.
-to a release milestone indicates an alleged bug *in* that Qubes OS release. A
-task or enhancement assigned to a release milestone indicates that the goal is
-to implement or do that thing *in* or *for* that Qubes OS release.
-
-The `Release TBD` (To Be Determined) milestone is for enhancements or tasks
-that will be specific to a Qubes OS release but have yet to be assigned to a
-specific release milestone. Bug reports should never be assigned to this
-milestone, because every bug is a problem or defect in something that already
-exists.
-
-The `Non-release` milestone is for issues that are independent of the Qubes OS
-release cycle, including (but not limited to) website, documentation, and
-project management issues. These are issues that will never be assigned to a
-specific Qubes OS release milestone.
 
 ### Projects
 
-The issue tracker has several
+The issue tracker has several [projects](https://github.com/QubesOS/qubes-issues/projects). A project is a way to create a group of multiple related issues. This is the preferred method of grouping issues, whereas trying to use normal issues as "meta-issues" or "epics" is discouraged.
-[projects](https://github.com/QubesOS/qubes-issues/projects). A project is a
-way to create a group of multiple related issues. This is the preferred method
-of grouping issues, whereas trying to use normal issues as "meta-issues" or
-"epics" is discouraged.
 
 ## Search tips
 
-[Search both open and closed
+[Search both open and closed issues.](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue) For example, you may be experiencing a bug that was just fixed, in which case the report for that bug is probably closed. In this case, it would be useful to view [all bug reports, both open and closed, with the most recently updated sorted to the top](https://github.com/QubesOS/qubes-issues/issues?q=label%3Abug+sort%3Aupdated-desc).
-issues.](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue)
-For example, you may be experiencing a bug that was just fixed, in which case
-the report for that bug is probably closed. In this case, it would be useful to
-view [all bug reports, both open and closed, with the most recently updated
-sorted to the
-top](https://github.com/QubesOS/qubes-issues/issues?q=label%3Abug+sort%3Aupdated-desc).
 
-[Search using labels.](https://github.com/QubesOS/qubes-issues/labels) For
+[Search using labels.](https://github.com/QubesOS/qubes-issues/labels) For example, you can search issues by priority ([blocker](https://github.com/QubesOS/qubes-issues/labels/P%3A%20blocker), [critical](https://github.com/QubesOS/qubes-issues/labels/P%3A%20critical), [major](https://github.com/QubesOS/qubes-issues/labels/P%3A%20major), etc.) and by component ([core](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+core%22), [manager/widget](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22C%3A+manager%2Fwidget%22+), [Xen](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+Xen%22), etc.).
-example, you can search issues by priority
-([blocker](https://github.com/QubesOS/qubes-issues/labels/P%3A%20blocker),
-[critical](https://github.com/QubesOS/qubes-issues/labels/P%3A%20critical),
-[major](https://github.com/QubesOS/qubes-issues/labels/P%3A%20major), etc.) and
-by component
-([core](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+core%22),
-[manager/widget](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22C%3A+manager%2Fwidget%22+),
-[Xen](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+Xen%22),
-etc.).
 
-You can also try searching by
+You can also try searching by [milestone](https://github.com/QubesOS/qubes-issues/milestones) and by [project](https://github.com/QubesOS/qubes-issues/projects).
-[milestone](https://github.com/QubesOS/qubes-issues/milestones) and by
-[project](https://github.com/QubesOS/qubes-issues/projects).
 
 ## Guidelines
 
 ### The issue tracker is not a discussion forum
 
-The issue tracker is a tool to help the developers be more productive and
+The issue tracker is a tool to help the developers be more productive and efficient in their work. It is not a place for discussion. If you wish to discuss something in the issue tracker, please do so on the forum or mailing lists (see [Help, Support, Mailing Lists, and Forum](/support/)). You can simply link to the relevant issue in your discussion post.
-efficient in their work. It is not a place for discussion. If you wish to
-discuss something in the issue tracker, please do so on the forum or mailing
-lists (see [Help, Support, Mailing Lists, and Forum](/support/)). You can
-simply link to the relevant issue in your discussion post.
 
-This guideline is important for keeping issues focused on *actionable
+This guideline is important for keeping issues focused on *actionable information*, which helps the developers to stay focused on their work. When developers come back to an issue to work on it, we do not want them to have to sift through a large number of unnecessary comments before they can get started. In many cases, an issue that gets "too big" essentially becomes more trouble than it's worth, and no developer will touch it (also see [every issue must be about a single, actionable thing](#every-issue-must-be-about-a-single-actionable-thing)). In these cases, we sometimes have to close the issue and open a new one. This is a waste of energy for everyone involved, so we ask that everyone help to avoid repeating this pattern.
-information*, which helps the developers to stay focused on their work. When
-developers come back to an issue to work on it, we do not want them to have to
-sift through a large number of unnecessary comments before they can get
-started. In many cases, an issue that gets "too big" essentially becomes more
-trouble than it's worth, and no developer will touch it (also see [every issue
-must be about a single, actionable
-thing](#every-issue-must-be-about-a-single-actionable-thing)). In these cases,
-we sometimes have to close the issue and open a new one. This is a waste of
-energy for everyone involved, so we ask that everyone help to avoid repeating
-this pattern.
 
 ### Do not submit questions
 
-[qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is not the place
+[qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is not the place to ask questions. This includes, but is not limited to, troubleshooting questions and questions about how to do things with Qubes. Instead, see [Help, Support, Mailing Lists, and Forum](/support/) for appropriate place to ask questions. By contrast, [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is meant for tracking more general bugs, enhancements, and tasks that affect a broad range of Qubes users.
-to ask questions. This includes, but is not limited to, troubleshooting
-questions and questions about how to do things with Qubes. Instead, see [Help,
-Support, Mailing Lists, and Forum](/support/) for appropriate place to ask
-questions. By contrast,
-[qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is meant for
-tracking more general bugs, enhancements, and tasks that affect a broad range
-of Qubes users.
 
 ### Use the issue template
 
-When you open a new issue, an issue template is provided for you. Please use
+When you open a new issue, an issue template is provided for you. Please use it. Do not delete it. The issue template is carefully designed to elicit important information. Without this information, the issue is likely to be incomplete. (If certain sections are not applicable, you may remove them, but please do so only sparingly and only if they are *truly* not applicable.)
-it. Do not delete it. The issue template is carefully designed to elicit
-important information. Without this information, the issue is likely to be
-incomplete. (If certain sections are not applicable, you may remove them, but
-please do so only sparingly and only if they are *truly* not applicable.)
 
-It is also important to note the placement and content of the HTML comments in
+It is also important to note the placement and content of the HTML comments in the issue template. These help us to have issues with a consistent format.
-the issue template. These help us to have issues with a consistent format.
 
 ### Every issue must be about a single, actionable thing
 
-If your issue is not actionable, please see [Help, Support, Mailing Lists, and
+If your issue is not actionable, please see [Help, Support, Mailing Lists, and Forum](/support/) for the appropriate place to post it. If your issue would be about more than one thing, file them as separate issues instead. This means we should generally not try to use a single issue as a "meta" or "epic" issue that exists only to group, contain, or track other issues. Instead, when there is a need to group multiple related issues together, use [projects](https://github.com/QubesOS/qubes-issues/projects).
-Forum](/support/) for the appropriate place to post it. If your issue would be
-about more than one thing, file them as separate issues instead. This means we
-should generally not try to use a single issue as a "meta" or "epic" issue that
-exists only to group, contain, or track other issues. Instead, when there is a
-need to group multiple related issues together, use
-[projects](https://github.com/QubesOS/qubes-issues/projects).
 
-This guideline is extremely important for making the issue tracker a useful
+This guideline is extremely important for making the issue tracker a useful tool for the developers. When an issue is too big and composite, it becomes intractable and drastically increases the likelihood that nothing will get done. Such issues also tend to encourage an excessive amount of general discussion that is simply not appropriate for a technical issue tracker (see [the issue tracker is not a discussion forum](#the-issue-tracker-is-not-a-discussion-forum)).
-tool for the developers. When an issue is too big and composite, it becomes
-intractable and drastically increases the likelihood that nothing will get
-done. Such issues also tend to encourage an excessive amount of general
-discussion that is simply not appropriate for a technical issue tracker (see
-[the issue tracker is not a discussion
-forum](#the-issue-tracker-is-not-a-discussion-forum)).
 
 ### New issues should not be duplicates of existing issues
 
-Before you submit an issue, check to see whether it has already been reported.
+Before you submit an issue, check to see whether it has already been reported. Search through the existing issues -- both open and closed -- by typing your key words in the **Filters** box. If you find an issue that seems to be similar to yours, read through it. If you find an issue that is the same as or subsumes yours, leave a comment on the existing issue rather than filing a new one, even if the existing issue is closed. If an issue affects more than one Qubes version, we usually keep only one issue for all versions. The Qubes team will see your comment and reopen the issue, if appropriate. For example, you can leave a comment with additional information to help the maintainer debug it. Adding a comment will subscribe you to email notifications, which can be helpful in getting important updates regarding the issue. If you don't have anything to add but still want to receive email updates, you can click the "Subscribe" button at the side or bottom of the comments.
-Search through the existing issues -- both open and closed -- by typing your
-key words in the **Filters** box. If you find an issue that seems to be similar
-to yours, read through it. If you find an issue that is the same as or subsumes
-yours, leave a comment on the existing issue rather than filing a new one, even
-if the existing issue is closed. If an issue affects more than one Qubes
-version, we usually keep only one issue for all versions. The Qubes team will
-see your comment and reopen the issue, if appropriate. For example, you can
-leave a comment with additional information to help the maintainer debug it.
-Adding a comment will subscribe you to email notifications, which can be
-helpful in getting important updates regarding the issue. If you don't have
-anything to add but still want to receive email updates, you can click the
-"Subscribe" button at the side or bottom of the comments.
 
 ### Every issue must be of a single type
 
-Every issue must be exactly one of the following types: a bug report (`bug`), a
+Every issue must be exactly one of the following types: a bug report (`bug`), a feature or improvement request (`enhancement`), or a task (`task`). Do not file multi-typed issues. Instead, file multiple issues of distinct types. The Qubes team will classify your issue according to its type.
-feature or improvement request (`enhancement`), or a task (`task`). Do not file
-multi-typed issues. Instead, file multiple issues of distinct types. The Qubes
-team will classify your issue according to its type.
 
 ### New issues should include all relevant information
 
-When you file a new issue, you should be sure to include the version of Qubes
+When you file a new issue, you should be sure to include the version of Qubes you're using, as well as versions of related software packages ([how to copy information out of dom0](/doc/how-to-copy-from-dom0/)). If your issue is related to hardware, provide as many details as possible about the hardware. A great way to do this is by [generating and submitting a Hardware Compatibility List (HCL) report](/doc/how-to-use-the-hcl/#generating-and-submitting-new-reports), then linking to it in your issue. You may also need to use command-line tools such as `lspci`. If you're reporting a bug in a package that is in a [testing](/doc/testing/) repository, please reference the appropriate issue in the [updates-status](https://github.com/QubesOS/updates-status/issues) repository. Project maintainers really appreciate thorough explanations. It usually helps them address the problem more quickly, so everyone wins!
-you're using, as well as versions of related software packages ([how to copy
-information out of dom0](/doc/how-to-copy-from-dom0/)). If your issue is
-related to hardware, provide as many details as possible about the hardware. A
-great way to do this is by [generating and submitting a Hardware Compatibility
-List (HCL) report](/doc/how-to-use-the-hcl/#generating-and-submitting-new-reports),
-then linking to it in your issue. You may also need to use command-line tools
-such as `lspci`. If you're reporting a bug in a package that is in a
-[testing](/doc/testing/) repository, please reference the appropriate issue in
-the [updates-status](https://github.com/QubesOS/updates-status/issues)
-repository. Project maintainers really appreciate thorough explanations. It
-usually helps them address the problem more quickly, so everyone wins!
 
 ### There are no guarantees that your issue will be addressed
 
-Keep in mind that
+Keep in mind that [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is an issue tracker, not a support system. Creating a new issue is simply a way for you to submit an item for the Qubes team's consideration. It is up to the Qubes team to decide whether or how to address your issue, which may include closing the issue without taking any action on it. Even if your issue is kept open, however, you should not expect it to be addressed within any particular time frame, or at all. At the time of this writing, there are well over one thousand open issues in [qubes-issues](https://github.com/QubesOS/qubes-issues/issues). The Qubes team has its own roadmap and priorities, which will govern the manner and order in which open issues are addressed.
-[qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is an issue
+
-tracker, not a support system. Creating a new issue is simply a way for you to
+### Issues and comments must be written in English
-submit an item for the Qubes team's consideration. It is up to the Qubes team
+
-to decide whether or how to address your issue, which may include closing the
+If English is not your native language, you may post a machine translation. If you wish, you may also include the original non-English text in a [collapsible section](#use-collapsible-sections-for-long-nonessential-content).
-issue without taking any action on it. Even if your issue is kept open,
+
-however, you should not expect it to be addressed within any particular time
+### Use collapsible sections for long, nonessential content
-frame, or at all. At the time of this writing, there are well over one thousand
+
-open issues in [qubes-issues](https://github.com/QubesOS/qubes-issues/issues).
+On GitHub, create collapsible sections in Markdown like so:
-The Qubes team has its own roadmap and priorities, which will govern the manner
+
-and order in which open issues are addressed.
+```
+<details>
+<summary>Summary goes here. This line is optional.</summary>
+
+Long, nonessential content goes here. You can put a code block here, but make sure to leave empty lines before and after the fence lines (```).
+
+</details>
+```
+
+**Tip:** Use the "Preview" tab to make sure it renders correctly before posting.
 
 ## How issues get closed
 
-If the Qubes developers make a code change that resolves an issue, then the
+If the Qubes developers make a code change that resolves an issue, then the issue will typically be [closed from the relevant commit or merged pull request (PR)](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-issues/linking-a-pull-request-to-an-issue).
-issue will typically be [closed from the relevant commit or merged pull request
-(PR)](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-issues/linking-a-pull-request-to-an-issue).
 
 ### Bug reports
 
-In the case of bugs, the package containing the change will move to the
+In the case of bugs, the package containing the change will move to the appropriate [testing](/doc/testing/) repository, then to the appropriate stable repository. If you so choose, you can test the fix while it's in the [testing](/doc/testing/) repository, or you can wait for it to land in the stable repository. If, after testing the fix, you find that it does not really fix the reported bug, please leave a comment on the issue explaining the situation. When you do, we will receive a notification and respond on the issue or reopen it (or both). Please **do not** create a duplicate issue or attempt to contact the developers individually about a problem.
-appropriate [testing](/doc/testing/) repository, then to the appropriate stable
-repository. If you so choose, you can test the fix while it's in the
-[testing](/doc/testing/) repository, or you can wait for it to land in the
-stable repository. If, after testing the fix, you find that it does not really
-fix the reported bug, please leave a comment on the issue explaining the
-situation. When you do, we will receive a notification and respond on the issue
-or reopen it (or both). Please **do not** create a duplicate issue or attempt
-to contact the developers individually about a problem.
 
 ### Resolution
 
-In other cases, an issue may be closed with a specific resolution, such as `R:
+In other cases, an issue may be closed with a specific resolution, such as `R: invalid`, `R: duplicate`, or `R: won't fix`. Each of these labels has a description that explains the label. We'll also leave a comment explaining why we're closing the issue with one of these specific resolutions. If the issue is closed without one of these specific resolutions, then it means, by default, that the reported bug was fixed or the requested enhancement was implemented.
-invalid`, `R: duplicate`, or `R: won't fix`. Each of these labels has a
-description that explains the label. We'll also leave a comment explaining why
-we're closing the issue with one of these specific resolutions. If the issue is
-closed without one of these specific resolutions, then it means, by default,
-that the reported bug was fixed or the requested enhancement was implemented.
 
 ### Backports
 
-Issues in GitHub can only be open or closed, but, when it comes to bugs that
+Issues in GitHub can only be open or closed, but, when it comes to bugs that affect multiple versions of Qubes OS, there are several possible states:
-affect multiple versions of Qubes OS, there are several possible states:
 
 1. Not fixed yet
 2. Fix developed but not yet committed (PR open)
@@ -337,20 +182,12 @@ affect multiple versions of Qubes OS, there are several possible states:
 6. Update backported to stable version(s) and pushed to the testing repo
 7. Update pushed to stable repo of stable version(s)
 
-We close issues at step 3. Then, as updates are released, the issue
+We close issues at step 3. Then, as updates are released, the issue automatically gets the appropriate `current-testing` (`rX.Y-*-cur-test`) and `stable` (`rX.Y-*-stable`) labels. Based on these labels, it's possible to select issues waiting for step 6 (see [issues by release](https://github.com/QubesOS/qubes-issues#issues-by-release)).
-automatically gets the appropriate `current-testing` (`rX.Y-*-cur-test`) and
-`stable` (`rX.Y-*-stable`) labels. Based on these labels, it's possible to
-select issues waiting for step 6 (see [issues by
-release](https://github.com/QubesOS/qubes-issues#issues-by-release)).
 
-Therefore, if you see that an issue is closed, but the fix is not yet available
+Therefore, if you see that an issue is closed, but the fix is not yet available to you, be aware that it may be at an intermediate stage of this process between issue closure and the update being available in whichever repos you have enabled in whichever version of Qubes you're using.
-to you, be aware that it may be at an intermediate stage of this process
-between issue closure and the update being available in whichever repos you
-have enabled in whichever version of Qubes you're using.
 
-In order to assist with this, we have a label called [backport
+In order to assist with this, we have a label called [backport pending](https://github.com/QubesOS/qubes-issues/labels/backport%20pending), which means, "The fix has been released for the testing release but is pending backport to the stable release." Our infrastructure will attempt to apply this label automatically, when appropriate, but it is not perfect, and the developers may be need to adjust it manually.
-pending](https://github.com/QubesOS/qubes-issues/labels/backport%20pending),
+
-which means, "The fix has been released for the testing release but is pending
+### Understanding open and closed issues
-backport to the stable release." Our infrastructure will attempt to apply this
+
-label automatically, when appropriate, but it is not perfect, and the
+Every issue is always in one of two states: open or closed, with open being the default. The **open** and **closed** states mean that, according to our available information at present, the issue in question either **is** or **is not** (respectively) actionable for the Qubes team. The open and closed states do not mean anything more than this, and it's important not to read anything else into them. It's also important to understand that closing an issue is, in effect, nothing more than changing a virtual tag on an issue. Closing an issue is never "final" in any sense, and it does not affect the issue itself in any other way. Issues can be opened and closed instantly with a single button press an unlimited number of times at no cost. In fact, since the open and closed states reflect our available information at present, one should expect these states to change back and forth as new information becomes available. Closed issues are fully searchable, just like open issues, and we explicitly instruct all users of the issue tracker to search *both* open *and* closed issues, which GitHub makes easy.
-developers may be need to adjust it manually.

introduction/support.md

@@ -512,6 +512,11 @@ on the [news](/news/) page. If you use one of these platforms, you may find it
 convenient to follow the Qubes OS Project there as a way of receiving Qubes
 news.
 
+## Chat
+
+If you'd like to chat, join us on the `#qubes` IRC channel (or its Matrix
+bridge: `#qubes:libera.chat`).
+
 ## Unofficial venues
 
 If you find another venue on the Internet that is not listed above, it is
@@ -522,9 +527,3 @@ moderate it. Please be especially careful in unofficial venues.
 should not be taken as a commitment to monitor or moderate the venue. It still
 remains unofficial. Also, please make sure someone claiming to be a Qubes team
 member really is one. It could be an impostor!)
-
-For example, here are some **unofficial** chat channels we know about that are
-maintained by the community:
-
-* Matrix, Qubes-related: <https://matrix.to/#/#cybersec-qubes_os:matrix.org>
-* `#qubes` channel on irc.libera.chat via traditional IRC clients

project-security/verifying-signatures.md

@@ -294,11 +294,9 @@ Before we proceed, you must first complete the following prerequisite steps:
 2. [Import and authenticate the QMSK.](#how-to-import-and-authenticate-the-qubes-master-signing-key)
 
 After you have completed these two prerequisite steps, the next step is to
-obtain the correct RSK. The filename of the RSK for your Qubes OS release is
+obtain the correct RSK. The filename pattern for RSKs is
-usually `qubes-release-X-signing-key.asc`, where `X` is the [major version
+`qubes-release-X-signing-key.asc`, where `X` is either a major or minor Qubes
-number](https://semver.org/) of your Qubes release. For example, if you were
+release number, such as `4` or `4.2`. There are several ways to get the RSK for
-installing release `1.2.3`, you would replace `X` with `1`, resulting in
-`qubes-release-1-signing-key.asc`. There are several ways to get the RSK for
 your Qubes release.
 
 - If you have access to an existing Qubes installation, the release keys are

user/advanced-topics/awesomewm.md

@@ -36,156 +36,3 @@ $ git clone https://github.com/QubesOS/qubes-desktop-linux-awesome
 For build instructions please check the repository _README_.
 
 The repository attempts to follow the upstream Fedora repository.
-
-## Common customizations
-
-This section focuses on Qubes-specific customizations. For generic AwesomeWM customizations you might want to have a look at the [AwesomeWM website](https://awesomewm.org).
-
-Customizations for AwesomeWM are usually done at `~/.config/awesome/rc.lua`. The default file can be found at `/etc/xdg/awesome/rc.lua`.
-
-### Application menu
-
-Starting from Qubes 4.0 application menu entries specific to AwesomeWM can be put into `~/.config/awesome/xdg-menu/` following the freedesktop standard. The folder might have to be created.
-
-### Focus steal hardening
-
-The default Qubes OS AwesomeWM installation comes with the defaults set by the AwesomeWM developers for focus changes. Some users may want more tight control over window focus changes - especially since focus changes can have security implications when sensitive data is provided to an incorrect application or even qube.
-
-#### Definition
-
-For the below example we'll define _wanted focus changes_ as one of the below:
-
-* mouse move & click afterwards
-* workspace/tag change
-* pre-defined key combinations for focus changes (e.g. Mod-j & Mod-k)
-* tag assignments and unassignments
-
-Everything else is considered an unwanted _focus steal_.
-
-In particular the following events are not meant to cause a focus change:
-
-* new window created
-* a window was closed
-* application request
-* mouse move without click (sloppy focus)
-
-For the below example other requests from applications to the window manager are meant to be ignored in general as well, e.g.:
-
-* windows shouldn't be able to maximize themselves without the user giving a respective command to the WM (simple test: Firefox F11 next to another window)
-* windows shouldn't be able to change their size themselves
-* windows shouldn't be able to modify their borders in any way
-
-Users may want to adjust their definitions and respective implementations according to their needs.
-
-#### Implementation
-
-The implementation may be specific to the AwesomeWM version you're running. This guide refers to AwesomeWM version 3.5.9 which is available to Qubes 4.0 users.
-
-Please keep in mind that this guide may not be conclusive. Your mileage may vary.
-
-##### Change the autofocus implementation
-
-The line `require("awful.autofocus")` in your _rc.lua_ implements various focus-related features for your AwesomeWM instance.
-
-In order to customise these, you can copy the file `/usr/share/awesome/lib/awful/autofocus.lua` to e.g. `~/.config/awesome/autofocus_custom.lua` and replace the line above with `require("autofocus_custom")`.
-
-Then you can customise the focus behavior. According to our above definitions it would look as follows:
-
-```lua
----autofocus_custom.lua
-local client = client
-local screen = screen
-local aclient = require("awful.client")
-local atag = require("awful.tag")
-
---- When loaded, this module makes sure that there's always a client that will have focus
--- on events such as tag switching, client unmanaging, etc.
--- awful.autofocus
-
--- Give focus when clients appear/disappear and no one else has focus.
--- @param obj An object that should have a .screen property.
-function check_focus(obj)
-    -- When no visible client has the focus...
-    if not client.focus or not client.focus:isvisible() then
-        local c = aclient.focus.history.get(obj.screen, 0)
-        if c then client.focus = c end
-    end
-end
-
--- Give focus on tag selection change.
--- @param tag A tag object
-function check_focus_tag(t)
-    local s = atag.getscreen(t)
-    if not s then return end
-    check_focus({ screen = s })
-    if client.focus and client.focus.screen ~= s then
-        local c = aclient.focus.history.get(s, 0)
-        if c then client.focus = c end
-    end
-end
-
---made above functions global & removed some focus switches below (user interaction required instead)
-
---clear any focus
-function clear_focus()
-    --unfortunately this doesn't work at the moment
-    --cf. https://github.com/awesomeWM/awesome/issues/164
-    --(Qubes uses an older AwesomeWM version that doesn't have the fix yet)
-    --client.focus = nil
-end
-
-atag.attached_connect_signal(nil, "property::selected", check_focus_tag)
-client.connect_signal("unmanage", clear_focus)
-client.connect_signal("tagged", check_focus)
-client.connect_signal("untagged", check_focus)
-client.connect_signal("property::hidden", clear_focus)
-client.connect_signal("property::minimized", clear_focus)
-```
-
-##### Remove unwanted focus changing key bindings
-
-The mouse bindings
-
-```lua
-awful.button({ }, 4, awful.tag.viewnext),
-awful.button({ }, 5, awful.tag.viewprev)
-```
-
-in the default _rc.lua_ may cause tag and thus focus changes without keyboard interaction and tend to happen accidentally. This doesn't suit our definition from above and should therefore be removed or commented out.
-
-##### Adjust client rules
-
-The default client rule allows certain focus changes via `focus = awful.client.focus.filter`. These changes can be prevented entirely by setting `focus = false`.
-
-Alternatively users may provide their own focus filter functions.
-
-##### Disable sloppy focus
-
-In your _rc.lua_ you'll find a section such as
-
-```lua
-    -- Enable sloppy focus
-    c:connect_signal("mouse::enter", function(c)
-        if awful.layout.get(c.screen) ~= awful.layout.suit.magnifier
-            and awful.client.focus.filter(c) then
-            client.focus = c
-        end
-    end)
-```
-
-These enable _sloppy focus_ aka focus changes on mouse movements (without clicking) and should be removed or commented out to disable that behaviour.
-
-##### Ignore requests from applications to the window manager
-
-Handling of such requests is currently mostly implemented by AwesomeWM in the file `/usr/share/awesome/lib/awful/ewmh.lua`. You can either comment out the respective `client.connect_singal()` lines in that file (it will change back after each AwesomeWM update though) or disconnect the signals in your _rc.lua_.
-
-As of AwesomeWM 3.5.9 this however is apparently only possible for signals connected to global functions, i.e. currently only the below signals can be disconnected in the _rc.lua_:
-
-```lua
-local ewmh = require("awful.ewmh")
-
-client.disconnect_signal("request::activate", ewmh.activate)
-client.disconnect_signal("request::tag", ewmh.tag)
-```
-
-The signal names may change across AwesomeWM versions.

user/advanced-topics/disposable-customization.md

@@ -15,62 +15,54 @@ title: Disposable customization
 
 ## Introduction
 
-A [disposable](/doc/disposable/) can be based on any [app qube](/doc/glossary/#app-qube).
+A [disposable](/doc/disposable/) can be based on any [app qube](/doc/glossary/#app-qube). You can also choose to use different [disposable templates](/doc/glossary/#disposable-template) for different disposables. To prepare an app qube to be a disposable template, you need to set the `template_for_dispvms` property:
-You can also choose to use different [disposable templates](/doc/glossary/#disposable-template) for different disposables.
-To prepare an app qube to be a disposable template, you need to set `template_for_dispvms` property, for example:
 
 ```shell_session
-[user@dom0 ~]$ qvm-prefs fedora-26-dvm template_for_dispvms True
+[user@dom0 ~]$ qvm-prefs <DISPOSABLE_TEMPLATE> template_for_dispvms True
 ```
 
-Additionally, if you want to have menu entries for starting applications in disposable based on this app qube (instead of in the app qube itself), you can achieve it with `appmenus-dispvm` feature:
+Additionally, if you want to have menu entries for starting applications in disposables based on this app qube (instead of in the app qube itself), you can achieve that with the `appmenus-dispvm` feature:
 
 ```shell_session
-[user@dom0 ~]$ qvm-features fedora-26-dvm appmenus-dispvm 1
+[user@dom0 ~]$ qvm-features <DISPOSABLE_TEMPLATE> appmenus-dispvm 1
 ```
 
-Note: application shortcuts that existed before setting this feature will not be updated automatically. Please go the the "Applications" tab in the qube's "Settings" dialog and unselect all existing shortcuts by clicking "<<", then click "OK" and close the dialog. Give it a few seconds time and then reopen and re-select all the shortcuts you want to see in the menu. See [this page](/doc/managing-appvm-shortcuts) for background information.
+**Note:** Application shortcuts that existed before setting this feature will not be updated automatically. Please go the the "Applications" tab in the qube's "Settings" dialog and unselect all existing shortcuts by clicking "<<", then click "OK" and close the dialog. Give it a few seconds time and then reopen and re-select all the shortcuts you want to see in the menu. See [this page](/doc/managing-appvm-shortcuts) for background information.
 
 ## Security
 
-If a disposable template becomes compromised, then any disposable based on that disposable template could be compromised.
+If a disposable template becomes compromised, then any disposable based on that disposable template could be compromised. Therefore, you should not make any risky customizations (e.g., installing untrusted browser plugins) in important disposable templates. In particular, the *default* disposable template is important because it is used by the "Open in disposable" feature. This means that it will have access to everything that you open with this feature. For this reason, it is strongly recommended that you base the default disposable template on a trusted template and refrain from making any risky customizations to it.
-Therefore, you should not make any risky customizations (e.g., installing untrusted browser plugins) in important disposable templates.
-In particular, the *default* disposable template is important because it is used by the "Open in disposable" feature.
-This means that it will have access to everything that you open with this feature.
-For this reason, it is strongly recommended that you base the default disposable template on a trusted template and refrain from making any risky customizations to it.
 
 ## Creating a new disposable template
 
-In Qubes 4.0, you're no longer restricted to a single disposable template. Instead, you can create as many as you want. Whenever you start a new disposable, you can choose to base it on whichever disposable template you like.
+In Qubes 4.0, you're no longer restricted to a single disposable template. Instead, you can create as many as you want. Whenever you start a new disposable, you can choose to base it on whichever disposable template you like. To create a new disposable template:
-To create new disposable template, lets say `custom-disposable-template`, based on `debian-9` template, use following commands:
 
 ```shell_session
-[user@dom0 ~]$ qvm-create --template debian-9 --label red custom-disposable-template
+[user@dom0 ~]$ qvm-create --template <TEMPLATE> --label red <DISPOSABLE_TEMPLATE>
-[user@dom0 ~]$ qvm-prefs custom-disposable-template template_for_dispvms True
+[user@dom0 ~]$ qvm-prefs <DISPOSABLE_TEMPLATE> template_for_dispvms True
-[user@dom0 ~]$ qvm-features custom-disposable-template appmenus-dispvm 1
+[user@dom0 ~]$ qvm-features <DISPOSABLE_TEMPLATE> appmenus-dispvm 1
 ```
 
-Additionally you may want to set it as default disposable template:
+Optionally, set it as the default disposable template:
 
 ```shell_session
-[user@dom0 ~]$ qubes-prefs default_dispvm custom-disposable-template
+[user@dom0 ~]$ qubes-prefs default_dispvm <DISPOSABLE_TEMPLATE>
 ```
 
 The above default is used whenever a qube request starting a new disposable and do not specify which one (for example `qvm-open-in-dvm` tool). This can be also set in qube settings and will affect service calls from that qube. See [qrexec documentation](/doc/qrexec/#specifying-vms-tags-types-targets-etc) for details.
 
-If you wish to use a [Minimal Template](/doc/templates/minimal/) as a disposable template, please see the [Minimal Template](/doc/templates/minimal/) page.
+If you wish to use a [minimal template](/doc/templates/minimal/) as a disposable template, please see the [minimal template](/doc/templates/minimal/) page.
 
 ## Customization of disposable
 
 _**Note:** If you are trying to customize Tor Browser in a Whonix disposable, please consult the [Whonix documentation](https://www.whonix.org/wiki/Tor_Browser/Advanced_Users#disposable_Template_Customization)._
 
-It is possible to change the settings for each new disposable.
+It is possible to change the settings for each new disposable. This can be done by customizing the disposable template on which it is based:
-This can be done by customizing the disposable template on which it is based:
 
-1. Start a terminal in the `fedora-26-dvm` qube (or another disposable template) by running the following command in a dom0 terminal. (If you enable `appmenus-dispvm` feature (as explained at the top), applications menu for this VM (`fedora-26-dvm`) will be "Disposable: fedora-26-dvm" (instead of "Domain: fedora-26-dvm") and entries there will start new disposable based on that VM (`fedora-26-dvm`). Not in that VM (`fedora-26-dvm`) itself).
+1. Start a terminal in the `<DISPOSABLE_TEMPLATE>` qube (or another disposable template) by running the following command in a dom0 terminal. (If you enable `appmenus-dispvm` feature (as explained at the top), applications menu for this VM (`<DISPOSABLE_TEMPLATE>`) will be "Disposable: <DISPOSABLE_TEMPLATE>" (instead of "Domain: <DISPOSABLE_TEMPLATE>") and entries there will start new disposable based on that VM (`<DISPOSABLE_TEMPLATE>`). Not in that VM (`<DISPOSABLE_TEMPLATE>`) itself).
 
     ```shell_session
-    [user@dom0 ~]$ qvm-run -a fedora-26-dvm gnome-terminal
+    [user@dom0 ~]$ qvm-run -a <DISPOSABLE_TEMPLATE> gnome-terminal
     ```
 
 2. Change the qube's settings and/or applications, as desired. Some examples of changes you may want to make include:
@@ -78,50 +70,53 @@ This can be done by customizing the disposable template on which it is based:
     - Changing default editor, image viewer. In Debian-based templates this can be done with the `mimeopen` command.
     - Changing the disposable's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new disposable, you can choose your desired ProxyVM manually (by changing the newly-started disposables settings). This is useful if you sometimes wish to use a disposable with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected disposable.
 
-4. Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal).
+3. Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal).
 
-## Using named disposables for sys-*
+## Using named disposables for service qubes
 
-You can use a [named disposable](/doc/glossary/#named-disposable) for `sys-*` as long as it is stateless.
+You can use a [named disposable](/doc/glossary/#named-disposable) for service qubes (such as those with the `sys-*` naming scheme) as long as they are stateless. For example, a `sys-net` using DHCP or `sys-usb` will work. In most cases `sys-firewall` will also work, even if you have configured app qube firewall rules. The only exception is if you require something like VM to VM communication and have manually edited `iptables` or other items directly inside the firewall app qube.
-For example, a `sys-net` using DHCP or `sys-usb` will work.
-In most cases `sys-firewall` will also work, even if you have configured app qube firewall rules.
-The only exception is if you require something like VM to VM communication and have manually edited `iptables` or other items directly inside the firewall app qube.
 
 To create one that has no PCI devices attached, such as for `sys-firewall`:
 
 ~~~
-qvm-create -C DispVM -l green <sys-VMName>
+qvm-create -C DispVM -l green <SERVICE_QUBE>
-qvm-prefs <sys-VMName> autostart true
+qvm-prefs <SERVICE_QUBE> autostart true
-qvm-prefs <sys-VMName> netvm <sys-net>
+qvm-prefs <SERVICE_QUBE> netvm <NET_QUBE>
-qvm-prefs <sys-VMName> provides_network true
+qvm-prefs <SERVICE_QUBE> provides_network true
-qvm-features <sys-VMName> appmenus-dispvm ''
+qvm-features <SERVICE_QUBE> appmenus-dispvm ''
 ~~~
 
-Next, set the old `sys-firewall` autostart to false, and update any references to the old one to instead point to the new.
+Next, set the old `sys-firewall` autostart to false, and update any references to the old one to instead point to the new, for example, with `qvm-prefs work netvm sys-firewall2`.
-For example, with `qvm-prefs work netvm sys-firewall2`.
 
 To create one with a PCI device attached such as for `sys-net` or `sys-usb`, use the additional commands as follows.
 
-**Note** You can use `qvm-pci` to [determine](/doc/how-to-use-pci-devices/#qvm-pci-usage) the `<BDF>`.
+**Note:** You can use `qvm-pci` to [determine](/doc/how-to-use-pci-devices/#qvm-pci-usage) the `<BDF>`. Also, you will often need to include the `-o no-strict-reset=True` [option](/doc/how-to-use-pci-devices/#no-strict-reset) with USB controllers.
-Also, you will often need to include the `-o no-strict-reset=True` [option](/doc/how-to-use-pci-devices/#no-strict-reset) with USB controllers.
 
 ~~~
-qvm-create -C DispVM -l red <sys-VMName>
+qvm-create -C DispVM -l red <SERVICE_QUBE>
-qvm-prefs <sys-VMName> virt_mode hvm
+qvm-prefs <SERVICE_QUBE> virt_mode hvm
-qvm-service <sys-VMName> meminfo-writer off
+qvm-service <SERVICE_QUBE> meminfo-writer off
-qvm-pci attach --persistent <sys-VMName> dom0:<BDF>
+qvm-pci attach --persistent <SERVICE_QUBE> dom0:<BDF>
-qvm-prefs <sys-VMName> autostart true
+qvm-prefs <SERVICE_QUBE> autostart true
-qvm-prefs <sys-VMName> netvm ''
+qvm-prefs <SERVICE_QUBE> netvm ''
-qvm-features <sys-VMName> appmenus-dispvm ''
+qvm-features <SERVICE_QUBE> appmenus-dispvm ''
-# optional, if this disposable will be providing networking
-qvm-prefs <sys-VMName> provides_network true
 ~~~
 
-Next, set the old `sys-` VM's autostart to false, and update any references to the old one.
+Optionally, if this disposable will also provide network access to other qubes:
-In particular, make sure to update `/etc/qubes-rpc/policy/qubes.UpdatesProxy` in dom0.
 
-For example, `qvm-prefs sys-firewall netvm <sys-VMName>`.
+~~~
-See below for a complete example of a `sys-net` replacement:
+qvm-prefs <SERVICE_QUBE> provides_network true
+~~~
+
+Next, set the old service qube's autostart to false, and update any references to the old one, e.g.:
+
+~~~
+qvm-prefs sys-firewall netvm <SERVICE_QUBE>
+~~~
+
+Also make sure to update any [RPC policies](/doc/rpc-policy/), if needed.
+
+Here is an example of a complete `sys-net` replacement:
 
 ~~~
 qvm-create -C DispVM -l red sys-net2
@@ -137,248 +132,38 @@ qvm-prefs sys-firewall netvm sys-net2
 qubes-prefs clockvm sys-net2
 ~~~
 
-## Adding programs to disposable Application Menu
+## Adding programs to the app menu
 
-For added convenience, arbitrary programs can be added to the Application Menu of the disposable. 
+For added convenience, arbitrary programs can be added to the app menu of the disposable. 
 
 In order to do that, select "Qube settings" entry in selected base app qube, go to "Applications" tab and select desired applications as for any other qube.
 
 Note that currently only applications whose main process keeps running until you close the application (i.e. do not start a background process instead) will work. One of known examples of incompatible applications is GNOME Terminal (shown on the list as "Terminal"). Choose different terminal emulator (like XTerm) instead.
 
-## Create Custom sys-net sys-firewall and sys-usb disposables
-
-Users have the option of creating customized disposables for the `sys-net`, `sys-firewall` and `sys-usb` VMs. In this configuration, a fresh VM instance is created each time a disposable is launched. Functionality is near-identical to the default VMs created following a new Qubes’ installation, except the user benefits from a non-persistent filesystem.
-
-Functionality is not limited, users can:
-
-- Set custom firewall rule sets and run Qubes VPN scripts. 
-- Set disposables to autostart at system boot.
-- Attach PCI devices with the `--persistent` option. 
-
-Using disposables in this manner is ideal for untrusted qubes which require persistent PCI devices, such as USB VMs and NetVMs.
-
->_**Note:**_ Users who want customized VPN or firewall rule sets must create a separate disposable template for use by each disposable. If disposable template customization is not needed, then a single disposable template is used as a template for all disposables.
-
-### Create and configure the disposable template on which the disposable will be based
-
-1. Create the disposable template:
-
-    ```shell_session
-    [user@dom0 ~]$ qvm-create --class AppVM --label gray <disposable-Template-Name>
-    ```
-
-2. _(optional)_ In the disposable template, add custom firewall rule sets, Qubes VPN scripts, etc.
-
-    Firewall rules sets and Qubes VPN scripts can be added just like any other VM.   
-    
-3. Set the disposable template as template for disposables:
-
-    ```shell_session
-    [user@dom0 ~]$ qvm-prefs <disposable-Template-Name> template_for_dispvms true
-    ```
-
-### Create the sys-net disposable
-
-1. Create `sys-net` disposable based on the disposable template:
-
-    ```shell_session
-    [user@dom0 ~]$ qvm-create --template <disposable-Template-Name> --class DispVM --label red disp-sys-net
-    ```
-
-2. Set `disp-sys-net` virtualization mode to [hvm](/doc/hvm/):
-
-    ```shell_session
-    [user@dom0 ~]$ qvm-prefs disp-sys-net virt_mode hvm
-    ```
-
-3. Set `disp-sys-net` to provide network for other VMs:
-
-    ```shell_session
-    [user@dom0 ~]$ qvm-prefs disp-sys-net provides_network true
-    ```
-
-4. Set `disp-sys-net` NetVM to none:
-
-    ```shell_session
-    [user@dom0 ~]$ qvm-prefs disp-sys-net netvm ""
-    ```
-
-5. List all available PCI devices to determine the correct _backend:BDF_ address(es) to assign to `disp-sys-net`:
-
-    ```shell_session
-    [user@dom0 ~]$ qvm-pci
-    ```
-
-6. Attach the network PCI device(s) to `disp-sys-net` (finding and assigning PCI devices can be found [here](/doc/how-to-use-pci-devices/):
-
-    ```shell_session
-    [user@dom0 ~]$ qvm-pci attach --persistent disp-sys-net <backend>:<bdf>
-    ```
-
-7. _(recommended)_ Set `disp-sys-net` to start automatically when Qubes boots:
-
-    ```shell_session
-    [user@dom0 ~]$ qvm-prefs disp-sys-net autostart true
-    ```
-
-8. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-net is not itself a disposable template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the disposable template):
-
-    ```shell_session
-    [user@dom0 ~]$ qvm-features disp-sys-net appmenus-dispvm ''
-    ```
-
-9. _(optional)_ Set `disp-sys-net` as the dom0 time source:
-
-    ```shell_session
-    [user@dom0 ~]$ qubes-prefs clockvm disp-sys-net
-    ```
-
-10. _(recommended)_ Allow templates to be updated via `disp-sys-net`. In dom0, edit `/etc/qubes-rpc/policy/qubes.UpdatesProxy` to change the target from `sys-net` to `disp-sys-net`.
-
-### Create the sys-firewall disposable
-
-1. Create `sys-firewall` disposable:
-
-    ```shell_session
-    [user@dom0 ~]$ qvm-create --template <disposable-Template-Name> --class DispVM --label green disp-sys-firewall
-    ```
-
-2. Set `disp-sys-firewall` to provide network for other VMs:
-
-    ```shell_session
-    [user@dom0 ~]$ qvm-prefs disp-sys-firewall provides_network true
-    ```
-
-3. Set `disp-sys-net` as the NetVM for `disp-sys-firewall`:
-
-    ```shell_session
-    [user@dom0 ~]$ qvm-prefs disp-sys-firewall netvm disp-sys-net
-    ```
-
-4. Set `disp-sys-firewall` as NetVM for other app qubes:
-
-    ```shell_session
-    [user@dom0 ~]$ qvm-prefs <vm_name> netvm disp-sys-firewall
-    ```
-
-5. _(recommended)_ Set `disp-sys-firewall` to auto-start when Qubes boots:
-
-    ```shell_session
-    [user@dom0 ~]$ qvm-prefs disp-sys-firewall autostart true
-    ```
-
-6. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-firewall is not itself a disposable template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the disposable template):
-
-    ```shell_session
-    [user@dom0 ~]$ qvm-features disp-sys-firewall appmenus-dispvm ''
-    ```
-
-7. _(optional)_ Set `disp-sys-firewall` as the default NetVM:
-
-    ```shell_session
-    [user@dom0 ~]$ qubes-prefs default_netvm disp-sys-firewall
-    ```
-
-### Create the sys-usb disposable
-
-1. Create the `disp-sys-usb`:
-
-    ```shell_session
-    [user@dom0 ~]$ qvm-create --template <disposable-template-name> --class DispVM --label red disp-sys-usb
-    ```
-
-2. Set the `disp-sys-usb` virtualization mode to hvm:
-
-    ```shell_session
-    [user@dom0 ~]$ qvm-prefs disp-sys-usb virt_mode hvm
-    ```
-
-3. Set `disp-sys-usb` NetVM to none:
-
-    ```shell_session
-    [user@dom0 ~]$ qvm-prefs disp-sys-usb netvm ""
-    ```
-
-4. List all available PCI devices:
-
-    ```shell_session
-    [user@dom0 ~]$ qvm-pci
-    ```
-
-5. Attach the USB controller to the `disp-sys-usb`:
-   >_**Note:**_ Most of the commonly used USB controllers (all Intel integrated controllers) require the `-o no-strict-reset=True` option to be set. Instructions detailing how this option is set can be found [here](/doc/how-to-use-pci-devices/#no-strict-reset).
-
-    ```shell_session
-    [user@dom0 ~]$ qvm-pci attach --persistent disp-sys-usb <backined>:<bdf>
-    ```
-
-6. _(optional)_ Set `disp-sys-usb` to auto-start when Qubes boots:
-
-    ```shell_session
-    [user@dom0 ~]$ qvm-prefs disp-sys-usb autostart true
-    ```
-
-7. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-usb is not itself a disposable template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the disposable template):
-
-    ```shell_session
-    [user@dom0 ~]$ qvm-features disp-sys-usb appmenus-dispvm ''
-    ```
-
-8. Users should now follow instructions on [How to hide USB controllers from dom0](/doc/usb-qubes/#how-to-hide-usb-controllers-from-dom0).
-
-9. At this point, your mouse may not work.
-   Edit the `qubes.InputMouse` policy file in dom0, which is located here:
-
-    ```
-    /etc/qubes-rpc/policy/qubes.InputMouse
-    ```
-
-   Add a line like this to the top of the file:
-
-    ```
-    disp-sys-usb dom0 allow,user=root
-    ```
-
-### Starting the disposables
-
-Prior to starting the new VMs, users should ensure that no other VMs such as the old `sys-net` and `sys-usb` VMs are running. This is because no two VMs can share the same PCI device while both running. It is recommended that users detach the PCI devices from the old VMs without deleting them. This will allow users to reattach the PCI devices if the newly created disposables fail to start. 
-
-Detach PCI device from VM:
-
-```shell_session
-[user@dom0~]$ qvm-pci detach <vm_name> <backend>:<bdf>
-```
-
-### Troubleshooting
-
-If the `disp-sys-usb` does not start, it could be due to a PCI passthrough problem. For more details on this issue along with possible solutions, users can look [here](/doc/pci-troubleshooting/#pci-passthrough-issues).
-
 ## Deleting disposables
 
-While working in a disposable, you may want to open a document in another disposable.
+While working in a disposable, you may want to open a document in another disposable. For this reason, the property `default_dispvm` may be set to the name of your disposable in a number of qubes:
-For this reason, the property `default_dispvm` may be set to the name of your disposable in a number of VMs:
 
 ```shell_session
-[user@dom0 ~]$ qvm-prefs workvm | grep default_dispvm
+[user@dom0 ~]$ qvm-prefs <QUBE> | grep default_dispvm
-default_dispvm        -  custom-disposable-template
+default_dispvm        -  <DISPOSABLE_TEMPLATE>
 ```
 
-This will prevent the deletion of the disposable template. In order to fix this you need to unset the `default_dispvm` property:
+This will prevent the deletion of the disposable template. In order to fix this, you need to unset the `default_dispvm` property:
 
 ```shell_session
-[user@dom0 ~]$ qvm-prefs workvm default_dispvm ""
+[user@dom0 ~]$ qvm-prefs <QUBE> default_dispvm ""
 ```
 
 You can then delete the disposable template:
 
 ```shell_session
-[user@dom0 ~]$ qvm-remove custom-disposable-template
+[user@dom0 ~]$ qvm-remove <DISPOSABLE_TEMPLATE>
 This will completely remove the selected VM(s)
-  custom-disposable-template
+  <DISPOSABLE_TEMPLATE>
 ```
 
-      
+If you still encounter a problem, you may have forgotten to clean an entry. Looking at the system logs will help you:
-If you still encounter the issue, you may have forgot to clean an entry. Looking at the system logs will help you:
 
 ```shell_session
 [user@dom0 ~]$ journalctl | tail

user/advanced-topics/gui-domain.md

@@ -147,7 +147,7 @@ qvm-prefs personal guivm dom0
 You are now able to delete the GUI domain, for example `sys-gui-gpu`:
 
 ```bash
-qvm-remove -y sys-gui-gpu
+qvm-remove -f sys-gui-gpu
 ```
 
 #### General issues

user/advanced-topics/kde.md

@@ -16,7 +16,7 @@ R3.2, however, [XFCE is the new default desktop environment](/doc/releases/3.2/r
 still possible to install KDE by issuing this command in dom0:
 
 ```shell_session
-$ sudo qubes-dom0-update @kde-desktop-qubes
+$ sudo qubes-dom0-update kde-settings-qubes
 ```
 
 You can also change your default login manager (lightdm) to the new KDE default: sddm

user/advanced-topics/salt.md

@@ -193,12 +193,12 @@ $ qubesctl --all state.highstate
 
 You will sometimes find yourself writing repetitive states.
 To solve this, there is the ability to template files or states.
-This is most commonly done with [Jinja](http://jinja.pocoo.org/).
+This is most commonly done with [Jinja](https://palletsprojects.com/p/jinja/).
 Jinja is similar to Python and in many cases behaves in a similar fashion, but
 there are sometimes differences when, for example, you set some variable inside
 a loop: the variable outside will not get changed.
 Instead, to get this behavior, you would use a `do` statement.
-So you should take a look at the [Jinja API documentation](http://jinja.pocoo.org/docs/2.9/templates/).
+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).
@@ -605,6 +605,6 @@ install template and shutdown updateVM:
 - [Salt states](https://docs.saltproject.io/en/latest/ref/states/all/) ([files](https://docs.saltproject.io/en/latest/ref/states/all/salt.states.file.html), [commands](https://docs.saltproject.io/en/latest/ref/states/all/salt.states.cmd.html),
   [packages](https://docs.saltproject.io/en/latest/ref/states/all/salt.states.pkg.html), [ordering](https://docs.saltproject.io/en/latest/ref/states/ordering.html))
 - [Top files](https://docs.saltproject.io/en/latest/ref/states/top.html)
-- [Jinja templates](http://jinja.pocoo.org/)
+- [Jinja templates](https://palletsprojects.com/p/jinja/)
 - [Qubes specific modules](https://github.com/QubesOS/qubes-mgmt-salt-dom0-qvm/blob/master/README.rst)
 - [Formulas for default Qubes VMs](https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/tree/master/qvm)

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

@@ -1,162 +0,0 @@
----
-advanced: true
-lang: en
-layout: doc
-permalink: /doc/custom-install/
-redirect_from:
-- /doc/encryption-config/
-ref: 152
-title: Custom installation
----
-
-In the present context, "custom installation" refers to things like manual partitioning, setting up LVM and RAID, and manual LUKS encryption configuration.
-
-## Installer Defaults
-
-For reference, these are the typical defaults for a single disk with legacy boot:
-
-~~~
-Mount Point: /boot
-Desired Capacity: 1024 MiB
-Device Type: Standard Partition
-File System: ext4
-Name: (none)
-
-Mount Point: /
-Desired Capacity: (your choice)
-Device Type: LVM Thin Provisioning
-Volume Group: qubes_dom0
-File System: ext4
-Name: root
-
-Mount Point: (none)
-Desired Capacity: 10 GiB
-Device Type: LVM
-Volume Group: qubes_dom0
-File System: swap
-Name: swap
-~~~
-
-~~~
-SUMMARY OF CHANGES
-
-Order   Action              Type                    Device              Mount point
-
-1       Destroy Format      Unknown                 Disk (sda)
-2       Create Format       partition table (MSDOS) Disk (sda)
-3       Create Device       partition               sda1 on Disk
-4       Create Format       ext4                    sda1 on Disk        /boot
-5       Create Device       partition               sda2 on Disk
-6       Create Format       LUKS                    sda2 on Disk
-7       Create Device       luks/dm-crypt           luks-sda2
-8       Create Format       physical volume (LVM)   luks-sda2
-9       Create Device       lvmvg                   qubes_dom0
-10      Create Device       lvmthinpool             qubes_dom0-pool00
-11      Create Device       lvmthinlv               qubes_dom0-root
-12      Create Device       lvmlv                   qubes_dom0-swap
-13      Create Format       swap                    qubes_dom0-swap
-14      Create Format       ext4                    qubes_dom0-root     /
-~~~
-
-## Typical Partition Schemes
-
-If you want your partition/LVM scheme to look like the Qubes default but with a few tweaks, follow this example.
-With a single disk, the result should look something like this:
-
-~~~
-NAME                                SIZE    TYPE    MOUNTPOINT
-sda                                         disk
-├──sda1                               1G    part    /boot
-└──sda2                                     part
-   └──luks-<UUID>                           crypt
-      ├──qubes_dom0-pool00_tmeta            lvm
-      ├──qubes_dom0-pool00_tdata            lvm
-      └──qubes_dom0-swap                    lvm     [SWAP]
-~~~
-
-## Encryption Defaults
-
-By default, `cryptsetup 1.7.5` will create a LUKS/dm-crypt volume as follows:
-
-~~~
-Version:            1
-Cipher name:        aes
-Cipher mode:        xts-plain64
-Hash spec:          sha256
-~~~
-
-~~~
-$ cryptsetup --help
-[...]
-Default compiled-in device cipher parameters:
-        loop-AES: aes, Key 256 bits
-        plain: aes-cbc-essiv:sha256, Key: 256 bits, Password hashing: ripdemd160
-        LUKS1: aes-xts-plain64, Key: 256 bits, LUKS header hashing: sha256, RNG: /dev/urandom
-~~~
-
-This means that, by default, Qubes inherits these upstream defaults:
-
-- AES-128 [[1]](https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions)[[2]](https://wiki.archlinux.org/index.php/dm-crypt/Device_encryption)[[3]](https://github.com/dyne/Tomb/issues/238)
-- SHA-256
-- `/dev/urandom`
-- probably an `iter-time` of one second
-
-If, instead, you'd like to use AES-256, SHA-512, `/dev/random`, and a longer `iter-time`, for example, you can configure encryption manually by following the instructions below.
-
-## Example: Custom LUKS Configuration
-
-Boot into the Qubes installer, then press `ctrl`+`alt`+`F2` to get a virtual console.
-
-1. (Optional) Wipe the disk:
-
-    ```
-    # dd if=/dev/zero of=/dev/sda bs=1M status=progress && sync
-    ```
-
-2. Create partitions:
-
-    ```
-    # fdisk /dev/sda
-    ```
-
-   Follow the steps to create two partitions:
-   
-   - ~500MiB-1GiB for `/boot`
-   - The rest for `/` (might want to leave some for overprovisioning if it's an SSD)
-
-4. Create LUKS encrypted volume:
-
-    ```
-    # cryptsetup -v --hash sha512 --cipher aes-xts-plain64 --key-size 512 --use-random --iter-time 10000 --verify-passphrase luksFormat /dev/sda2
-    ```
-
-5. Open encrypted volume:
-
-    ```
-    # cryptsetup open /dev/sda2 luks
-    ```
-
-6. Create LVM volumes:
-
-    ```
-    # pvcreate /dev/mapper/luks
-    # vgcreate qubes_dom0 /dev/mapper/luks
-    # lvcreate -n swap -L 10G qubes_dom0
-    # lvcreate -T -l +100%FREE qubes_dom0/pool00
-    # lvcreate -V1G -T qubes_dom0/pool00 -n root
-    # lvextend -L <size_of_pool00> /dev/qubes_dom0/root
-    ```
-
-8. Proceed with the installer. You can do that either by pressing `ctrl`+`alt`+`F6`, or by rebooting and restarting the installation.
-   At the disk selection screen, select:
-
-    ```
-    [x] I will configure partitioning.
-    [ ] Encrypt my data.
-    ```
-
-9. Decrypt your partition. After decrypting you may assign mount points:
-   Open the Unknown list and select `qubes_dom0-root`. Check the reformat box to the right and choose `ext4` as a filesystem. Enter `/` into the Mount Point field at the top.
-   Repeat the process for `sda1` and `qubes_dom0-swap`. Those should be assigned to `/boot` and `swap` respectively.
-   The default file systems are ext4 for `/boot` and `/`, and swap for `swap`.
-   When you are finished, the Unknown list should go away, and all three mount points should be assigned. Proceed normally with the installation from there.

user/downloading-installing-upgrading/download-mirrors.md

@@ -24,4 +24,4 @@ helpful in streamlining the process.
 * Our preferred frequency is **once every 24 hours**, but anything up to once
   every 6-8 hours is fine.
 * For technical accommodations, please contact [Wojtek](/team/#wojtek-porczyk) or [Marek](/team/#marek-marczykowski-górecki).
-* For website updates and fixes, please contact [Andrew](/team/#andrew-david-wong).
+* For website updates and fixes, please contact [unman](/team/#unman).

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

@@ -18,7 +18,7 @@ No operating system, not even Qubes, can help you if you're installing it on har
 This includes CPUs, GPUs, SSDs, HDDs, the motherboard, BIOS/EFI/UEFI, and all relevant firmware.
 Unfortunately, in today's world of undetectable supply chain attacks, there are no easy solutions.
 (Tools like [Anti Evil Maid (AEM)](/doc/anti-evil-maid/) can help with *maintaining* the trustworthiness of your hardware, but not with establishing it in the first place.)
-Some users have chosen to use tools like [Coreboot](https://www.coreboot.org/), [Heads](http://osresearch.net/), and [Skulls](https://github.com/merge/skulls).
+Some users have chosen to use tools like [Coreboot](https://www.coreboot.org/), [Heads](https://osresearch.net/), and [Skulls](https://github.com/merge/skulls).
 
 ## Verifying the Qubes ISO
 

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

@@ -15,14 +15,13 @@ redirect_from:
 - /doc/InstallationGuideR3.0rc1/
 - /doc/InstallationGuideR3.0rc2/
 - /doc/live-usb/
+- /doc/custom-install/
+- /doc/encryption-config/
 ref: 153
 title: Installation guide
 ---
 
-Welcome to the Qubes OS installation guide! This guide will walk you through
+Welcome to the Qubes OS installation guide! This guide will walk you through the process of installing Qubes. Please read it carefully and thoroughly, as it contains important information for ensuring that your Qubes OS installation is functional and secure.
-the process of installing Qubes. Please read it carefully and thoroughly, as it
-contains important information for ensuring that your Qubes OS installation is
-functional and secure.
 
 ## Pre-installation
 
@@ -30,106 +29,56 @@ functional and secure.
 
 <div class="alert alert-danger" role="alert">
   <i class="fa fa-exclamation-triangle"></i>
-  <b>Warning:</b> Qubes has no control over what happens on your computer
+  <b>Warning:</b> Qubes has no control over what happens on your computer before you install it. No software can provide security if it is installed on compromised hardware. Do not install Qubes on a computer you don't trust. See <a href="/doc/install-security/">installation security</a> for more information.
-  before you install it. No software can provide security if it is installed on
-  compromised hardware. Do not install Qubes on a computer you don't trust.
-  See <a href="/doc/install-security/">installation security</a> for more
-  information.
 </div>
 
-Qubes OS has very specific [system requirements](/doc/system-requirements/). To
+Qubes OS has very specific [system requirements](/doc/system-requirements/). To ensure compatibility, we strongly recommend using [Qubes-certified hardware](/doc/certified-hardware/). Other hardware may require you to perform significant troubleshooting. You may also find it helpful to consult the [Hardware Compatibility List](/hcl/).
-ensure compatibility, we strongly recommend using [Qubes-certified
-hardware](/doc/certified-hardware/). Other hardware may require you to perform
-significant troubleshooting. You may also find it helpful to consult the
-[Hardware Compatibility List](/hcl/).
 
-Even on supported hardware, you must ensure that [IOMMU-based
+Even on supported hardware, you must ensure that [IOMMU-based virtualization](https://en.wikipedia.org/wiki/Input%E2%80%93output_memory_management_unit#Virtualization) is activated in the BIOS or UEFI. Without it, Qubes OS won't be able to enforce isolation. For Intel-based boards, this setting is called Intel Virtualization for Directed I/O (**Intel VT-d**) and for AMD-based boards, it is called  AMD I/O Virtualization Technology (or simply **AMD-Vi**). This parameter should be activated in your computer's BIOS or UEFI, alongside the standard Virtualization (**Intel VT-x**) and AMD Virtualization (**AMD-V**) extensions. This [external guide](https://web.archive.org/web/20200112220913/https://www.intel.in/content/www/in/en/support/articles/000007139/server-products.html) made for Intel-based boards can help you figure out how to enter your BIOS or UEFI to locate and activate those settings. If those settings are not nested under the Advanced tab, you might find them under the Security tab.
-virtualization](https://en.wikipedia.org/wiki/Input%E2%80%93output_memory_management_unit#Virtualization)
-is activated in the BIOS or UEFI. Without it, Qubes OS won't be able to enforce
-isolation. For Intel-based boards, this setting is called Intel Virtualization
-for Directed I/O (**Intel VT-d**) and for AMD-based boards, it is called  AMD
-I/O Virtualization Technology (or simply **AMD-Vi**). This parameter should be
-activated in your computer's BIOS or UEFI, alongside the standard
-Virtualization (**Intel VT-x**) and AMD Virtualization (**AMD-V**) extensions.
-This [external
-guide](https://web.archive.org/web/20200112220913/https://www.intel.in/content/www/in/en/support/articles/000007139/server-products.html)
-made for Intel-based boards can help you figure out how to enter your BIOS or
-UEFI to locate and activate those settings. If those settings are not nested
-under the Advanced tab, you might find them under the Security tab.
 
 <div class="alert alert-warning" role="alert">
   <i class="fa fa-exclamation-circle"></i>
-  <b>Note:</b> Qubes OS is not meant to be installed inside a virtual machine
+  <b>Note:</b> Qubes OS is not meant to be installed inside a virtual machine as a guest hypervisor. In other words, <b>nested virtualization</b> is not supported. In order for a strict compartmentalization to be enforced, Qubes OS needs to be able to manage the hardware directly.
-  as a guest hypervisor. In other words, <b>nested virtualization</b> is not
-  supported. In order for a strict compartmentalization to be enforced, Qubes
-  OS needs to be able to manage the hardware directly.
 </div>
 
 ### Copying the ISO onto the installation medium
 
-Pick the most secure existing computer and OS you have available for
+Pick the most secure existing computer and OS you have available for downloading and copying the Qubes ISO onto the installation medium. [Download](/downloads/) a Qubes ISO.
-downloading and copying the Qubes ISO onto the installation medium.
-[Download](/downloads/) a Qubes ISO.
 
 <div class="alert alert-danger" role="alert">
   <i class="fa fa-exclamation-triangle"></i>
-  <b>Warning:</b> Any file you download from the internet could be malicious,
+  <b>Warning:</b> Any file you download from the internet could be malicious, even if it appears to come from a trustworthy source. Our philosophy is to <a href="/faq/#what-does-it-mean-to-distrust-the-infrastructure">distrust the infrastructure</a>. Regardless of how you acquire your Qubes ISO, <a href="/security/verifying-signatures/">verify its authenticity</a> before continuing.
-  even if it appears to come from a trustworthy source. Our philosophy is to <a
-  href="/faq/#what-does-it-mean-to-distrust-the-infrastructure">distrust the
-  infrastructure</a>. Regardless of how you acquire your Qubes ISO, <a
-  href="/security/verifying-signatures/">verify its authenticity</a> before
-  continuing.
 </div>
 
-Once the ISO has been verified as authentic, you should copy it onto the
+Once the ISO has been verified as authentic, you should copy it onto the installation medium of your choice, such as a USB drive, dual-layer DVD, or Blu-ray disc. The size of each Qubes ISO is available on the [downloads](/downloads/) page by hovering over the download button. The instructions below assume you've chosen a USB drive as your medium. If you've chosen a different medium, please adapt the instructions accordingly.
-installation medium of your choice, such as a USB drive, dual-layer DVD,
-or Blu-ray disc. The size of each Qubes ISO is available on the
-[downloads](/downloads/) page by hovering over the download button. The
-instructions below assume you've chosen a USB drive as your medium. If you've
-chosen a different medium, please adapt the instructions accordingly.
 
 <div class="alert alert-warning" role="alert">
   <i class="fa fa-exclamation-circle"></i>
-  <b>Note:</b> There are important <a href="/doc/install-security/">security
+  <b>Note:</b> There are important <a href="/doc/install-security/">security considerations</a> to keep in mind when choosing an installation medium. Advanced users may wish to <a href="/security/verifying-signatures/#how-to-re-verify-installation-media-after-writing">re-verify their installation media after writing</a>.
-  considerations</a> to keep in mind when choosing an installation medium.
-  Advanced users may wish to <a
-  href="/security/verifying-signatures/#how-to-re-verify-installation-media-after-writing">re-verify
-  their installation media after writing</a>.
 </div>
 
 <div class="alert alert-danger" role="alert">
   <i class="fa fa-exclamation-triangle"></i>
-  <b>Warning:</b> Be careful to choose the correct device when copying the ISO,
+  <b>Warning:</b> Be careful to choose the correct device when copying the ISO, or you may lose data. We strongly recommended making a full backup before modifying any devices.
-  or you may lose data. We strongly recommended making a full backup before
-  modifying any devices.
 </div>
 
 #### Linux ISO to USB
 
-On Linux, if you choose to use a USB drive, copy the ISO onto the USB device,
+On Linux, if you choose to use a USB drive, copy the ISO onto the USB device, e.g. using `dd`:
-e.g. using `dd`:
 
 ```
 $ sudo dd if=Qubes-RX-x86_64.iso of=/dev/sdY status=progress bs=1048576 conv=fsync
 ```
 
-Change `Qubes-RX-x86_64.iso` to the filename of the version you're installing,
+Change `Qubes-RX-x86_64.iso` to the filename of the version you're installing, and change `/dev/sdY` to the correct target device e.g., `/dev/sdc`). Make sure to write to the entire device (e.g., `/dev/sdc`) rather than just a single partition (e.g., `/dev/sdc1`).
-and change `/dev/sdY` to the correct target device e.g., `/dev/sdc`). Make sure
-to write to the entire device (e.g., `/dev/sdc`) rather than just a single
-partition (e.g., `/dev/sdc1`).
 
 #### Windows ISO to USB
 
-On Windows, you can use the [Rufus](https://rufus.akeo.ie/) tool to write the
+On Windows, you can use the [Rufus](https://rufus.akeo.ie/) tool to write the ISO to a USB key. Be sure to select "Write in DD Image mode" *after* selecting the Qubes ISO and pressing "START" on the Rufus main window.
-ISO to a USB key. Be sure to select "Write in DD Image mode" *after* selecting
-the Qubes ISO and pressing "START" on the Rufus main window.
 
 <div class="alert alert-info" role="alert">
   <i class="fa fa-info-circle"></i>
-  <b>Note:</b> Using Rufus to create the installation medium means that you
+  <b>Note:</b> Using Rufus to create the installation medium means that you <a href="https://github.com/QubesOS/qubes-issues/issues/2051">won't be able</a> to choose the "Test this media and install Qubes OS" option mentioned in the example below. Instead, choose the "Install Qubes OS" option.
-  <a href="https://github.com/QubesOS/qubes-issues/issues/2051">won't be able</a>
-  to choose the "Test this media and install Qubes OS" option mentioned in the
-  example below. Instead, choose the "Install Qubes OS" option.
 </div>
 
 [![Rufus menu](/attachment/doc/rufus-menu.png)](/attachment/doc/rufus-menu.png)
@@ -138,37 +87,17 @@ the Qubes ISO and pressing "START" on the Rufus main window.
 
 ## Installation
 
-This section will demonstrate a simple installation using mostly default
+This section will demonstrate a simple installation using mostly default settings.
-settings.
-
-If you are an advanced user, and you would like to customize your installation,
-please see [custom installation](/doc/custom-install/). Otherwise, follow the
-instructions below.
 
 ### Getting to the boot screen
 
-"Booting" is the process of starting your computer. When a computer boots up,
+"Booting" is the process of starting your computer. When a computer boots up, it first runs low-level software before the main operating system. Depending on the computer, this low-level software is may be called the ["BIOS"](https://en.wikipedia.org/wiki/BIOS) or ["UEFI"](https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface).
-it first runs low-level software before the main operating system. Depending on
-the computer, this low-level software is may be called the
-["BIOS"](https://en.wikipedia.org/wiki/BIOS) or
-["UEFI"](https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface).
 
-Since you're installing Qubes OS, you'll need to access your computer's BIOS or
+Since you're installing Qubes OS, you'll need to access your computer's BIOS or UEFI menu so that you can tell it to boot from the USB drive to which you just copied the Qubes installer ISO.
-UEFI menu so that you can tell it to boot from the USB drive to which you just
-copied the Qubes installer ISO.
 
-To begin, power off your computer and plug the USB drive into a USB port, but
+To begin, power off your computer and plug the USB drive into a USB port, but don't press the power button yet. Right after you press the power button, you'll have to immediately press a specific key to enter the BIOS or UEFI menu. The key to press varies from brand to brand. `Esc`, `Del`, and `F10` are common ones. If you're not sure, you can search the web for `<COMPUTER_MODEL> BIOS key` or `<COMPUTER_MODEL> UEFI key` (replacing `<COMPUTER_MODEL>` with your specific computer model) or look it up in your computer's manual.
-don't press the power button yet. Right after you press the power button,
-you'll have to immediately press a specific key to enter the BIOS or UEFI menu.
-The key to press varies from brand to brand. `Esc`, `Del`, and `F10` are common
-ones. If you're not sure, you can search the web for `<COMPUTER_MODEL> BIOS
-key` or `<COMPUTER_MODEL> UEFI key` (replacing `<COMPUTER_MODEL>` with your
-specific computer model) or look it up in your computer's manual.
 
-Once you know the key to press, press your computer's power button, then
+Once you know the key to press, press your computer's power button, then repeatedly press that key until you've entered your computer's BIOS or UEFI menu. To give you and idea of what you should be looking for, we've provided a couple of example photos below.
-repeatedly press that key until you've entered your computer's BIOS or UEFI
-menu. To give you and idea of what you should be looking for, we've provided a
-couple of example photos below.
 
 Here's an example of what the BIOS menu looks like on a ThinkPad T430:
 
@@ -178,39 +107,13 @@ And here's an example of what a UEFI menu looks like:
 
 [![UEFI menu](/attachment/doc/uefi.jpeg)](/attachment/doc/uefi.jpeg)
 
-Once you access your computer's BIOS or UEFI menu, you'll want to go to the
+Once you access your computer's BIOS or UEFI menu, you'll want to go to the "boot menu," which is where you tell your computer which devices to boot from. The goal is to tell the computer to boot from your USB drive so that you can run the Qubes installer. If your boot menu lets you select which device to boot from first, simply select your USB drive. (If you have multiple entries that all look similar to your USB drive, and you're not sure which one is correct, one option is just to try each one until it works.) If, on the other hand, your boot menu presents you with a list of boot devices in order, then you'll want to move your USB drive to the top so that the Qubes installer runs before anything else.
-"boot menu," which is where you tell your computer which devices to boot from.
-The goal is to tell the computer to boot from your USB drive so that you can
-run the Qubes installer. If your boot menu lets you select which device to boot
-from first, simply select your USB drive. (If you have multiple entries that
-all look similar to your USB drive, and you're not sure which one is correct,
-one option is just to try each one until it works.) If, on the other hand, your
-boot menu presents you with a list of boot devices in order, then you'll want
-to move your USB drive to the top so that the Qubes installer runs before
-anything else.
 
-Once you're done on the boot menu, save your changes. How you do this depends
+Once you're done on the boot menu, save your changes. How you do this depends on your BIOS or UEFI, but the instructions should be displayed right there on the screen or in a nearby tab. (If you're not sure whether you've saved your changes correctly, you can always reboot your computer and go back into the boot menu to check whether it still reflects your changes.) Once your BIOS or UEFI is configured the way you want it, reboot your computer. This time, don't press any special keys. Instead, let the BIOS or UEFI load and let your computer boot from your USB drive. If you're successful in this step, after a few seconds you'll be presented with the Qubes installer screen:
-on your BIOS or UEFI, but the instructions should be displayed right there on
-the screen or in a nearby tab. (If you're not sure whether you've saved your
-changes correctly, you can always reboot your computer and go back into the
-boot menu to check whether it still reflects your changes.) Once your BIOS or
-UEFI is configured the way you want it, reboot your computer. This time, don't
-press any special keys. Instead, let the BIOS or UEFI load and let your
-computer boot from your USB drive. If you're successful in this step, after a
-few seconds you'll be presented with the Qubes installer screen:
 
 [![Boot screen](/attachment/doc/boot-screen.png)](/attachment/doc/boot-screen.png)
 
-<div class="alert alert-info" role="alert">
+From here, you can navigate the boot screen using the arrow keys on your keyboard. Pressing the "Tab" key will reveal options. You can choose one of three options:
-  <i class="fa fa-info-circle"></i>
-  <b>Note:</b> When installing Qubes OS 4.0 on UEFI, there is intentionally no
-  boot menu. It goes straight to the installer. The boot menu will be back in
-  Qubes OS 4.1.
-</div>
-
-From here, you can navigate the boot screen using the arrow keys on your
-keyboard. Pressing the "Tab" key will reveal options. You can choose one of
-three options:
 
 * Install Qubes OS
 * Test this media and install Qubes OS
@@ -218,74 +121,51 @@ three options:
  
 Select the option to test this media and install Qubes OS. 
 
-If the boot screen does not appear, there are several options to troubleshoot.
+<div class="alert alert-info" role="alert">
-First, try rebooting your computer. If it still loads your currently installed
+  <i class="fa fa-info-circle"></i>
-operating system or does not detect your installation medium, make sure the
+  <b>Note:</b> If the latest stable release is not compatible with your hardware, you may wish to consider <a href="/doc/testing/">testing a newer release</a>.
-boot order is set up appropriately. The process to change the boot order varies
+</div>
-depending on the currently installed system and the motherboard manufacturer.
+
-If **Windows 10** is installed on your machine, you may need to follow specific
+If the boot screen does not appear, there are several options to troubleshoot. First, try rebooting your computer. If it still loads your currently installed operating system or does not detect your installation medium, make sure the boot order is set up appropriately. The process to change the boot order varies depending on the currently installed system and the motherboard manufacturer. If **Windows 10** is installed on your machine, you may need to follow specific instructions to change the boot order. This may require an [advanced reboot](https://support.microsoft.com/en-us/help/4026206/windows-10-find-safe-mode-and-other-startup-settings).
-instructions to change the boot order. This may require an [advanced
-reboot](https://support.microsoft.com/en-us/help/4026206/windows-10-find-safe-mode-and-other-startup-settings).
 
 ### The installer home screen
 
-On the first screen, you are asked to select the language that will be used
+On the first screen, you are asked to select the language that will be used during the installation process. When you are done, select **Continue**.
-during the installation process. When you are done, select **Continue**.
 
 [![welcome](/attachment/doc/welcome-to-qubes-os-installation-screen.png)](/attachment/doc/welcome-to-qubes-os-installation-screen.png)
 
-Prior to the next screen, a compatibility test runs to check whether
+Prior to the next screen, a compatibility test runs to check whether IOMMU-virtualization is active or not. If the test fails, a window will pop up. 
-IOMMU-virtualization is active or not. If the test fails, a window will pop up. 
 
 [![Unsupported hardware detected](/attachment/doc/unsupported-hardware-detected.png)](/attachment/doc/unsupported-hardware-detected.png)
 
-Do not panic. It may simply indicate that IOMMU-virtualization hasn't been
+Do not panic. It may simply indicate that IOMMU-virtualization hasn't been activated in the BIOS or UEFI. Return to the [hardware requirements](#hardware-requirements) section to learn how to activate it. If the setting is not configured correctly, it means that your hardware won't be able to leverage some Qubes security features, such as a strict isolation of the networking and USB hardware. 
-activated in the BIOS or UEFI. Return to the [hardware
-requirements](#hardware-requirements) section to learn how to activate it. If
-the setting is not configured correctly, it means that your hardware won't be
-able to leverage some Qubes security features, such as a strict isolation of
-the networking and USB hardware. 
 
-If the test passes, you will reach the installation summary screen. The
+If the test passes, you will reach the installation summary screen. The installer loads Xen right at the beginning. If you can see the installer's graphical screen, and you pass the compatibility check that runs immediately afterward, Qubes OS is likely to work on your system!
-installer loads Xen right at the beginning. If you can see the installer's
-graphical screen, and you pass the compatibility check that runs immediately
-afterward, Qubes OS is likely to work on your system!
 
-Like Fedora, Qubes OS uses the Anaconda installer. Those that are familiar with
+Like Fedora, Qubes OS uses the Anaconda installer. Those that are familiar with RPM-based distributions should feel at home. 
-RPM-based distributions should feel at home. 
 
 ### Installation summary
 
 <div class="alert alert-success" role="alert">
   <i class="fa fa-check-circle"></i>
-  <b>Did you know?</b> The Qubes OS installer is completely offline. It doesn't
+  <b>Did you know?</b> The Qubes OS installer is completely offline. It doesn't even load any networking drivers, so there is no possibility of internet-based data leaks or attacks during the installation process.
-  even load any networking drivers, so there is no possibility of
-  internet-based data leaks or attacks during the installation process.
 </div>
 
-The Installation summary screen allows you to change how the system will be
+The Installation summary screen allows you to change how the system will be installed and configured, including localization settings. At minimum, you are required to select the storage device on which Qubes OS will be installed. 
-installed and configured, including localization settings. At minimum, you are
-required to select the storage device on which Qubes OS will be installed. 
 
 [![Installation summary not ready](/attachment/doc/installation-summary-not-ready.png)](/attachment/doc/installation-summary-not-ready.png)
 
 ### Localization
 
-Let's assume you wish to add a German keyboard layout. Go to Keyboard Layout,
+Let's assume you wish to add a German keyboard layout. Go to Keyboard Layout, press the "Plus" symbol, search for "German" as indicated in the screenshot and press "Add". If you want it be your default language, select the "German" entry in the list and press the arrow button. Click on "Done" in the upper left corner, and you're ready to go!
-press the "Plus" symbol, search for "German" as indicated in the screenshot and
-press "Add". If you want it be your default language, select the "German" entry
-in the list and press the arrow button. Click on "Done" in the upper left
-corner, and you're ready to go!
 
 [![Keyboard layout selection](/attachment/doc/keyboard-layout-selection.png)](/attachment/doc/keyboard-layout-selection.png)
 
-The process to select a new language is similar to the process to select a new
+The process to select a new language is similar to the process to select a new keyboard layout. Follow the same process in the "Language Support" entry.
-keyboard layout. Follow the same process in the "Language Support" entry.
 
 [![Language support selection](/attachment/doc/language-support-selection.png)](/attachment/doc/language-support-selection.png)
 
-You can have as many keyboard layout and languages as you want. Post-install,
+You can have as many keyboard layout and languages as you want. Post-install, you will be able to switch between them and install others. 
-you will be able to switch between them and install others. 
 
 Don't forget to select your time and date by clicking on the Time & Date entry.
 
@@ -295,82 +175,49 @@ Don't forget to select your time and date by clicking on the Time & Date entry.
 
 [![Add-ons](/attachment/doc/add-ons.png)](/attachment/doc/add-ons.png)
 
-On the software selection tab, you can choose which software to install in
+On the software selection tab, you can choose which software to install in Qubes OS. Two options are available:
-Qubes OS. Two options are available:
 
-* **Debian:** Select this option if you would like to use
+* **Debian:** Select this option if you would like to use [Debian](/doc/templates/debian/) qubes in addition to the default Fedora qubes.
-  [Debian](/doc/templates/debian/) qubes in addition to the default Fedora
+* **Whonix:** Select this option if you would like to use [Whonix](https://www.whonix.org/wiki/Qubes) qubes. Whonix allows you to use [Tor](https://www.torproject.org/) securely within Qubes.
-  qubes.
-* **Whonix:** Select this option if you would like to use
-  [Whonix](https://www.whonix.org/wiki/Qubes) qubes. Whonix allows you to use
-  [Tor](https://www.torproject.org/) securely within Qubes.
 
-Whonix lets you route some or all of your network traffic through Tor for
+Whonix lets you route some or all of your network traffic through Tor for greater privacy. Depending on your threat model, you may need to install Whonix templates right away.
-greater privacy. Depending on your threat model, you may need to install Whonix
-templates right away.
 
-Regardless of your choices on this screen, you will always be able to install
+Regardless of your choices on this screen, you will always be able to install these and other [templates](/doc/templates/) later. If you're short on disk space, you may wish to deselect these options.
-these and other [templates](/doc/templates/) later. If you're short on disk
-space, you may wish to deselect these options.
 
-By default, Qubes OS comes preinstalled with the lightweight Xfce4 desktop
+By default, Qubes OS comes preinstalled with the lightweight Xfce4 desktop environment. Other desktop environments will be available to you after the installation is completed, though they may not be officially supported (see [advanced topics](/doc/#advanced-topics)).
-environment. Other desktop environments will be available to you after the
-installation is completed, though they may not be officially supported (see
-[Advanced Topics](/doc/#advanced-topics)).
 
 Press **Done** to go back to the installation summary screen.
 
 ### Installation destination
 
-Under the System section, you must choose the installation destination. Select
+Under the System section, you must choose the installation destination. Select the storage device on which you would like to install Qubes OS.
-the storage device on which you would like to install Qubes OS.
 
 <div class="alert alert-danger" role="alert">
   <i class="fa fa-exclamation-triangle"></i>
-  <b>Warning:</b> Be careful to choose the correct installation target, or you
+  <b>Warning:</b> Be careful to choose the correct installation target, or you may lose data. We strongly recommended making a full backup before proceeding.
-  may lose data. We strongly recommended making a full backup before
-  proceeding.
 </div>
 
-Your installation destination can be an internal or external storage drive,
+Your installation destination can be an internal or external storage drive, such as an SSD, HDD, or USB drive. The installation destination must have a least 32 GiB of free space available.
-such as an SSD, HDD, or USB drive. The installation destination must have a
-least 32 GiB of free space available.
 
 <div class="alert alert-warning" role="alert">
   <i class="fa fa-exclamation-circle"></i>
-  <b>Note:</b> The installation destination cannot be the same as the
+  <b>Note:</b> The installation destination cannot be the same as the installation medium. For example, if you're installing Qubes OS <em>from</em> a USB drive <em>onto</em> a USB drive, they must be two distinct USB drives, and they must both be plugged into your computer at the same time. (Note: This may not apply to advanced users who partition their devices appropriately.)
-  installation medium. For example, if you're installing Qubes OS <em>from</em>
-  a USB drive <em>onto</em> a USB drive, they must be two distinct USB drives,
-  and they must both be plugged into your computer at the same time. (Note:
-  This may not apply to advanced users who partition their devices
-  appropriately.)
 </div>
 
-Installing an operating system onto a USB drive can be a convenient way to try
+Installing an operating system onto a USB drive can be a convenient way to try Qubes. However, USB drives are typically much slower than internal SSDs. We recommend a very fast USB 3.0 drive for decent performance. Please note that a minimum storage of 32 GiB is required. If you want to install Qubes OS onto a USB drive, just select the USB device as the target installation device. Bear in mind that the installation process is likely to take longer than it would on an internal storage device.
-Qubes. However, USB drives are typically much slower than internal SSDs. We
-recommend a very fast USB 3.0 drive for decent performance. Please note that a
-minimum storage of 32 GiB is required. If you want to install Qubes OS onto a
-USB drive, just select the USB device as the target installation device. Bear
-in mind that the installation process is likely to take longer than it would on
-an internal storage device.
 
 [![Select storage device](/attachment/doc/select-storage-device.png)](/attachment/doc/select-storage-device.png)
 
 <div class="alert alert-success" role="alert">
   <i class="fa fa-check-circle"></i>
-  <b>Did you know?</b> Qubes OS uses full-disk AES encryption (FDE) via LUKS by
+  <b>Did you know?</b> By default, Qubes OS uses <a href="https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup">LUKS</a>/<a href="https://en.wikipedia.org/wiki/Dm-crypt">dm-crypt</a> to encrypt everything except the <code>/boot</code> partition.
-  default.
 </div>
 
-As soon as you press **Done**, the installer will ask you to enter a passphrase
+As soon as you press **Done**, the installer will ask you to enter a passphrase for disk encryption. The passphrase should be complex. Make sure that your keyboard layout reflects what keyboard you are actually using. When you're finished, press **Done**.
-for disk encryption. The passphrase should be complex. Make sure that your
-keyboard layout reflects what keyboard you are actually using. When you're
-finished, press **Done**.
 
 <div class="alert alert-danger" role="alert">
   <i class="fa fa-exclamation-triangle"></i>
-  <b>Warning:</b> If you forget your encryption passphrase, there is no way to
+  <b>Warning:</b> If you forget your encryption passphrase, there is no way to recover it.
-  recover it.
 </div>
 
 [![Select storage passhprase](/attachment/doc/select-storage-passphrase.png)](/attachment/doc/select-storage-passphrase.png)
@@ -381,27 +228,19 @@ When you're ready, press **Begin Installation**.
 
 ### Create your user account
 
-While the installation process is running, you can create your user account.
+While the installation process is running, you can create your user account. This is what you'll use to log in after disk decryption and when unlocking the screen locker. This is a purely local, offline account in dom0. By design, Qubes OS is a single-user operating system, so this is just for you.
-This is what you'll use to log in after disk decryption and when unlocking the
-screen locker. This is a purely local, offline account in dom0. By design,
-Qubes OS is a single-user operating system, so this is just for you.
 
-Select **User Creation** to define a new user with administrator privileges and
+Select **User Creation** to define a new user with administrator privileges and a password. Just as for the disk encryption, this password should be complex. The root account is deactivated and should remain as such.
-a password. Just as for the disk encryption, this password should be complex.
-The root account is deactivated and should remain as such.
 
 [![Account name and password](/attachment/doc/account-name-and-password.png)](/attachment/doc/account-name-and-password.png)
 
-When the installation is complete, press **Reboot**. Don't forget to remove the
+When the installation is complete, press **Reboot**. Don't forget to remove the installation medium, or else you may end up seeing the installer boot screen again.
-installation medium, or else you may end up seeing the installer boot screen
-again.
 
 ## Post-installation
 
 ### First boot
 
-If the installation was successful, you should now see the GRUB menu during the
+If the installation was successful, you should now see the GRUB menu during the boot process.
-boot process.
 
 [![Grub boot menu](/attachment/doc/grub-boot-menu.png)](/attachment/doc/grub-boot-menu.png)
 
@@ -411,49 +250,27 @@ Just after this screen, you will be asked to enter your encryption passphrase.
 
 ### Initial Setup
 
-You're almost done. Before you can start using Qubes OS, some configuration is
+You're almost done. Before you can start using Qubes OS, some configuration is needed. 
-needed. 
 
 [![Initial setup menu](/attachment/doc/initial-setup-menu.png)](/attachment/doc/initial-setup-menu.png)
 
-By default, the installer will create a number of qubes (depending on the
+By default, the installer will create a number of qubes (depending on the options you selected during the installation process). These are designed to give you a more ready-to-use environment from the get-go.
-options you selected during the installation process). These are designed to
-give you a more ready-to-use environment from the get-go.
 
 [![Initial setup menu configuration](/attachment/doc/initial-setup-menu-configuration.png)](/attachment/doc/initial-setup-menu-configuration.png)
 
 Let's briefly go over the options:
 
-* **Create default system qubes:**
+* **Create default system qubes:** These are the core components of the system, required for things like internet access.
-  These are the core components of the system, required for things like
+* **Create default application qubes:** These are how you compartmentalize your digital life. There's nothing special about the ones the installer creates. They're just suggestions that apply to most people. If you decide you don't want them, you can always delete them later, and you can always create your own.
-  internet access.
+* **Create Whonix Gateway and Workstation qubes:** If you want to use Whonix, you should select this option.
-* **Create default application qubes:**
+  * **Enabling system and template updates over the Tor anonymity network using Whonix:** If you select this option, then whenever you install or update software in dom0 or a template, the internet traffic will go through Tor.
-  These are how you compartmentalize your digital life. There's nothing special
+* **Create USB qube holding all USB controllers:** Just like the network qube for the network stack, the USB qube isolates the USB controllers.
-  about the ones the installer creates. They're just suggestions that apply to
+  * **Use sys-net qube for both networking and USB devices:** You should select this option if you rely on a USB device for network access, such as a USB modem or a USB Wi-Fi adapter.
-  most people. If you decide you don't want them, you can always delete them
+* **Do not configure anything:** This is for very advanced users only. If you select this option, you'll have to set everything up manually afterward.
-  later, and you can always create your own.
-* **Create Whonix Gateway and Workstation qubes:**
-  If you want to use Whonix, you should select this option.
-  * **Enabling system and template updates over the Tor anonymity network using
-  Whonix:**
-  If you select this option, then whenever you install or update software in
-  dom0 or a template, the internet traffic will go through Tor.
-* **Create USB qube holding all USB controllers:**
-  Just like the network qube for the network stack, the USB qube isolates the
-  USB controllers.
-  * **Use sys-net qube for both networking and USB devices:**
-  You should select this option if you rely on a USB device for network access,
-  such as a USB modem or a USB Wi-Fi adapter.
-* **Do not configure anything:**
-  This is for very advanced users only. If you select this option, you'll have
-  to set everything up manually afterward.
 
-When you're satisfied with you choices, press **Done**. This configuration
+When you're satisfied with you choices, press **Done**. This configuration process may take a while, depending on the speed and compatibility of your system.
-process may take a while, depending on the speed and compatibility of your
-system.
 
-After the configuration is done, you will be greeted by the login screen. Enter
+After the configuration is done, you will be greeted by the login screen. Enter your password and log in.
-your password and log in.
 
 [![Login screen](/attachment/doc/login-screen.png)](/attachment/doc/login-screen.png)
 
@@ -465,67 +282,34 @@ Congratulations, you are now ready to use Qubes OS!
 
 ### Updating
 
-Next, [update](/doc/how-to-update/) your installation to ensure you have
+Next, [update](/doc/how-to-update/) your installation to ensure you have the latest security updates. Frequently updating is one of the best ways to remain secure against new threats.
-the latest security updates. Frequently updating is one of the best ways to
-remain secure against new threats.
 
 ### Security
 
-The Qubes OS Project occasionally issues [Qubes Security Bulletins
+The Qubes OS Project occasionally issues [Qubes Security Bulletins (QSBs)](/security/qsb/) as part of the [Qubes Security Pack (qubes-secpack)](/security/pack/). It is important to make sure that you receive all QSBs in a timely manner so that you can take action to keep your system secure. (While [updating](#updating) will handle most security needs, there may be cases in which additional action from you is required.) For this reason, we strongly recommend that every Qubes user subscribe to the [qubes-announce](/support/#qubes-announce) mailing list.
-(QSBs)](/security/qsb/) as part of the [Qubes Security Pack
-(qubes-secpack)](/security/pack/). It is important to make sure that you
-receive all QSBs in a timely manner so that you can take action to keep your
-system secure. (While [updating](#updating) will handle most security needs,
-there may be cases in which additional action from you is required.) For this
-reason, we strongly recommend that every Qubes user subscribe to the
-[qubes-announce](/support/#qubes-announce) mailing list.
 
-In addition to QSBs, the Qubes OS Project also publishes
+In addition to QSBs, the Qubes OS Project also publishes [Canaries](/security/canary/), XSA summaries, template releases and end-of-life notices, and other items of interest to Qubes users. Since these are not essential for all Qubes users to read, they are not sent to [qubes-announce](/support/#qubes-announce) in order to keep the volume on that list low. However, we expect that most users, especially novice users, will find them helpful. If you are interested in these additional items, we encourage you to subscribe to the [Qubes News RSS feed](/feed.xml) or join one of our other [venues](/support/), where these news items are also announced.
-[Canaries](/security/canary/), XSA summaries, template releases and
-end-of-life notices, and other items of interest to Qubes users. Since these
-are not essential for all Qubes users to read, they are not sent to
-[qubes-announce](/support/#qubes-announce) in order to keep the volume on that
-list low. However, we expect that most users, especially novice users, will
-find them helpful. If you are interested in these additional items, we
-encourage you to subscribe to the [Qubes News RSS feed](/feed.xml) or join one
-of our other [venues](/support/), where these news items are also announced.
 
-For more information about Qubes OS Project security, please see the [security
+For more information about Qubes OS Project security, please see the [security center](/security/).
-center](/security/).
 
 ### Backups
 
-It is extremely important to make regular backups so that you don't lose your
+It is extremely important to make regular backups so that you don't lose your data unexpectedly. The [Qubes backup system](/doc/how-to-back-up-restore-and-migrate/) allows you to do this securely and easily.
-data unexpectedly. The [Qubes backup
-system](/doc/how-to-back-up-restore-and-migrate/) allows you to do this
-securely and easily.
 
 ### Submit your HCL report
 
-Consider giving back to the Qubes community and helping other users by
+Consider giving back to the Qubes community and helping other users by [generating and submitting a Hardware Compatibility List (HCL) report](/doc/how-to-use-the-hcl/#generating-and-submitting-new-reports).
-[generating and submitting a Hardware Compatibility List (HCL)
-report](/doc/how-to-use-the-hcl/#generating-and-submitting-new-reports).
 
 ### Get Started
 
-Find out [Getting Started](/doc/getting-started/) with Qubes, check out
+Find out [Getting Started](/doc/getting-started/) with Qubes, check out the other [How-To Guides](/doc/#how-to-guides), and learn about [Templates](/doc/#templates).
-the other [How-To Guides](/doc/#how-to-guides), and learn about
-[Templates](/doc/#templates).
 
 ## Getting help
 
-* We work very hard to make the [documentation](/doc/) accurate, comprehensive
+* We work very hard to make the [documentation](/doc/) accurate, comprehensive useful and user friendly. We urge you to read it! It may very well contain the answers to your questions. (Since the documentation is a community effort, we'd also greatly appreciate your help in [improving](/doc/how-to-edit-the-documentation/) it!)
-  useful and user friendly. We urge you to read it! It may very well contain
-  the answers to your questions. (Since the documentation is a community
-  effort, we'd also greatly appreciate your help in
-  [improving](/doc/how-to-edit-the-documentation/) it!)
 
-* If issues arise during installation, see the [Installation
+* If issues arise during installation, see the [Installation Troubleshooting](/doc/installation-troubleshooting) guide. 
-  Troubleshooting](/doc/installation-troubleshooting) guide. 
 
-* If you don't find your answer in the documentation, please see [Help,
+* If you don't find your answer in the documentation, please see [Help, Support, Mailing Lists, and Forum](/support/) for places to ask.
-  Support, Mailing Lists, and Forum](/support/) for places to ask.
 
-* Please do **not** email individual members of the Qubes team with questions
+* Please do **not** email individual members of the Qubes team with questions about installation or other problems. Instead, please see [Help, Support, Mailing Lists, and Forum](/support/) for appropriate places to ask questions.
-  about installation or other problems. Instead, please see [Help, Support,
-  Mailing Lists, and Forum](/support/) for appropriate places to ask questions.

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

@@ -28,7 +28,8 @@ are available from our [download mirrors](/downloads/#mirrors).
 | Release 3.2 | 2016-09-29 | 2019-03-28 | Unsupported           |
 | Release 4.0 | 2018-03-28 | 2022-08-04 | Unsupported           |
 | Release 4.1 | 2022-02-04 | TBA        | Supported             |
-| Release 4.2 | TBA        | TBA        | [In development](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue+milestone%3A%22Release+4.2%22) |
+| Release 4.2 | TBA        | TBA        | [In testing](https://github.com/QubesOS/qubes-issues/milestone/26) |
+| Release 4.3 | TBA        | TBA        | [In development](https://github.com/QubesOS/qubes-issues/milestone/28) |
 
 ### Note on patch releases
 
@@ -53,6 +54,7 @@ The table below shows the OS used for dom0 in each Qubes OS release.
 | Release 3.2 | Fedora 23 |
 | Release 4.0 | Fedora 25 |
 | Release 4.1 | Fedora 32 |
+| Release 4.2 | Fedora 37 |
 
 ### Note on dom0 and EOL
 
@@ -89,9 +91,10 @@ upstream release on the upstream distribution's website (see [Fedora
 EOL](https://fedoraproject.org/wiki/End_of_life) and [Debian
 Releases](https://wiki.debian.org/DebianReleases)).
 
-| Qubes OS    | Fedora | Debian                                              | Whonix |
+| Qubes OS    | Fedora | Debian | Whonix |
-| ----------- | ------ | --------------------------------------------------- | ------ |
+| ----------- | ------ | ------ | ------ |
-| Release 4.1 | 36     | 10 (Buster), 11 (Bullseye)                          | 16     |
+| Release 4.1 | 37, 38 | 11, 12 | 16     |
+| Release 4.2 | 37, 38 | 11, 12 | 17     |
 
 ### Note on Debian support
 
@@ -105,23 +108,6 @@ chart that illustrates this. Qubes support ends at the *regular* EOL date,
 
 [Whonix](https://www.whonix.org/wiki/Qubes) templates are supported by our
 partner, the [Whonix Project](https://www.whonix.org/). The Whonix Project has
-set its own support policy for Whonix templates in Qubes.
+set its own support policy for Whonix templates in Qubes. Please see the
-
+[Qubes-Whonix version support policy](https://www.whonix.org/wiki/About#Qubes_Hosts)
-This policy requires Whonix template users to stay reasonably close to the
+for details.
-cutting edge by upgrading to new stable releases of Qubes OS and Whonix
-templates within a month of their respective releases. To be precise:
-
-* One month after a new stable version of Qubes OS is released, Whonix
-  templates will no longer be supported on any older release of Qubes OS. This
-  means that users who wish to continue using Whonix templates on Qubes must
-  always upgrade to the latest stable Qubes OS release within one month of its
-  release.
-
-* One month after new stable versions of Whonix templates are released, older
-  releases of Whonix templates will no longer be supported. This means that
-  users who wish to continue using Whonix templates on Qubes must always
-  upgrade to the latest stable Whonix template releases within one month of
-  their release.
-
-We aim to announce both types of events one month in advance in order to remind
-users to upgrade.

user/downloading-installing-upgrading/testing.md

@@ -23,6 +23,9 @@ How to test upcoming Qubes OS releases:
 
 * Use [qubes-builder](/doc/qubes-builder/) to build the latest release.
 * Test the latest release candidate (RC), if one is currently available.
+* 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).)
 * (No support) Experiment with devel alpha ISOs found from time to time at
   [Qubes OpenQA](https://openqa.qubes-os.org/).
 
@@ -78,14 +81,12 @@ How to test [templates](/doc/templates/):
 
 To temporarily enable any of these repos, use the `--enablerepo=<repo-name>`
 option. Example commands:
-
 ```
-sudo qubes-dom0-update --enablerepo=qubes-templates-itl-testing
+qvm-template --enablerepo=qubes-templates-itl-testing list --available
-sudo qubes-dom0-update --enablerepo=qubes-templates-community-testing
+qvm-template --enablerepo=qubes-templates-itl-testing install <template_name>
 ```
-
+To enable any of these repos permanently, change the corresponding `enabled` value to `1` in `/etc/qubes/repo-templates`.  
-To enable or disable any of these repos permanently, change the corresponding
+To disable any of these repos permanently, change the corresponding `enabled` value to `0`.
-`enabled` value to `1` in `/etc/yum.repos.d/qubes-templates.repo`.
 
 ## Providing feedback
 

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

@@ -0,0 +1,107 @@
+---
+lang: en
+layout: doc
+permalink: /doc/upgrade/4.2/
+title: How to upgrade to Qubes 4.2
+---
+
+This page explains how to upgrade from Qubes 4.1 to Qubes 4.2. There are two
+ways to upgrade: a clean installation or an in-place upgrade. In general, a
+clean installation is simpler and less error-prone, but an in-place upgrade
+allows you to preserve your customizations.
+
+## Back up
+
+Before attempting either an in-place upgrade or a clean installation, we
+strongly recommend that you first [back up your
+system](/doc/how-to-back-up-restore-and-migrate/) so that you don't lose any
+data.
+
+## Clean installation
+
+If you would prefer to perform a clean installation rather than upgrading
+in-place:
+
+1. Create a
+   [backup](/doc/how-to-back-up-restore-and-migrate/#creating-a-backup) of your
+   current installation.
+2. [Download](/downloads/) the latest 4.2 release.
+3. Follow the [installation guide](/doc/installation-guide/) to install Qubes
+   4.1.
+4. [Restore from your
+   backup](/doc/how-to-back-up-restore-and-migrate/#restoring-from-a-backup) on
+   your new 4.2 installation.
+
+## In-place upgrade
+
+**Warning:** It is not possible to upgrade directly from releases earlier than
+4.1. If you're still on an earlier release, please either perform a [clean
+installation of 4.2](#clean-installation) or [upgrade to
+4.1](/doc/upgrade/4.1/) first.
+
+The upgrade may take several hours, and will download several gigabytes of
+data.
+
+In place upgrade is a complex operation. For this reason, we provide a
+`qubes-dist-upgrade` tool to handle all the necessary steps automatically. You
+can install it with the following command in the dom0 terminal:
+
+    sudo qubes-dom0-update -y qubes-dist-upgrade
+
+The upgrade consists of five stages --- three before restarting the system ---
+labeled "STAGE 1" through "STAGE 3" in the options list below, and two after restarting the system --- labeled as "STAGE 4" and "STAGE 5" below.
+
+Full list of options can be obtained with `qubes-dist-upgrade --help`:
+
+    Usage: qubes-dist-upgrade [OPTIONS]...
+
+    This script is used for updating current QubesOS R4.1 to R4.2.
+    
+    Options:
+        --update, -t                       (STAGE 1) Update of dom0, TemplatesVM and StandaloneVM.
+        --release-upgrade, -r              (STAGE 2) Update 'qubes-release' for Qubes R4.1.
+        --dist-upgrade, -s                 (STAGE 3) Upgrade to Qubes R4.1 and Fedora 32 repositories.
+        --template-standalone-upgrade, -l  (STAGE 4) Upgrade templates and standalone VMs to R4.1 repository.
+        --finalize, -x                     (STAGE 5) Finalize upgrade. It does:
+                                             - resync applications and features
+                                             - cleanup salt states
+        --all-pre-reboot                   Execute stages 1 do 3
+        --all-post-reboot                  Execute stages 4 and 5
+    
+        --assumeyes, -y                    Automatically answer yes for all questions.
+        --usbvm, -u                        Current UsbVM defined (default 'sys-usb').
+        --netvm, -n                        Current NetVM defined (default 'sys-net').
+        --updatevm, -f                     Current UpdateVM defined (default 'sys-firewall').
+        --skip-template-upgrade, -j        Don't upgrade TemplateVM to R4.2 repositories.
+        --skip-standalone-upgrade, -k      Don't upgrade StandaloneVM to R4.2 repositories.
+        --only-update                      Apply STAGE 4 and resync appmenus only to
+                                           selected qubes (comma separated list).
+        --keep-running                     List of extra VMs to keep running during update (comma separated list).
+                                           Can be useful if multiple updates proxy VMs are configured.
+        --max-concurrency                  How many TemplateVM/StandaloneVM to update in parallel in STAGE 1
+                                           (default 4).
+
+After installing the tool, before-reboot stages can be performed at once with:
+
+    sudo qubes-dist-upgrade --all-pre-reboot
+
+Optionally, an `--assumeyes` (or `-y`) option can be used to automatically
+accept all the actions without confirmation.
+
+Alternatively, each upgrade stage can be started separately (see the list of
+options above).
+
+After completing "STAGE 1" through "STAGE 3", restart the system. Then perform
+the final steps:
+
+    sudo qubes-dist-upgrade --all-post-reboot
+
+After performing those steps, it's recommended to restart the system one last time.
+
+When this completes, you can start using Qubes OS 4.2.
+
+
+## Update
+
+After upgrading or performing a clean installation, we strongly recommend
+[updating your system](/doc/how-to-update/).

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

@@ -19,3 +19,4 @@ see [how to update](/doc/how-to-update/).
 * [Upgrade from 3.1 to 3.2](/doc/upgrade/3.2/)
 * [Upgrade from 3.2 to 4.0](/doc/upgrade/4.0/)
 * [Upgrade from 4.0 to 4.1](/doc/upgrade/4.1/)
+* [Upgrade from 4.1 to 4.2](/doc/upgrade/4.2/)

user/hardware/certified-hardware.md

@@ -10,191 +10,96 @@ ref: 144
 title: Certified hardware
 ---
 
-The Qubes OS Project aims to partner with a select few computer vendors to
+The Qubes OS Project aims to partner with a select few computer vendors to ensure that Qubes users have reliable hardware purchasing options. We aim for these vendors to be as diverse as possible in terms of geography, cost, and availability.
-ensure that Qubes users have reliable hardware purchasing options. We aim for
-these vendors to be as diverse as possible in terms of geography, cost, and
-availability.
 
 <div class="alert alert-danger" role="alert">
   <i class="fa fa-exclamation-triangle"></i>
-  <b>Warning:</b> The Qubes OS Project certifies only that a particular
+  <b>Warning:</b> The Qubes OS Project certifies only that a particular hardware <em>configuration</em> is <em>supported</em> by Qubes OS and is available to purchase with Qubes OS preinstalled. We take no responsibility for any vendor's manufacturing, shipping, payment, or other practices; nor can we control whether physical hardware is modified (whether maliciously or otherwise) <i>en route</i> to the user.
-  hardware <em>configuration</em> is <em>supported</em> by Qubes OS and is
-  available to purchase with Qubes OS preinstalled. We take no responsibility
-  for any vendor's manufacturing, shipping, payment, or other practices; nor
-  can we control whether physical hardware is modified (whether maliciously or
-  otherwise) <i>en route</i> to the user.
 </div>
 
-You may also be interested in the [community-recommended
+You may also be interested in the [community-recommended hardware](https://forum.qubes-os.org/t/5560) list and the [hardware compatibility list (HCL)](/hcl/).
-hardware](https://forum.qubes-os.org/t/5560) list and the [hardware
-compatibility list (HCL)](/hcl/).
 
-## Qubes-certified Laptops
+## Qubes-certified computers
 
-Qubes-certified laptops are certified for a [major
+Qubes-certified computers are certified for a [major release](/doc/version-scheme/) and regularly tested by the Qubes developers to ensure compatibility with all of Qubes' features within that major release. The developers test all new updates within that major release to ensure that no regressions are introduced.
-release](/doc/version-scheme/) and regularly tested by the Qubes developers to
+
-ensure compatibility with all of Qubes' features within that major release. The
+The current Qubes-certified models are listed below in chronological order of certification.
-developers test all new updates within that major release to ensure that no
-regressions are introduced.
 
 ### Insurgo PrivacyBeast X230
 
-[![insurgo-privacybeast-x230.png](/attachment/site/insurgo-privacybeast-x230.png)](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/)
+[![Photo of the Insurgo PrivacyBeast X230](/attachment/site/insurgo-privacybeast-x230.png)](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/)
 
-The [Insurgo PrivacyBeast
+The [Insurgo PrivacyBeast X230](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/) is a laptop based on the ThinkPad X230. It is certified for Qubes OS 4.X. Read our [announcement](/news/2019/07/18/insurgo-privacybeast-qubes-certification/) for details.
-X230](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/)
-meets and exceeds our hardware certification requirements for Qubes 4. Read our
-[announcement](/news/2019/07/18/insurgo-privacybeast-qubes-certification/) of
-the certification for further details!
 
 ### NitroPad X230
 
-[![nitropad-x230.jpg](/attachment/site/nitropad-x230.jpg)](https://shop.nitrokey.com/shop/product/nitropad-x230-67)
+[![Photo of the NitroPad X230](/attachment/site/nitropad-x230.jpg)](https://shop.nitrokey.com/shop/product/nitropad-x230-67)
 
-The [NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67)
+The [NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67) is a laptop based on the ThinkPad X230. It is certified for Qubes OS 4.X. Read our [announcement](/news/2020/03/04/nitropad-x230-qubes-certification/) for details.
-satisfies all hardware certification requirements for Qubes 4, offering users
-extensive hardware security options. Read our
-[announcement](/news/2020/03/04/nitropad-x230-qubes-certification/) of the
-certification for further details!
 
 ### NitroPad T430
 
-[![nitropad-t-430.jpg](/attachment/site/nitropad-t430.jpg)](https://shop.nitrokey.com/shop/product/nitropad-t430-119)
+[![Photo of the NitroPad T430](/attachment/site/nitropad-t430.jpg)](https://shop.nitrokey.com/shop/product/nitropad-t430-119)
 
-The [NitroPad T430](https://shop.nitrokey.com/shop/product/nitropad-t430-119)
+The [NitroPad T430](https://shop.nitrokey.com/shop/product/nitropad-t430-119) is a laptop based on the ThinkPad T430. It is certified for Qubes OS 4.X. Read our [announcement](/news/2021/06/01/nitropad-t430-qubes-certification/) for details.
-satisfies all hardware certification requirements for Qubes 4, offering users
-extensive hardware security options. Read our
-[announcement](/news/2021/06/01/nitropad-t430-qubes-certification/) of the
-certification for further details!
 
+### Dasharo FidelisGuard Z690
 
-## Become Hardware Certified
+[![Photo of the Dasharo FidelisGuard Z690](/attachment/site/dasharo-fidelisguard-z690.jpg)](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
 
-If you are a hardware vendor, you can have your hardware certified as
+The [Dasharo FidelisGuard Z690](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is a desktop based on the MSI PRO Z690-A DDR4 motherboard. It is certified for Qubes OS 4.X. Read our [announcement](/news/2023/03/15/dasharo-fidelisguard-z690-first-qubes-certified-desktop/) for details.
-compatible with Qubes OS. The benefits of hardware certification include:
 
-- Your customers can purchase with confidence, knowing that they can take full
+### NovaCustom NV41 Series
-  advantage of Qubes OS on your hardware for a specific major version.
+
-- We will continue testing your hardware to ensure compatibility with the
+[![Photo of the NovaCustom NV41 Series](/attachment/site/novacustom-nv41-series.png)](https://configurelaptop.eu/nv41-series/)
-  supported major version. In the course of this testing, we will also test
+
-  your hardware against upcoming versions, which can help with future planning.
+The [NovaCustom NV41 Series](https://configurelaptop.eu/nv41-series/) is a 14-inch custom laptop. It is certified for Qubes OS 4.X. Read our [announcement](/news/2023/05/03/novacustom-nv41-series-qubes-certified/) for details.
-- Your hardware will continue to be compatible with Qubes OS as it further
+
-  develops within that major version, and we will work with you toward
+### NitroPC Pro
-  preserving compatibility and certification in future releases.
+
+[![Photo of the NitroPC Pro](/attachment/posts/nitropc-pro.jpg)](https://shop.nitrokey.com/shop/product/nitropc-pro-523)
+
+The [NitroPC Pro](https://shop.nitrokey.com/shop/product/nitropc-pro-523) is a desktop based on the MSI PRO Z690-A DDR5 motherboard. It is certified for Qubes OS 4.X. Read our [announcement](/news/2023/09/06/nitropc-pro-qubes-certified/) for details.
+
+## Become hardware certified
+
+If you are a hardware vendor, you can have your hardware certified as compatible with Qubes OS. The benefits of hardware certification include:
+
+- Your customers can purchase with confidence, knowing that they can take full advantage of Qubes OS on your hardware for a specific major version.
+- We will continue testing your hardware to ensure compatibility with the supported major version. In the course of this testing, we will also test your hardware against upcoming versions, which can help with future planning.
+- Your hardware will continue to be compatible with Qubes OS as it further develops within that major version, and we will work with you toward preserving compatibility and certification in future releases.
 - You can support the development of Qubes OS.
 
-## Hardware Certification Requirements
+## Hardware certification requirements
 
-**Note:** This section describes the requirements for hardware *certification*,
+**Note:** This section describes the requirements for hardware *certification*, *not* the requirements for *running* Qubes OS. For the latter, please see the [system requirements](/doc/system-requirements/). A brief list of the requirements described in this section is available [here](/doc/system-requirements/#qubes-certified-hardware).
-*not* the requirements for *running* Qubes OS. For the latter, please see the
-[system requirements](/doc/system-requirements/). A brief list of the
-requirements described in this section is available
-[here](/doc/system-requirements/#qubes-certified-hardware).
 
-A basic requirement is that all Qubes-certified devices must be be available
+A basic requirement is that all Qubes-certified devices must be be available for purchase with Qubes OS preinstalled. Customers may be offered the option to select from a list of various operating systems (or no operating system at all) to be preinstalled, but Qubes OS must be on that list in order to maintain Qubes hardware certification.
-for purchase with Qubes OS preinstalled. Customers may be offered the option to
-select from a list of various operating systems (or no operating system at all)
-to be preinstalled, but Qubes OS must be on that list in order to maintain
-Qubes hardware certification.
 
-One of the most important security improvements introduced with the release of
+One of the most important security improvements introduced with the release of Qubes 4.0 was to replace paravirtualization (PV) technology with **hardware-enforced memory virtualization**, which recent processors have made possible thanks to so-called Second Level Address Translation ([SLAT](https://en.wikipedia.org/wiki/Second_Level_Address_Translation)), also known as [EPT](https://ark.intel.com/Search/FeatureFilter?productType=processors&ExtendedPageTables=true&MarketSegment=Mobile) in Intel parlance. SLAT (EPT) is an extension to Intel VT-x virtualization, which originally was capable of only CPU virtualization but not memory virtualization and hence required a complex Shadow Page Tables approach. We hope that embracing SLAT-based memory virtualization will allow us to prevent disastrous security bugs, such as the infamous [XSA-148](https://xenbits.xen.org/xsa/advisory-148.html), which --- unlike many other major Xen bugs --- regrettably did [affect](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-022-2015.txt) Qubes OS. Consequently, we require SLAT support of all certified hardware beginning with Qubes OS 4.0.
-Qubes 4.0 was to replace paravirtualization (PV) technology with
-**hardware-enforced memory virtualization**, which recent processors have made
-possible thanks to so-called Second Level Address Translation
-([SLAT](https://en.wikipedia.org/wiki/Second_Level_Address_Translation)), also
-known as
-[EPT](https://ark.intel.com/Search/FeatureFilter?productType=processors&ExtendedPageTables=true&MarketSegment=Mobile)
-in Intel parlance. SLAT (EPT) is an extension to Intel VT-x virtualization,
-which originally was capable of only CPU virtualization but not memory
-virtualization and hence required a complex Shadow Page Tables approach. We
-hope that embracing SLAT-based memory virtualization will allow us to prevent
-disastrous security bugs, such as the infamous
-[XSA-148](https://xenbits.xen.org/xsa/advisory-148.html), which --- unlike many
-other major Xen bugs --- regrettably did
-[affect](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-022-2015.txt)
-Qubes OS. Consequently, we require SLAT support of all certified hardware
-beginning with Qubes OS 4.0.
 
-Another important requirement is that Qubes-certified hardware should run only
+Another important requirement is that Qubes-certified hardware should run only **open-source boot firmware** (aka "the BIOS"), such as [coreboot](https://www.coreboot.org/). The only exception is the use of (properly authenticated) CPU-vendor-provided blobs for silicon and memory initialization (see [Intel FSP](https://firmware.intel.com/learn/fsp/about-intel-fsp)) as well as other internal operations (see [Intel ME](https://www.apress.com/9781430265719)). However, we specifically require all code used for and dealing with the System Management Mode (SMM) to be open-source.
-**open-source boot firmware** (aka "the BIOS"), such as
-[coreboot](https://www.coreboot.org/). The only exception is the use of
-(properly authenticated) CPU-vendor-provided blobs for silicon and memory
-initialization (see [Intel
-FSP](https://firmware.intel.com/learn/fsp/about-intel-fsp)) as well as other
-internal operations (see [Intel ME](https://www.apress.com/9781430265719)).
-However, we specifically require all code used for and dealing with the System
-Management Mode (SMM) to be open-source.
 
-While we
+While we [recognize](https://blog.invisiblethings.org/papers/2015/x86_harmful.pdf) the potential problems that proprietary CPU-vendor code can cause, we are also pragmatic enough to realize that we need to take smaller steps first, before we can implement even stronger countermeasures such as a [stateless laptop](https://blog.invisiblethings.org/papers/2015/state_harmful.pdf). A switch to open source boot firmware is one such important step. To be compatible with Qubes OS, the BIOS must properly expose all the VT-x, VT-d, and SLAT functionality that the underlying hardware offers (and which we require). Among other things, this implies **proper DMAR ACPI table** construction.
-[recognize](https://blog.invisiblethings.org/papers/2015/x86_harmful.pdf) the
-potential problems that proprietary CPU-vendor code can cause, we are also
-pragmatic enough to realize that we need to take smaller steps first, before we
-can implement even stronger countermeasures such as a [stateless
-laptop](https://blog.invisiblethings.org/papers/2015/state_harmful.pdf). A
-switch to open source boot firmware is one such important step. To be
-compatible with Qubes OS, the BIOS must properly expose all the VT-x, VT-d, and
-SLAT functionality that the underlying hardware offers (and which we require).
-Among other things, this implies **proper DMAR ACPI table** construction.
 
-Most laptops use PS/2 connections internally for their input devices (i.e.,
+Most laptops use PS/2 connections internally for their input devices (i.e., keyboard and touchpad). On most desktops, however, USB-connected keyboards and mice have become standard. This presents a dilemma when the computer has only one USB controller. If that single USB controller is dedicated solely to the input devices, then no untrusted USB devices can be used. Conversely, if the sole USB controller is completely untrusted, then there is no way for the user to physically control the system in a secure way. In practice, Qubes users on such hardware systems are generally forced to use a single USB controller for both trusted and untrusted purposes --- [an unfortunate security trade-off](/doc/device-handling-security/#security-warning-on-usb-input-devices). For this reason, we require that every Qubes-certified non-laptop device **either** (1) supports non-USB input devices (e.g., via PS/2) **or** (2) has a separate USB controller that is only for input devices.
-keyboard and touchpad). On most desktops, however, USB-connected keyboards
-and mice have become standard. This presents a dilemma when the computer has
-only one USB controller. If that single USB controller is dedicated solely to
-the input devices, then no untrusted USB devices can be used. Conversely, if
-the sole USB controller is completely untrusted, then there is no way for the
-user to physically control the system in a secure way. In practice, Qubes users
-on such hardware systems are generally forced to use a single USB controller
-for both trusted and untrusted purposes --- [an unfortunate security
-trade-off](/doc/device-handling-security/#security-warning-on-usb-input-devices).
-For this reason, we require that every Qubes-certified non-laptop device
-**either** (1) supports non-USB input devices (e.g., via PS/2) **or** (2) has a
-separate USB controller that is only for input devices.
 
-Finally, we require that Qubes-certified hardware does not have any built-in
+Finally, we require that Qubes-certified hardware does not have any built-in _USB-connected_ microphones (e.g. as part of a USB-connected built-in camera) that cannot be easily physically disabled by the user, e.g. via a convenient mechanical switch. Thankfully, the majority of laptops on the market that we have seen already satisfy this condition out-of-the-box, because their built-in microphones are typically connected to the internal audio device, which itself is a type of PCIe device. This is important, because such PCIe audio devices are --- by default --- assigned to Qubes' (trusted) dom0 and exposed through our carefully designed protocol only to select app qubes when the user explicitly chooses to do so. The rest of the time, they should be outside the reach of malware.
-_USB-connected_ microphones (e.g. as part of a USB-connected built-in camera)
-that cannot be easily physically disabled by the user, e.g. via a convenient
-mechanical switch. Thankfully, the majority of laptops on the market that we
-have seen already satisfy this condition out-of-the-box, because their built-in
-microphones are typically connected to the internal audio device, which itself
-is a type of PCIe device. This is important, because such PCIe audio devices
-are --- by default --- assigned to Qubes' (trusted) dom0 and exposed through
-our carefully designed protocol only to select app qubes when the user
-explicitly chooses to do so. The rest of the time, they should be outside the
-reach of malware.
 
-While we also recommend a physical kill switch on the built-in camera (or, if
+While we also recommend a physical kill switch on the built-in camera (or, if possible, not to have a built-in camera), we also recognize this isn't a critical requirement, because users who are concerned about it can easily cover it a piece of tape (something that, regrettably, is far less effective on a microphone).
-possible, not to have a built-in camera), we also recognize this isn't a
-critical requirement, because users who are concerned about it can easily cover
-it a piece of tape (something that, regrettably, is far less effective on a
-microphone).
 
-Similarly, we don't consider physical kill switches on Wi-Fi and Bluetooth
+Similarly, we don't consider physical kill switches on Wi-Fi and Bluetooth devices to be mandatory. Users who plan on using Qubes in an air-gap scenario would do best if they manually remove all such devices persistently (as well as the builtin [speakers](https://github.com/romanz/amodem/)!), rather than rely on easy-to-flip-by-mistake switches, while others should benefit from the Qubes default sandboxing of all networking devices in dedicated VMs.
-devices to be mandatory. Users who plan on using Qubes in an air-gap scenario
-would do best if they manually remove all such devices persistently (as well as
-the builtin [speakers](https://github.com/romanz/amodem/)!), rather than rely
-on easy-to-flip-by-mistake switches, while others should benefit from the Qubes
-default sandboxing of all networking devices in dedicated VMs.
 
-We hope these hardware requirements will encourage the development of more
+We hope these hardware requirements will encourage the development of more secure and trustworthy devices.
-secure and trustworthy devices.
 
-## Hardware Certification Process
+## Hardware certification process
 
 To have hardware certified, the vendor must:
 
-1. Send the Qubes team two (2) units for testing (non-returnable) for each
+1. Send the Qubes team two (2) units for testing (non-returnable) for each configuration the vendor wishes to be offering.
-   configuration the vendor wishes to be offering.
+2. Offer to customers the very same configuration (same motherboard, same screen, same BIOS version, same Wi-Fi module, etc.) for at least one year.
-2. Offer to customers the very same configuration (same motherboard, same
+3. Pay the Qubes team a flat monthly rate, to be agreed upon between the hardware vendor and the Qubes team.
-   screen, same BIOS version, same Wi-Fi module, etc.) for at least one year.
-3. Pay the Qubes team a flat monthly rate, to be agreed upon between the
-   hardware vendor and the Qubes team.
 
-It is the vendor's responsibility to ensure the hardware they wish to have
+It is the vendor's responsibility to ensure the hardware they wish to have certified can run Qubes OS, at the very least the latest stable version. This could be done by consulting the [Hardware Compatibility List](/hcl/) or trying to install it themselves before shipping any units to us. While we are willing to troubleshoot simple issues, we will need to charge a consulting fee for more in-depth work.
-certified can run Qubes OS, at the very least the latest stable version. This
-could be done by consulting the [Hardware Compatibility List](/hcl/) or trying
-to install it themselves before shipping any units to us. While we are willing
-to troubleshoot simple issues, we will need to charge a consulting fee for more
-in-depth work.
 
-If you are interested in having your hardware certified, please [contact
+If you are interested in having your hardware certified, please [contact us](mailto:business@qubes-os.org).
-us](mailto:business@qubes-os.org).

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

@@ -170,7 +170,7 @@ occur. However, if you do wish to move all files from the dom0 backup out of
 the subdirectory into your current dom0 home directory (overwriting any
 existing files in the process), you may do so by following the instructions
 [here](https://stackoverflow.com/questions/20192070/how-to-move-all-files-including-hidden-files-into-parent-directory-via).
-Just remember that this can cause unexpected and desired configuration changes
+Just remember that this can cause unexpected and undesired configuration changes
 in dom0, depending on exactly which files you're adding and replacing.
 
 ## Emergency backup recovery without qubes

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

@@ -317,7 +317,7 @@ her setup looks like this:
   to these generally doesn't allow spending or withdrawing any money. So, even
   the worst case scenario here wouldn't be catastrophic, unlike with her bank
   and brokerage accounts. Third, she's not too worried about any of her credit
-  card company websites being used to attach each other or her qube (As long as
+  card company websites being used to attack each other or her qube. (As long as
   it's contained to a single qube, she's fine with that level of risk.) Last,
   but not least: She has way too many credit cards! While Carol is very frugal,
   she likes to collect the sign-up bonuses that are offered for opening new
@@ -526,7 +526,7 @@ lessons from our case studies:
   able to actually *use* your computer efficiently to do the things you need to
   do. For example, if you immediately try to jump into doing everything in
   [disposables](/doc/how-to-use-disposables/) and find yourself constantly
-  losing working (e.g., because you forget to transfer it out before the
+  losing work (e.g., because you forget to transfer it out before the
   disposable self-destructs), then that's a big problem! Your extra
   self-imposed security measures are interfering with the very thing they're
   designed to protect. At times like these, take a deep breath and remember

user/how-to-guides/how-to-update.md

@@ -8,27 +8,9 @@ ref: 200
 title: How to update
 ---
 
-*This page is about updating your system while staying on the same [supported
+*This page is about updating your system while staying on the same [supported version of Qubes OS](/doc/supported-releases/#qubes-os). If you're instead looking to upgrade from your current version of Qubes OS to a newer version, see [Upgrade guides](/doc/upgrade/).*
-version of Qubes OS](/doc/supported-releases/#qubes-os). If you're instead
-looking to upgrade from your current version of Qubes OS to a newer version,
-see the [Upgrade Guides](/doc/upgrade/).*
 
-## Security updates
+It is important to keep your Qubes OS system up-to-date to ensure you have the latest security updates, as well as the latest non-security enhancements and bug fixes.
-
-Security updates are an extremely important part of keeping your Qubes
-installation secure. When there is an important security issue, we will issue a
-[Qubes Security Bulletin (QSB)](/security/qsb/) via the [Qubes Security
-Pack (`qubes-secpack`)](/security/pack/). It is very important to read each new
-QSB and follow any user instructions it contains. Most of the time, simply
-[updating your system normally](#routine-updates) will be sufficient to obtain
-security updates. However, in some cases, special action may be required on
-your part, which will be explained in the QSB.
-
-## Routine updates
-
-It is important to keep your Qubes OS system up-to-date to ensure you have the
-latest [security updates](#security-updates), as well as the latest
-non-security enhancements and bug fixes.
 
 Fully updating your Qubes OS system means updating:
 
@@ -36,95 +18,71 @@ Fully updating your Qubes OS system means updating:
 - [templates](/doc/glossary/#template)
 - [standalones](/doc/glossary/#standalone) (if you have any)
 
-You can accomplish this using the **Qubes Update** tool.
+## Security updates
 
-[![Qubes Update](/attachment/doc/r4.0-software-update.png)](/attachment/doc/r4.0-software-update.png)
+Security updates are an extremely important part of keeping your Qubes installation secure. When there is an important security incident, we will issue a [Qubes Security Bulletin (QSB)](/security/qsb/) via the [Qubes Security Pack (`qubes-secpack`)](/security/pack/). It is very important to read each new QSB and follow any user instructions it contains. Most of the time, simply updating your system normally, as described below, will be sufficient to obtain security updates. However, in some cases, special action may be required on your part, which will be explained in the QSB.
 
-By default, the Qubes Update tool will appear as an icon in the Notification
+## Checking for updates
-Area when updates are available.
+
+By default, the **Qubes Update** tool will appear as an icon in the Notification Area when updates are available.
 
 [![Qube Updates Available](/attachment/doc/r4.0-qube-updates-available.png)](/attachment/doc/r4.0-qube-updates-available.png)
 
-However, you can also start the tool manually by selecting it in the
+However, you can also start the tool manually by selecting it in the Applications Menu under "Qubes Tools." Even if no updates have been detected, you can use this tool to check for updates manually at any time by selecting "Enable updates for qubes without known available updates," then selecting all desired items from the list and clicking "Next."
-Applications Menu under "Qubes Tools." Even if no updates have been detected,
-you can use this tool to check for updates manually at any time by selecting
-"Enable updates for qubes without known available updates," then selecting all
-desired items from the list and clicking "Next."
 
 <div class="alert alert-info" role="alert">
   <i class="fa fa-question-circle"></i>
-  For information about how templates download updates, please see <a
+  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>.
-  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>.
 </div>
 
-By default, most qubes that are connected to the internet will periodically
+By default, most qubes that are connected to the internet will periodically check for updates for their parent templates. If updates are available, you will receive a notification as described above. However, if you have any templates that do *not* have any online child qubes, you will *not* receive update notifications for them. Therefore, you should regularly update such templates manually instead.
-check for updates for their parent templates. If updates are available, you
+
-will receive a notification as described above. However, if you have any
+## Installing updates
-templates that do *not* have any online child qubes, you will *not* receive
+
-update notifications for them. Therefore, you should regularly update such
+The standard way to install updates is with the **Qubes Update** tool. (However, you can also perform the same action via the [command-line interface](#command-line-interface).)
-templates manually instead.
+
+[![Qubes Update](/attachment/doc/r4.0-software-update.png)](/attachment/doc/r4.0-software-update.png)
+
+Simply follow the on-screen instructions, and the tool will download and install all available updates for you. Note that if you are downloading updates over Tor (`sys-whonix`), this can take a very long time, especially if there are a lot of updates available.
+
+## Restarting after updating
+
+Certain updates require certain components to be restarted in order for the updates to take effect:
+
+- QSBs may instruct you to restart certain components after installing updates.
+- Dom0 should be restarted after all **Xen** and **kernel** updates.
+- On Intel systems, dom0 should be restarted after all `microcode_ctl` updates.
+- On AMD systems, dom0 should be restarted after all `linux-firmware` updates.
+- After updating a template, first shut down the template, then restart all running qubes based on that template.
+
+## AEM resealing after updating
+
+If you use [Anti Evil Maid (AEM)](/doc/anti-evil-maid/), you'll have to "reseal" after certain updates. It's common for QSBs to contain instructions to this effect. See the relevant QSB and the [AEM `README`](https://github.com/QubesOS/qubes-antievilmaid/blob/main/README) for details.
 
 ## Command-line interface
 
 <div class="alert alert-danger" role="alert">
   <i class="fa fa-exclamation-triangle"></i>
-  <b>Warning:</b> Updating with direct commands such as
+  <b>Warning:</b> Updating with direct commands such as <code>qubes-dom0-update</code>, <code>dnf update</code>, and <code>apt update</code> is <b>not</b> recommended, since these bypass built-in Qubes OS update security measures. Instead, we strongly recommend using the <b>Qubes Update</b> tool or its command-line equivalents, as described below. (By contrast, <a href="/doc/how-to-install-software/">installing</a> packages using direct package manager commands is fine.)
-  <code>qubes-dom0-update</code>, <code>dnf update</code>, and <code>apt
-  update</code> is <b>not</b> recommended, since these bypass built-in Qubes OS
-  update security measures. Instead, we strongly recommend using the <b>Qubes
-  Update</b> tool or its command-line equivalents, as described below. (By
-  contrast, <a href="/doc/how-to-install-software/">installing</a> packages
-  using direct package manager commands is fine.)
 </div>
 
-Advanced users may wish to perform updates via the command-line interface. The
+Advanced users may wish to perform updates via the command-line interface. The recommended way to do this is by applying the following two Salt states. **Applying these two Salt states is the same as updating via the Qubes Update tool.**
-recommended way to do this is by applying the following two Salt states.
-**Applying these two Salt states is the same as updating via the Qubes Update
-tool.**
 
  - [update.qubes-dom0](/doc/salt/#updatequbes-dom0)
  - [update.qubes-vm](/doc/salt/#updatequbes-vm)
 
-In your update qube, a terminal window opens that displays the progress of
+In your update qube, a terminal window opens that displays the progress of operations and output as it is logged. At the end of the process, logs are sent back to dom0. You answer any yes/no prompts in your dom0 terminal window.
-operations and output as it is logged. At the end of the process, logs are sent
-back to dom0. You answer any yes/no prompts in your dom0 terminal window.
 
-Advanced users may also be interested in learning [how to enable the
+Advanced users may also be interested in learning [how to enable the testing repos](/doc/testing/).
-testing repos](/doc/testing/).
 
 ## Upgrading to avoid EOL
 
-The above covers updating *within* a given operating system (OS) release.
+The above covers updating *within* a given operating system (OS) release. Eventually, however, most OS releases will reach **end-of-life (EOL)**, after which point they will no longer be supported. This applies to Qubes OS itself as well as OSes used in [templates](/doc/templates/) (and [standalones](/doc/standalones-and-hvms/), if you have any).
-Eventually, however, most OS releases will reach **end-of-life (EOL)**, after
-which point they will no longer be supported. This applies to Qubes OS itself
-as well as OSes used in [templates](/doc/templates/) (and
-[standalones](/doc/standalones-and-hvms/), if you have any).
 
-**It's very important that you use only supported releases so that you continue
+**It's very important that you use only supported releases so that you continue to receive security updates.** This means that you *must* periodically upgrade Qubes OS and your templates before they reach EOL. You can always see which versions of Qubes OS and select templates are supported on [Supported releases](/doc/supported-releases/).
-to receive security updates.** This means that you *must* periodically upgrade
-Qubes OS and your templates before they reach EOL. You can always see which
-versions of Qubes OS and select templates are supported on the [Supported
-Versions](/doc/supported-releases/) page.
 
-In the case of Qubes OS itself, we will make an
+In the case of Qubes OS itself, we will make an [announcement](/news/categories/#releases) when a supported Qubes OS release is approaching EOL and another when it has actually reached EOL, and we will provide [instructions for upgrading to the next stable supported Qubes OS release](/doc/upgrade/).
-[announcement](/news/categories/#releases) when a supported Qubes OS release is
-approaching EOL and another when it has actually reached EOL, and we will
-provide [instructions for upgrading to the next stable supported Qubes OS
-release](/doc/upgrade/).
 
-Periodic upgrades are also important for templates. For example, you might be
+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)).
-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 [Supported Versions:
-Templates](/doc/supported-releases/#templates)).
 
-The one exception to all this is the specific release used for dom0 (not to be
+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).
-confused with Qubes OS as a whole), which [doesn't have to be
-upgraded](/doc/supported-releases/#note-on-dom0-and-eol).

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

@@ -14,14 +14,9 @@ ref: 203
 title: How to use disposables
 ---
 
-A [disposable](/doc/glossary/#disposable) is a lightweight [qube](/doc/glossary/#qube) that can be created quickly and will self-destruct when closed.
+A [disposable](/doc/glossary/#disposable) is a lightweight [qube](/doc/glossary/#qube) that can be created quickly and will self-destruct when closed. Disposables are usually created in order to host a single application, like a viewer, editor, or web browser.
-Disposables are usually created in order to host a single application, like a viewer, editor, or web browser.
 
-From inside an app qube, choosing the `Open in disposable` option on a file will launch a disposable for just that file.
+From inside an app qube, choosing the `Open in disposable` option on a file will launch a disposable for just that file. Changes made to a file opened in a disposable are passed back to the originating qube. This means that you can safely work with untrusted files without risk of compromising your other qubes. Disposables can be launched either directly from dom0's app menu or terminal window, or from within app qubes. Disposables are generated with names like `disp####`, where `####` is random number.
-Changes made to a file opened in a disposable are passed back to the originating VM.
-This means that you can safely work with untrusted files without risk of compromising your other VMs.
-Disposables can be launched either directly from dom0's Start Menu or terminal window, or from within app qubes.
-While running, disposables will appear in Qubes VM Manager with the name `disp####`.
 
 [![disposablevm-example.png](/attachment/doc/disposablevm-example.png)](/attachment/doc/disposablevm-example.png)
 
@@ -29,89 +24,66 @@ This diagram provides a general example of how disposables can be used to safely
 
 ## Security
 
-If a [disposable template](/doc/glossary/#disposable-template) becomes compromised, then any disposable based on that disposable template could be compromised.
+If a [disposable template](/doc/glossary/#disposable-template) becomes compromised, then any disposable based on that disposable template could be compromised. In particular, the *default* disposable template is important because it is used by the "Open in disposable" feature. This means that it will have access to everything that you open with this feature. For this reason, it is strongly recommended that you base the default disposable template on a trusted template.
-In particular, the *default* disposable template is important because it is used by the "Open in disposable" feature.
-This means that it will have access to everything that you open with this feature.
-For this reason, it is strongly recommended that you base the default disposable template on a trusted template.
 
 ### Disposables and Local Forensics
 
-At this time, disposables should not be relied upon to circumvent local forensics, as they do not run entirely in RAM.
+At this time, disposables should not be relied upon to circumvent local forensics, as they do not run entirely in RAM. For details, see [this thread](https://groups.google.com/d/topic/qubes-devel/QwL5PjqPs-4/discussion).
-For details, see [this thread](https://groups.google.com/d/topic/qubes-devel/QwL5PjqPs-4/discussion).
 
 When it is essential to avoid leaving any trace, consider using [Tails](https://tails.boum.org/).
 
 ## Disposables and Networking
 
-Similarly to how app qubes are based on their underlying [template](/doc/glossary/#template), disposables are based on their underlying [disposable template](/doc/glossary/#disposable-template).
+Similarly to how app qubes are based on their underlying [template](/doc/glossary/#template), disposables are based on their underlying [disposable template](/doc/glossary/#disposable-template). R4.0 introduces the concept of multiple disposable templates, whereas R3.2 was limited to only one.
-R4.0 introduces the concept of multiple disposable templates, whereas R3.2 was limited to only one.
 
-On a fresh installation of Qubes, the default disposable template is called `fedora-XX-dvm` (where `XX` is the Fedora version of the default template).
+On a fresh installation of Qubes, the default disposable template is called `fedora-X-dvm` or `debian-X-dvm` (where `X` is a release number). If you have included the Whonix option in your install, there will also be a `whonix-ws-dvm` disposable template available for your use.
-If you have included the Whonix option in your install, there will also be a `whonix-ws-dvm` disposable template available for your use.
 
 You can set any app qube to have the ability to act as a disposable template with:
 
 ```
-qvm-prefs <vmname> template_for_dispvms True
+qvm-prefs <APP_QUBE> template_for_dispvms True
 ```
 
-The default system wide disposable template can be changed with `qubes-prefs default_dispvm`.
+The default system wide disposable template can be changed with `qubes-prefs default_dispvm`. By combining the two, choosing `Open in disposable` from inside an app qube will open the document in a disposable based on the default disposable template you specified.
-By combining the two, choosing `Open in disposable` from inside an app qube will open the document in a disposable based on the default disposable template you specified.
 
-You can change this behaviour for individual VMs: in the Application Menu, open Qube Settings for the VM in question and go to the "Advanced" tab.
+You can change this behavior for individual qubes: in the Application Menu, open Qube Settings for the qube in question and go to the "Advanced" tab. Here you can edit the "Default disposable" setting to specify which disposable template will be used to launch disposables from that qube. This can also be changed from the command line with:
-Here you can edit the "Default disposable" setting to specify which disposable template will be used to launch disposables from that VM.
-This can also be changed from the command line with:
 
 ```
-qvm-prefs <VM> default_dispvm <DISPOSABLEVM_TEMPLATE>
+qvm-prefs <QUBE> default_dispvm <DISPOSABLE_TEMPLATE>
 ```
 
-For example, `anon-whonix` has been set to use `whonix-ws-dvm` as its `default_dispvm`, instead of the system default.
+For example, `anon-whonix` has been set to use `whonix-ws-dvm` as its `default_dispvm`, instead of the system default. You can even set an app qube that has also been configured as a disposable template to use itself, so disposables launched from within the app qube/disposable template would inherit the same settings.
-You can even set an app qube that has also been configured as a disposable template to use itself, so disposables launched from within the app qube/disposable template would inherit the same settings.
 
-NetVM and firewall rules for disposable templates can be set as they can for a normal VM.
+Network and firewall settings for disposable templates can be set as they can for a normal qube. By default a disposable will inherit the network and firewall settings of the disposable template on which it is based. This is a change in behavior from R3.2, where disposables would inherit the settings of the app qube from which they were launched. Therefore, launching a disposable from an app qube will result in it using the network/firewall settings of the disposable template on which it is based. For example, if an app qube uses sys-net as its net qube, but the default system disposable uses sys-whonix, any disposable launched from this app qube will have sys-whonix as its net qube.
-By default a disposable will inherit the NetVM and firewall settings of the disposable template on which it is based.
-This is a change in behaviour from R3.2, where disposables would inherit the settings of the app qube from which they were launched.
-Therefore, launching a disposable from an app qube will result in it using the network/firewall settings of the disposable template on which it is based.
-For example, if an app qube uses sys-net as its NetVM, but the default system disposable uses sys-whonix, any disposable launched from this app qube will have sys-whonix as its NetVM.
 
-**Warning:** The opposite is also true.
+**Warning:** The opposite is also true. This means if you have changed `anon-whonix`'s `default_dispvm` to use the system default, and the system default disposable uses sys-net, launching a disposable from inside `anon-whonix` will result in the disposable using `sys-net`.
-This means if you have changed anon-whonix's `default_dispvm` to use the system default, and the system default disposable uses sys-net, launching a disposable from inside anon-whonix will result in the disposable using sys-net.
 
-A disposable launched from the Start Menu inherits the NetVM and firewall settings of the disposable template on which it is based.
+A disposable launched from the app menu inherits the net qube and firewall settings of the disposable template on which it is based. Note that changing the net qube setting for the system default disposable template *does* affect the net qube of disposables launched from the app menu. Different disposable templates with individual net qube settings can be added to the app menu.
-Note that changing the "NetVM" setting for the system default disposable template *does* affect the NetVM of disposables launched from the Start Menu.
-Different disposable templates with individual NetVM settings can be added to the Start Menu.
 
-**Important Notes:**
+**Important Notes:** Some disposable templates will automatically create a menu item to launch a disposable. If you do not see an entry and want to add one, please use the command:
-Some disposable templates will automatically create a menu item to launch a disposable, if you do not see an entry and want to add one please use the command:
 
 ```
-qvm-features <DISPOSABLE> appmenus-dispvm 1
+qvm-features <DISPOSABLE_TEMPLATE> appmenus-dispvm 1
 ```
 
-To launch a disposable template from the command line, in dom0 please type the following:
+To launch a disposable template from the command line, execute the following command in dom0:
 
 ```
-qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --service qubes.StartApp+NameOfApp
+qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --service qubes.StartApp+<APPLICATION>
 ```
 
 ## Opening a file in a disposable via GUI
 
-In an app qube's file manager, right click on the file you wish to open in a disposable, then choose "View in disposable" or "Edit in disposable".
+In an app qube's file manager, right click on the file you wish to open in a disposable, then choose "View in disposable" or "Edit in disposable". Wait a few seconds and the default application for this file type should appear displaying the file content. This app is running in its own dedicated qube -- a disposable created for the purpose of viewing or editing this very file. Once you close the viewing application the whole disposable will be destroyed. If you have edited the file and saved the changes, the changed file will be saved back to the original app qube, overwriting the original.
-Wait a few seconds and the default application for this file type should appear displaying the file content.
-This app is running in its own dedicated VM -- a disposable created for the purpose of viewing or editing this very file.
-Once you close the viewing application the whole disposable will be destroyed.
-If you have edited the file and saved the changes, the changed file will be saved back to the original app qube, overwriting the original.
 
-![r4.0-open-in-dispvm-1.png](/attachment/doc/r4.0-open-in-dispvm-1.png) ![r4.0-open-in-dispvm-2.png](/attachment/doc/r4.0-open-in-dispvm-2.png)
+![r4.0-open-in-dispvm-1.png](/attachment/doc/r4.0-open-in-dispvm-1.png)
+
+![r4.0-open-in-dispvm-2.png](/attachment/doc/r4.0-open-in-dispvm-2.png)
 
 
 ## Opening a fresh web browser instance in a new disposable
 
-Sometimes it is desirable to open an instance of Firefox within a new fresh disposable.
+Sometimes it is desirable to open an instance of Firefox within a new fresh disposable. This can be done easily using the app menu: just go to **Application Menu -> Disposable -> Disposable: Firefox web browser**. Wait a few seconds until a web browser starts. Once you close the viewing application the whole disposable will be destroyed.
-This can be done easily using the Start Menu: just go to **Application Menu -\> Disposable -\> Disposable:Firefox web browser**.
-Wait a few seconds until a web browser starts.
-Once you close the viewing application the whole disposable will be destroyed.
 
 ![r4.0-open-in-dispvm-3.png](/attachment/doc/r4.0-open-in-dispvm-3.png)
 
@@ -140,10 +112,7 @@ This will _not_ override the internal handling of PDF documents in Web browsers.
 
 ## Starting an arbitrary program in a disposable from an app qube
 
-Sometimes it can be useful to start an arbitrary program in a disposable.
+Sometimes it can be useful to start an arbitrary program in a disposable. The disposable will stay running so long as the process which started the disposable has not exited. Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details [here](https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009)). Starting an arbitrary program can be done from an app qube by running
-The disposable will stay running so long as the process which started the disposable has not exited.
-Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details [here](https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009)).
-Starting an arbitrary program can be done from an app qube by running
 
 ~~~
 [user@vault ~]$ qvm-run '@dispvm' xterm
@@ -153,24 +122,17 @@ The created disposable can be accessed via other tools (such as `qvm-copy-to-vm`
 
 ## Starting an arbitrary application in a disposable via command line from dom0
 
-The Application Launcher has shortcuts for opening a terminal and a web browser in dedicated disposables, since these are very common tasks.
+The Application Launcher has shortcuts for opening a terminal and a web browser in dedicated disposables, since these are very common tasks. The disposable will stay running so long as the process which started the disposable has not exited. Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details [here](https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009)). It is possible to start an arbitrary application in a disposable directly from dom0 by running:
-The disposable will stay running so long as the process which started the disposable has not exited.
-Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details [here](https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009)).
-It is possible to start an arbitrary application in a disposable directly from dom0 by running:
 
 ~~~
 $ qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --service qubes.StartApp+xterm
 ~~~
 
-The label color will be inherited from `<DISPOSABLE_TEMPLATE>`.
+The label color will be inherited from `<DISPOSABLE_TEMPLATE>`. (The disposable Application Launcher shortcut used for starting programs runs a very similar command to the one above.)
-(The disposable Application Launcher shortcut used for starting programs runs a very similar command to the one above.)
 
 ### Opening a link in a disposable based on a non-default disposable template from a qube
 
-Suppose that the default disposable template for your `email` qube has no networking (e.g., so that untrusted attachments can't phone home).
+Suppose that the default disposable template for your `email` qube has no networking (e.g., so that untrusted attachments can't phone home). However, sometimes you want to open email links in disposables. Obviously, you can't use the default disposable template, since it has no networking, so you need to be able to specify a different disposable template. You can do that with this command from the `email` qube (as long as your RPC policies allow it):
-However, sometimes you want to open email links in disposables.
-Obviously, you can't use the default disposable template, since it has no networking, so you need to be able to specify a different disposable template.
-You can do that with this command from the `email` qube (as long as your RPC policies allow it):
 
 ~~~
 $ qvm-open-in-vm @dispvm:<ONLINE_DISPOSABLE_TEMPLATE> https://www.qubes-os.org
@@ -187,16 +149,14 @@ In dom0, add the following line at the beginning of the file `/etc/qubes-rpc/pol
 ~~~
 
 This line means:
-- FROM: Any VM
+- FROM: Any qube
 - TO: A disposable based on `<ONLINE_DISPOSABLE_TEMPLATE>`
 - WHAT: Allow sending an "Open URL" request
 
-In other words, any VM will be allowed to create a new disposable based on `<ONLINE_DISPOSABLE_TEMPLATE>` and open a URL inside of that disposable.
+In other words, any qube will be allowed to create a new disposable based on `<ONLINE_DISPOSABLE_TEMPLATE>` and open a URL inside of that disposable.
 
 More information about RPC policies for disposables can be found [here](/doc/qrexec/#qubes-rpc-administration).
 
 ## Customizing disposables
 
-You can change the template used to generate the disposables, and change settings used in the disposable savefile.
+You can change the template used to generate the disposables, and change settings used in the disposable savefile. These changes will be reflected in every new disposable based on that template. Full instructions can be found [here](/doc/disposable-customization/).
-These changes will be reflected in every new disposable based on that template.
-Full instructions can be found [here](/doc/disposable-customization/).

user/reference/glossary.md

@@ -141,11 +141,12 @@ still be called "qubes."
 
 * **Important:** The term "qube" is a common noun and should follow the
   capitalization rules of common nouns. For example, "I have three qubes" is
-  correct," while "I have three Qubes" is incorrect.
+  correct, while "I have three Qubes" is incorrect.
 
 * Note that starting a sentence with the plural of "qube" (i.e., "Qubes...")
   can be ambiguous, since it may not be clear whether the referent is a
-  plurality of qubes or [Qubes OS](#qubes-os).
+  plurality of qubes or [Qubes OS](#qubes-os). You may wish to rephrase
+  sentences in order to avoid this ambiguity.
 
 * Example usage: "In Qubes OS, you do your banking in your 'banking' qube and
   your web surfing in your 'untrusted' qube. That way, if your 'untrusted' qube

user/security-in-qubes/u2f-proxy.md

@@ -99,10 +99,10 @@ If you are using Qubes 4.0, you can further compartmentalise your U2F keys by re
 For example, you could make it so that your `twitter` qube (and, therefore, all web browsers in your `twitter` qube) can access only the key on your U2F token for `https://twitter.com`, regardless of whether any of the web browsers in your `twitter` qube or the `twitter` qube itself are compromised.
 If your `twitter` qube makes an authentication request for your bank website, it will be denied at the Qubes policy level.
 
-To enable this, create a file in dom0 named `/etc/qubes-rpc/policy/policy.RegisterArgument+u2f.Authenticate` with the following content:
+To enable this, create a file in dom0 named `/etc/qubes/policy.d/30-user-u2fproxy.policy` with the following content:
 
 ```
-sys-usb @anyvm allow,target=dom0
+policy.RegisterArgument +u2f.Authenticate sys-usb @anyvm allow target=dom0
 ```
 
 Next, empty the contents of `/etc/qubes-rpc/policy/u2f.Authenticate` so that it is a blank file.
@@ -124,7 +124,7 @@ systemctl disable qubes-u2fproxy@sys-usb.service
 
 Replace `USB_QUBE` with the actual USB qube name.
 
-Do not forget to change the sys-usb qube name in the policy `/etc/qubes-rpc/policy/u2f.Authenticate`.
+Do not forget to change the sys-usb qube name in the policy `/etc/qubes/policy.d/30-user-u2fproxy.policy`.
 
 ## Template and browser support
 

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

@@ -103,87 +103,15 @@ Below is a complete list of configuration made according to the above statement,
 Replacing passwordless root access with Dom0 user prompt
 --------------------------------------------------------
 
-While ITL supports the statement above, some Qubes users may wish to enable user/root isolation in VMs anyway.
+While the Qubes developers support the statement above, some Qubes users may wish to enable user/root isolation in VMs anyway.
-We do not support it in any of our packages, but of course nothing is preventing the user from modifying his or her own system.
+We do not support this in any of our packages, but of course nothing is preventing a user from modifying his or her own system.
-A list of steps to do so is provided here **without any guarantee of safety, accuracy, or completeness.
+A list of steps to do so is provided in the [Qubes community guide, Replacing passwordless root with a dom0 prompt
+](https://forum.qubes-os.org/t/replacing-passwordless-root-with-a-dom0-prompt/19074) **without any guarantee of safety, accuracy, or completeness.
 Proceed at your own risk.
 Do not rely on this for extra security.**
 
-1. Adding Dom0 "VMAuth" service:
-
-    ```
-    [root@dom0 /]# echo "/usr/bin/echo 1" >/etc/qubes-rpc/qubes.VMAuth
-    [root@dom0 /]# echo "@anyvm dom0 ask,default_target=dom0" \
-    >/etc/qubes-rpc/policy/qubes.VMAuth
-    [root@dom0 /]# chmod +x /etc/qubes-rpc/qubes.VMAuth
-    ```
-
-   (Note: any VMs you would like still to have passwordless root access (e.g. Templates) can be specified in the second file with "\<vmname\> dom0 allow")
-
-2. Configuring Fedora template to prompt Dom0 for any authorization request:
-    - In `/etc/pam.d/system-auth`, replace all lines beginning with "auth" with these lines:
-
-        ```
-        auth  [success=1 default=ignore]  pam_exec.so seteuid /usr/lib/qubes/qrexec-client-vm dom0 qubes.VMAuth /bin/grep -q ^1$
-        auth  requisite  pam_deny.so
-        auth  required   pam_permit.so
-        ```
-
-    - Require authentication for sudo.
-      Replace the first line of `/etc/sudoers.d/qubes` with:
-
-        ```
-        user ALL=(ALL) ALL
-        ```
-
-    - Disable PolKit's default-allow behavior:
-
-        ```
-        [root@fedora-20-x64]# rm /etc/polkit-1/rules.d/00-qubes-allow-all.rules
-        [root@fedora-20-x64]# rm /etc/polkit-1/localauthority/50-local.d/qubes-allow-all.pkla
-        ```
-
-3. Configuring Debian/Whonix template to prompt Dom0 for any authorization request:
-    - In `/etc/pam.d/common-auth`, replace all lines beginning with "auth" with these lines:
-
-        ```
-        auth  [success=1 default=ignore]  pam_exec.so seteuid /usr/lib/qubes/qrexec-client-vm dom0 qubes.VMAuth /bin/grep -q ^1$
-        auth  requisite  pam_deny.so
-        auth  required   pam_permit.so
-        ```
-
-    - Require authentication for sudo.
-      Replace the first line of `/etc/sudoers.d/qubes` with:
-
-        ```
-        user ALL=(ALL) ALL
-        ```
-
-    - Disable PolKit's default-allow behavior:
-
-        ```
-        [root@debian-8]# rm /etc/polkit-1/rules.d/00-qubes-allow-all.rules
-        [root@debian-8]# rm /etc/polkit-1/localauthority/50-local.d/qubes-allow-all.pkla
-        ```
-
-    - In `/etc/pam.d/su.qubes`, comment out this line near the bottom of the file:
-
-        ```
-        auth sufficient pam_permit.so
-        ```
-
-    - For Whonix, if prompts appear during boot, create `/etc/sudoers.d/zz99` and add these lines:
-
-        ```
-        ALL ALL=NOPASSWD: /usr/sbin/virt-what
-        ALL ALL=NOPASSWD: /usr/sbin/service whonixcheck restart
-        ALL ALL=NOPASSWD: /usr/sbin/service whonixcheck start
-        ALL ALL=NOPASSWD: /usr/sbin/service whonixcheck stop
-        ALL ALL=NOPASSWD: /usr/sbin/service whonixcheck status
-        ```
-
 Dom0 passwordless root access
 -----------------------------
 
 There is also passwordless user->root access in dom0.
-As stated in comment in sudo configuration there (different one than VMs one), there is really no point in user/root isolation, because all the user data (and VM management interface) is already accessible from dom0 user level, so there is nothing more to get from dom0 root account.
+As stated in the comment in sudo configuration there (which is different from the one in individual qubes), there is really no point in user/root isolation, because all the user data (and VM management interface) is already accessible from dom0 user level, so there is nothing more to get from dom0 root account.

user/templates/minimal-templates.md

@@ -25,9 +25,13 @@ templates, along with some examples of common use cases.
 ## Important
 
 1. [The minimal templates are intended only for advanced
-   users.](https://forum.qubes-os.org/t/9717/15) If you encounter problems with
+   users.](https://forum.qubes-os.org/t/9717/15) Most things will *not* work
-   the minimal templates, we recommend that you use their standard template
+   out-of-the-box, and you *will* have to fix them yourself. If you are not
-   counterparts instead.
+   prepared to do a lot of reading, searching, learning, and troubleshooting,
+   then you should instead stick to the standard templates, which are perfectly
+   suitable for the vast majority of users. In particular, if you are new to
+   Qubes, you should not attempt to use minimal templates until you have gained
+   more experience.
 
 2. If something works with a standard template but not the minimal version,
    this is most likely due to user error (e.g., a missing package or
@@ -259,6 +263,9 @@ list of packages to be installed):
 - `default-mgmt-dvm`: requires `qubes-core-agent-passwordless-root` and
   `qubes-mgmt-salt-vm-connector`.
 - [Yubikey](/doc/yubikey/): You may need to install `xserver-xorg-input-libinput` for 2FA responses to work in web browsers like Firefox.
+- Thumbnails (e.g., file previews in Nautilus): `libgdk-pixbuf2.0-bin` (images),
+  `ffmpegthumbnailer` (videos). (Try `apt search thumbnailer` for other file
+  types.)
 
 In Qubes 4.0, additional packages from the `qubes-core-agent` suite may be
 needed to make the customized minimal template work properly. These packages

user/templates/templates.md

@@ -104,28 +104,23 @@ 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.
 
-Please refer to each template's installation instructions. Usually, the
+You can use a command line tool - `qvm-template` - or a GUI - `qvm-template-gui`.
-installation method is to execute the following type of command in dom0:
 
+At the command line in dom0, `qvm-template list --available` will show available templates. To install a template, use:
 ```
-$ sudo qubes-dom0-update qubes-template-<DISTRO_NAME>-<RELEASE_NUMBER>
+$ qvm-template install  <template_name>
 ```
 
-`qubes-template-<DISTRO_NAME>-<RELEASE_NUMBER>` is the name of the desired
+You can also use `qvm-template` to upgrade or reinstall templates.
-template package. Advanced users can install a
-[minimal](/doc/templates/minimal/) version of the template, if one exists, by
-appending `-minimal` directly to the end of the template package name.
-
-If you wish to install a community template, you must enable the community
-template repo:
 
+Repo definitions are stored 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. :
 ```
-$ sudo qubes-dom0-update --enablerepo=qubes-templates-community qubes-template-<DISTRO_NAME>-<RELEASE_NUMBER>
+$ 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`.  
-If you receive the message that no match is found for
+To permanently disable, set the line to `enabled = 0`.
-`qubes-template-<DISTRO_NAME>-<RELEASE_NUMBER>`, see
-[here](/faq/#when-i-try-to-install-a-template-it-says-no-match-is-found).
 
 If you wish to install a template that is in testing, please see
 [here](/doc/testing/#templates).
@@ -227,40 +222,57 @@ Please see [How to Reinstall a Template](/doc/reinstall-template/).
 
 ## Switching
 
-When you install a new template or upgrade a clone of a template, it is
+When you install a new template or
-recommended that you switch everything that was set to the old template to the
+[upgrade](/doc/how-to-update/#upgrading-to-avoid-eol) a template, it is
+recommended that you switch everything that was using the old template to the
 new template:
 
-1. Make the new template the default template.
+1. **Make the new template the default template.** In the App Menu, go
+   to Qubes Tools, then click on Qubes Global Settings. In the Qube Defaults
+   section, next to Template, select the new template from the
+   drop-down list. Press OK.
 
-    ```
+2. **Base your [disposable templates](/doc/glossary/#disposable-template) on
-    Applications Menu -> System Tools -> Qubes Global Settings -> Default template
+   the new template.**
-    ```
 
-2. If your keyboard or mouse is connected through `sys-usb`, switch `sys-usb`
+   - If your only keyboard and mouse are *not* connected through a [USB
-   to the new template. (Note that this is a single command to ensure that
+     qube](/doc/usb-qubes/), or that USB qube is *not* a disposable, then shut
-   `sys-usb` restarts. If it does not, you will not be able to use your USB
+     down all disposables. In the App Menu, go to Qubes Tools, then click on
-   keyboard or mouse.)
+     Qube Manager. In the Qube Manager, find your disposable template(s). (By
+     default, they end in `-dvm`.) Right click, hover over Template, then click
+     on the new template. Repeat for each disposable template.
 
-    ```
+   - If your only keyboard or mouse *are* connected through a USB qube, and
-    [user@dom0 ~]$ qvm-shutdown --wait sys-usb; qvm-prefs sys-usb template <NEW_TEMPLATE>; qvm-start sys-usb
+     that USB qube *is* a disposable, then you will have to enter a special
-    ```
+     command that shuts down all of your qubes, switches the USB qube's
+     disposable template to the new template, then starts the USB qube again.
+     In order to avoid being locked out of your system, you must be very
+     careful to enter this command without typos and with the correct
+     substitutions.
 
-3. Base app qubes on the new template.
+     In the App Menu, click on Terminal Emulator. Type the command below,
+     substituting `<SYS_USB_DISPOSABLE_TEMPLATE>` with the name of the
+     disposable template on which `sys-usb` is based, `<NEW_TEMPLATE>` with the
+     name of the new template, and `<USB_QUBE>` with the name of your USB qube.
+     Other than these substitutions, make sure to enter the command exactly as
+     written.
 
-    ```
+     ```
-    Applications Menu -> System Tools -> Qubes Template Manager
+     qvm-shutdown --wait --all; qvm-prefs <SYS_USB_DISPOSABLE_TEMPLATE> template <NEW_TEMPLATE>; qvm-start <USB_QUBE>
-    ```
+     ```
 
-4. Base the [disposable template](/doc/glossary/#disposable-template) on the new
+     With substitutions, your command should look similar to this example.
-   template.
+     (Warning: This is just an example. Do not attempt to use it.)
 
-    ```
+     ```
-    [user@dom0 ~]$ qvm-create -l red -t <NEW_TEMPLATE> <NEW_DISPOSABLE_TEMPLATE>
+     qvm-shutdown --wait --all; qvm-prefs fedora-01-dvm template fedora-02; qvm-start sys-usb
-    [user@dom0 ~]$ qvm-prefs <NEW_DISPOSABLE_TEMPLATE> template_for_dispvms True
+     ```
-    [user@dom0 ~]$ qvm-features <NEW_DISPOSABLE_TEMPLATE> appmenus-dispvm 1
+
-    [user@dom0 ~]$ qubes-prefs default-dispvm <NEW_DISPOSABLE_TEMPLATE>
+3. **Base your app qubes on the new template.** In the Qube Manager, click on
-    ```
+   the Template heading to sort by template. Select all the qubes based on the
+   old template by clicking on the first one, holding shift, then clicking on
+   the last one. With multiple qubes selected, right-click on any of them,
+   hover your cursor over Template, then click on the new template.
 
 ## Advanced
 

user/templates/xfce-templates.md

@@ -13,7 +13,7 @@ title: Xfce templates
 ---
 
 If you would like to use Xfce (more lightweight compared to GNOME desktop environment) Linux distribution in your qubes,
-you can install one of the available Xfce templates for [Fedora](/doc/templates/fedora/), [CentOS](/doc/templates/centos/) or [Gentoo](/doc/templates/gentoo/).
+you can install one of the available Xfce templates for [Fedora](/doc/templates/fedora/), [Debian](/doc/templates/debian/), [CentOS](/doc/templates/centos/), or [Gentoo](/doc/templates/gentoo/).
 
 ## Installation
 

user/troubleshooting/uefi-troubleshooting.md

@@ -133,7 +133,7 @@ Some laptops cannot read from an external boot device larger than 8GB. If you en
 
 ## Installation completes successfully but then boot loops or hangs on black screen
 
-There is a [common bug in UEFI implementation](http://xen.markmail.org/message/f6lx2ab4o2fch35r) affecting mostly Lenovo systems, but probably some others too.
+There is a [common bug in UEFI implementation](https://xen.markmail.org/message/f6lx2ab4o2fch35r) affecting mostly Lenovo systems, but probably some others too.
 While some systems need `mapbs` and/or `noexitboot` disabled to boot, others require them enabled at all times.
 Although these are enabled by default in the installer, they are disabled after the first stage of a successful install.
 You can re-enable them either as part of the install process:
@@ -177,7 +177,7 @@ Or if you have already rebooted after the first stage install and have encounter
 
 ## Installation completes successfully but then system crash/restarts on next boot
 
-Some Dell systems and probably others have [another bug in UEFI firmware](http://markmail.org/message/amw5336otwhdxi76).
+Some Dell systems and probably others have [another bug in UEFI firmware](https://markmail.org/message/amw5336otwhdxi76).
 These systems need `efi=attr=uc` enabled at all times.
 Although this is enabled by default in the installer, it is disabled after the first stage of a successful install.
 You can re-enable it either as part of the install process: