Merge pull request #3 from QubesOS/master

Merge 3

about/experts.md

@@ -7,7 +7,7 @@ permalink: /experts/
 <div class="home-content container">
   <div class="row more-top">
     <div class="col-lg-12 col-md-12">
-      <h2 class="text-center"><i class="fa fa-thumbs-o-up"></i> What the experts are saying about Qubes</h2>
+      <h2 class="text-center"><i class="fa fa-quote-left"></i> What the experts are saying about Qubes</h2>
     </div>
   </div>
   <div class="white-box more-bottom">

about/faq.md

@@ -431,7 +431,7 @@ The encrypted partitions are identified and the user is prompted for password on
 
 A fully encrypted drive does not appear in Nautilus.
 
-The work round is to manually decrypt and mount the drive:
+The workaround is to manually decrypt and mount the drive:
 
 1. attach usb device to qube - it should be attached as /dev/xvdi or similar.
 2. sudo cryptsetup open /dev/xvdi bk --type luks
@@ -461,6 +461,15 @@ If it seems like the issue described in [this thread](https://github.com/QubesOS
 
 Please report (via the mailing lists) if you experience this issue, and whether disabling the compositor fixes it for you or not.
 
+### My HVM in Qubes R4.0 won't let me start/install an OS
+
+I see a screen popup with SeaBios and 4 lines, last one being `Probing EDD (edd=off to disable!... ok`.
+
+From a `dom0` prompt, enter:
+
+    qvm-prefs <HVMname> kernel ""
+
+
 ----------
 
 ## Developers

basics_dev/coding-style.md

@@ -97,7 +97,7 @@ General programming style guidelines
     }
     ~~~
 
--   Do **not** use comments to disable code fragments. In a production code there should really be no commented or disabled code fragments. If you really, really have a good reason to retain some fragment of unused code, use \#if or \#ifdef to disable it, e.g.:
+-   Do **not** use comments to disable code fragments. In production code there should really be no commented or disabled code fragments. If you really, really have a good reason to retain some fragment of unused code, use \#if or \#ifdef to disable it, e.g.:
 
     ~~~
     #if 0
@@ -130,7 +130,7 @@ Source Code management (Git) guidelines
     -   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.
     -   By maintaining relatively small git repositories, it is easy for new developers to understand the code and contribute new patches, without the need to understand all the other code.
     -   Code repositories represent also licensing boundaries. So, e.g. because `core-agent-linux` and `core-agent-windows` are maintained in two different repositories, it is possible to have the latter under a proprietary, non-GPL license, while keeping the former fully open source.
-    -   We have drastically changes the layout and naming of the code repositories shortly after Qubes OS R2 Beta 2 release. For details on the current code layout, please read [this article](https://blog.invisiblethings.org/2013/03/21/introducing-qubes-odyssey-framework.html).
+    -   We have drastically changed the layout and naming of the code repositories shortly after Qubes OS R2 Beta 2 release. For details on the current code layout, please read [this article](https://blog.invisiblethings.org/2013/03/21/introducing-qubes-odyssey-framework.html).
 
 Commit message guidelines
 -------------------------
@@ -165,7 +165,7 @@ Security coding guidelines
        height = untrusted_conf.height;
     ~~~
 
--   Use another variables, without the `untrusted_` prefix to hold the sanitized values, as shown above.
+-   Use others variables, without the `untrusted_` prefix to hold the sanitized values, as shown above.
 
 Python-specific guidelines
 --------------------------
@@ -178,7 +178,7 @@ C and C++ specific guidelines
 -   Do not place code in `*.h` files.
 -   Use `const` whenever possible, e.g. in function arguments passed via pointers.
 -   Do not mix procedural and objective code together -- if you write in C++, use classes and objects.
--   Think about classes hierarchy, before start implementing specific methods.
+-   Think about classes hierarchy, before starting to implement specific methods.
 
 Bash-specific guidelines
 ------------------------

basics_dev/style-guide.md

@@ -68,7 +68,7 @@ Currently, all the icons on the Qubes-OS.org website are generated using [FontAw
 
 ## Logos
 
-The following is a collection of various sizes & versions of the Qubes logo used both in the OS itself and on our website. All of these files are licensed GPLv2 and the source can be [downloaded here](https://github.com/QubesOS/qubes-artwork).
+The following is a collection of various sizes and versions of the Qubes logo used both in the OS itself and on our website. All of these files are licensed GPLv2 and the source can be [downloaded here](https://github.com/QubesOS/qubes-artwork).
 
 <div class="styleguide">
 {% for logo in site.data.styleguide.logos %}

basics_dev/usability-ux.md

@@ -44,7 +44,7 @@ In making software easy to use, it is crucial to be mindful of [cognitive load](
 
 ## Easy to Understand
 
-There will always be the need to communicate things to users. In these cases, an interface should aim to make this information easy to understand. The following are simple guides to help achieve this - none these are absolute maxims!
+There will always be the need to communicate things to users. In these cases, an interface should aim to make this information easy to understand. The following are simple guides to help achieve this - none of these are absolute maxims!
 
 <div class="focus">
   <i class="fa fa-times"></i> <strong>Avoid Acronyms</strong>
@@ -82,7 +82,7 @@ Technical words are usually more accurate, but they often *only* make sense to t
 - `savefile`
 - `qrexec-daemon`
 
-These are all terms that have at some point showed up in users' notification messages. Each term is very specific, but requires the user to understand virtualization to interpet.
+These are all terms that have at some point showed up in users' notification messages. Each term is very specific, but requires the user to understand virtualization to interpret.
 
 <div class="focus">
   <i class="fa fa-check"></i> <strong> Use Common Concepts</strong>
@@ -195,7 +195,7 @@ There are many cases where a user wants to perform an action on more than one fi
 3. Select proper file
 4. Complete task on file
 
-That subtle act of clicking through a file system can prove to be significant if a user needs to open more than a couples files in the same directory. We can alleviate some of the work by changing the process:
+That subtle act of clicking through a file system can prove to be significant if a user needs to open more than a couple files in the same directory. We can alleviate some of the work by changing the process:
 
 1. Click on `Open File` from a menu or button
 2. Remember last open folder/file system

basics_user/doc-guidelines.md

@@ -43,7 +43,7 @@ documentation change will be reviewed before it's published to the web. This
 allows us to maintain quality control and protect our users.
 
 As mentioned above, we keep all the documentation in a dedicated [Git
-repository][qubes-doc] hosted on [GitHub]. Thanks to GitHub's interface, you can
+repository][qubes-doc] hosted on [GitHub]. Thanks to the GitHub's interface, you can
 edit the documentation even if you don't know Git at all! The only thing you
 need is a GitHub account, which is free.
 
@@ -105,6 +105,18 @@ pull request, we'll post a comment explaining why we can't.
 ![done](/attachment/wiki/doc-edit/10-done.png)
 
 
+How to add images
+-----------------
+
+To add an image to a page, use the following syntax in the main document:
+
+```
+![Image Title](/attachment/wiki/page-title/image-filename.png)
+```
+
+Then, submit your image(s) in a separate pull request to the [qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository using the same path and filename.
+
+
 Version-specific Documentation
 ------------------------------
 

basics_user/getting-started.md

@@ -134,10 +134,6 @@ Otherwise, a compromised qube which is able to occupy the entire screen could tr
 Since a compromised qube can draw pixels within its own windows however it likes, it could draw a fake password prompt, for example, which appears to have a different colored border so that it looks like it belongs to a different qube. 
 This is why you should always drag such prompts away from other windows (or use some other means of manipulating the windows) to ensure that they belong to the qube to which they appear to belong.
 
-However, if the user makes use of an "expose-like" desktop switcher, such as the "Desktop Grid" effect that is enabled by default under KDE (default activation command: Ctrl-F8), then we can safely allow qubes to enter full screen mode, as we have assurance that we can always "preempt" them by hitting the magic key combination (e.g., Ctrl-F8), which will be consumed by the trusted window manager and not passed down to the fullscreen qube. 
-This means that the qube has no way of effectively "faking" the fullscreen view of the system, as the user can easily identify it as "just another qube." 
-Theoretically, this could be achieved even with primitive Alt-Tab like switching, which should be available on simpler Window Managers (such as Xfce4, which we also support as an alternative dom0 Desktop Environment), but this might be less obvious to the user.
-
 To allow a qube to enter full screen mode, one should edit the `/etc/qubes/guid.conf` file in dom0.
 
 To allow all qubes to enter full screen mode, set `allow_fullscreen` flag to `true` in the `global` section:

building/building-archlinux-template.md

@@ -362,7 +362,7 @@ redirect_from:
 The `qubes-mgmt-salt` repo is not currently forked under the marmarek user on
 GitHub, to whom the above instructions set the `GIT_PREFIX`.  As Archlinux is
 not yet supported by mgmt-salt, simply leave it out of the build (when building
-the Archlinux template on it's own) by appending the following to your `override.conf` file:
+the Archlinux template on its own) by appending the following to your `override.conf` file:
 
 `BUILDER_PLUGINS := $(filter-out mgmt-salt,$(BUILDER_PLUGINS))`
 

building/development-workflow.md

@@ -419,7 +419,7 @@ Remember to also import gpg public key using `rpm --import`.
 
 ### Deb packages - Apt repo
 
-Steps are mostly the same as in case of yum repo. Only details differs:
+Steps are mostly the same as in the case of yum repo. The only details that differ:
 
  - use [linux-deb] instead of [linux-yum] as a base - both in source and target VM
  - use different `update_repo.sh` script in source VM (below)

building/qubes-builder-details.md

@@ -33,8 +33,8 @@ Variables for Windows build:
 -   `WIN_SIGN_CMD` Command used to sign resulting binaries. Note that default value is *sign.bat*. If you don't want to sign binaries, specify some placeholder here (eg. *true*). Check existing components (eg. vmm-xen-windows-pvdrivers) for example scripts. This command will be run with certain environment variables:
     -   `CERT_FILENAME` Path to key file (pfx format)
     -   `CERT_PASSWORD` Key password
-    -   `CERT_PUBLIC_FILENAME` Certificate path in case of self-signed cert
+    -   `CERT_PUBLIC_FILENAME` Certificate path in the case of self-signed cert
-    -   `CERT_CROSS_CERT_FILENAME` Certificate path in case of correct autheticode cert
+    -   `CERT_CROSS_CERT_FILENAME` Certificate path in the case of correct autheticode cert
     -   `SIGNTOOL` Path to signtool
 -   `WIN_PACKAGE_CMD` Command used to produce installation package (msi or msm). Default value is *wix.bat*, similar to above - use *true* if you don't want this command.
 -   `WIN_OUTPUT_HEADERS` Directory (relative to `WIN_SOURCE_SUBDIRS` element) with public headers of the package - for use in other components.

common-tasks/backup-restore.md

@@ -215,7 +215,7 @@ Here are some things to consider when selecting a passphrase for your backups:
  For example, when you attempt to retrieve a recent backup, the adversary may instead give you a very old backup containing a compromised VM. 
  If you're concerned about this type of attack, you may wish to use a different passphrase for each backup, e.g., by appending a number or date to the passphrase.
  * If you're forced to enter your system drive decryption passphrase in plain view of others (where it can be shoulder-surfed), then you may want to use a different passphrase for your backups (even if your system drive decryption passphrase is already maximally strong).
- On the othe hand, if you're careful to avoid shoulder-surfing and/or have a passphrase that's difficult to detect via shoulder-surfing, then this may not be a problem for you.
+ On the other hand, if you're careful to avoid shoulder-surfing and/or have a passphrase that's difficult to detect via shoulder-surfing, then this may not be a problem for you.
 
 Notes
 -----

common-tasks/copy-from-dom0.md

@@ -21,66 +21,49 @@ To copy a file from dom0 to a VM (domU), simply use `qvm-copy-to-vm`:
 qvm-copy-to-vm <dest-vm> <file>
 ~~~
 
-The file will arrive in your destination VM in the `~/QubesIncoming/dom0/`
+The file will arrive in your destination VM in the `~/QubesIncoming/dom0/` directory.
-directory.
 
 ### Copying logs from Dom0 ###
 
-In order to easily copy/paste the contents of logs from dom0 to the inter-VM
+In order to easily copy/paste the contents of logs from dom0 to the inter-VM clipboard, you can simply:
-clipboard, you can simply:
 
 1.  Right-click on the desired VM in the Qubes VM Manager.
 2.  Click "Logs."
 3.  Click on the desired log.
 4.  Click "Copy to Qubes clipboard."
 
-You may now paste the log contents to any VM as you normally would (i.e.,
+You may now paste the log contents to any VM as you normally would (i.e., Ctrl-Shift-V, then Ctrl-V).
-Ctrl-Shift-V, then Ctrl-V).
 
 ### Copy/paste from Dom0 ###
 
 For data other than logs, there are several options:
 
 1.  Copy it as a file (see above)
-2.  Since updated versions of 3.2 you can copy text to the dom0 clipboard
+2.  In Qubes 3.2 you can copy text to the dom0 clipboard (Ctrl-C as normal), then click "Copy Dom0 clipboard" in the Qubes menu:
-    (Ctrl-C as normal), then click "Copy Dom0 clipboard" in the Qubes menu:
     ![copy-dom0-clipboard](/attachment/wiki/QubesScreenshots/r3.2-dom0-copyout.png)
     which is equivelant to Ctrl-Shift-C from a normal AppVM.
-    Then you can use Ctrl-Shift-V and Ctrl-V to paste the copied text into an
+    Then you can use Ctrl-Shift-V and Ctrl-V to paste the copied text into an AppVM as normal.
-    AppVM as normal.
+3.  In other versions, write the data you wish to copy into `/var/run/qubes/qubes-clipboard.bin`, then `echo -n dom0 > /var/run/qubes/qubes-clipboard.bin.source`.
-3.  In older versions, write the data you wish to copy into
-    `/var/run/qubes/qubes-clipboard.bin`, then write "dom0" to
-    `/var/run/qubes/qubes-clipboard.bin.source`.
     Then use Ctrl-Shift-V to paste the data to the desired VM.
 
 
 Copying **to** Dom0
 -------------------
 
-There should normally be few reasons for the user to want to copy files from VMs
+There should normally be few reasons for the user to want to copy files from VMs to Dom0, as Dom0 only acts as a "thin trusted terminal", and no user applications run there.
-to Dom0, as Dom0 only acts as a "thin trusted terminal", and no user
+Copying untrusted files to Dom0 is not advised and may compromise the security of your Qubes system.
-applications run there. Copying untrusted files to Dom0 is not advised and may
+Because of this, we do not provide a graphical user interface for it, unlike [copying files between VMs](/doc/copying-files/).
-compromise the security of your Qubes system. Because of this, we do not provide
-a graphical user interface for it, unlike [copying files between
-VMs](/doc/copying-files/).
 
-One common use-case for this is if we want to use a desktop wallpaper in Dom0 we
+One common use-case for this is if we want to use a desktop wallpaper in Dom0 we have located in one of our AppVMs (e.g. in the 'personal' AppVM where we got the wallpaper from our camera or downloaded it from the Internet).
-have located in one of our AppVMs (e.g. in the 'personal' AppVM where we got the
+While it's a well-justified reason, imagine what would happen if the wallpaper (e.g. a JPEG file) was somehow malformed or malicious and attempted to exploit a hypothetical JPEG parser bug in Dom0 code (e.g. in the Dom0's Xorg/KDE code that parses the wallpaper and displays it).
-wallpaper from our camera or downloaded it from the Internet). While it's a
-well-justified reason, imagine what would happen if the wallpaper (e.g. a JPEG
-file) was somehow malformed or malicious and attempted to exploit a hypothetical
-JPEG parser bug in Dom0 code (e.g. in the Dom0's Xorg/KDE code that parses the
-wallpaper and displays it).
 
-If you are determined to copy some files to Dom0 anyway, you can use the
+If you are determined to copy some files to Dom0 anyway, you can use the following method (run this command from Dom0's console):
-following method (run this command from Dom0's console):
 
 ~~~
 qvm-run --pass-io <src-vm> 'cat /path/to/file_in_src_domain' > /path/to/file_name_in_dom0
 ~~~
 
-You can use the same method to copy files from Dom0 to VMs (if, for some reason,
+You can use the same method to copy files from Dom0 to VMs (if, for some reason, you don't want to use `qvm-copy-to-vm`):
-you don't want to use `qvm-copy-to-vm`):
 
 ~~~
 cat /path/to/file_in_dom0 | qvm-run --pass-io <dest-vm> 'cat > /path/to/file_name_in_appvm'

common-tasks/dispvm.md

@@ -11,16 +11,56 @@ redirect_from:
 Disposable VMs (DispVMs)
 ========================
 
-A Disposable VM (DispVM) is a lightweight VM that can be created quickly and will disappear when closed. 
+A Disposable VM (DispVM) is a lightweight VM that can be created quickly and will disappear when closed.
-Disposable VMs are usually created in order to host a single application, like a viewer, editor, or web browser. 
+Disposable VMs are usually created in order to host a single application, like a viewer, editor, or web browser.
-Changes made to a file opened in a Disposable VM are passed back to the originating VM. 
+
-This means that you can safely work with untrusted files without risk of compromising your other VMs. 
+From inside an AppVM, choosing the `Open in Disposable VM` option on a file will launch a DispVM for just that file.
-DispVMs can be created either directly from Dom0 or from within AppVMs. 
+Changes made to a file opened in a DispVM are passed back to the originating VM.
-Once a DispVM has been created it will appear in Qubes VM Manager with the name "dispX". 
+This means that you can safely work with untrusted files without risk of compromising your other VMs.
+DispVMs can be launched either directly from Dom0's Start Menu or terminal window, or from within AppVMs.
+While running, DispVMs will appear in Qubes VM Manager with the name `disp####`.
 
 See [this article](https://blog.invisiblethings.org/2010/06/01/disposable-vms.html) for more on why one would want to use a Disposable VM.
 
-Disposable VMs and Networking
+
+Disposable VMs and Networking (R4.0 and later)
+-----------------------------
+
+Similarly to how AppVMs are based on their underlying [TemplateVM](https://www.qubes-os.org/doc/glossary/#templatevm), DispVMs are based on their underlying [DVM Template](https://www.qubes-os.org/doc/glossary/#dvm-template).
+R4.0 introduces the concept of multiple DVM Templates, whereas R3.2 was limited to only one.
+
+On a fresh installation of Qubes, the default DVM Template is called `fedora-XX-dvm` (where `XX` is the Fedora version of the default TemplateVM).
+If you have included the Whonix option in your install, there will also be a `whonix-ws-dvm` DVM Template available for your use.
+
+You can set any AppVM to have the ability to act as a DVM Template with:
+
+    qvm-prefs <vmname> template_for_dispvms true
+
+The default system wide DVM Template can be changed with `qubes-prefs default_dispvm`.
+By combining the two, choosing `Open in Disposable VM` from inside an AppVM will open the document in a DispVM based on the default DVM 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. 
+Here you can edit the "Default DispVM" setting to specify which DVM Template will be used to launch DispVMs from that VM.
+This can also be changed from the command line with:
+
+    qvm-prefs <vmname> default_dispvm <dvmtemplatename>
+
+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 AppVM that has also been configured as a DVM Template to use itself, so DispVMs launched from within the AppVM/DVM Template would inherit the same settings.
+
+NetVM and firewall rules for DVM Templates can be set as they can for a normal VM. 
+By default a DispVM will inherit the NetVM and firewall settings of the DVM Template on which it is based.
+This is a change in behaviour from R3.2, where DispVMs would inherit the settings of the AppVM from which they were launched.
+Therefore, launching a DispVM from an AppVM will result in it using the network/firewall settings of the DVM Template on which it is based.
+For example, if an AppVM uses sys-net as its NetVM, but the default system DispVM uses sys-whonix, any DispVM launched from this AppVM will have sys-whonix as its NetVM.
+
+**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 DispVM uses sys-net, launching a DispVM from inside anon-whonix will result in the DispVM using sys-net.
+
+A Disposable VM launched from the Start Menu inherits the NetVM and firewall settings of the DVM Template on which it is based.
+Note that changing the "NetVM" setting for the system default DVM Template *does* affect the NetVM of DispVMs launched from the Start Menu.
+Different DVM Templates with individual NetVM settings can be added to the Start Menu. 
+
+Disposable VMs and Networking (R3.2 and earlier)
 -----------------------------
 
 NetVM and firewall rules for Disposable VMs can be set as they can for a normal VM. 
@@ -49,7 +89,7 @@ Opening a fresh web browser instance in a new Disposable VM
 -----------------------------------------------------------
 
 Sometimes it is desirable to open an instance of Firefox within a new fresh Disposable VM. 
-This can be done easily using the Start Menu: just go to Start -\> System Tools -\> DispVM:Firefox web browser. 
+This can be done easily using the Start Menu: just go to **Application Menu -\> DisposableVM -\> DispVM:Firefox web browser**. 
 Wait a few seconds until a web browser starts. 
 Once you close the viewing application the whole Disposable VM will be destroyed. 
 
@@ -75,7 +115,7 @@ Sometimes it can be useful to start an arbitrary program in a DispVM. This can b
 [user@vault ~]$ qvm-run '$dispvm' xterm
 ~~~
 
-The created Disposable VM can be accessed via other tools (such as `qvm-copy-to-vm`) using its "dispX" name as shown in the Qubes Manager or `qvm-ls`.
+The created Disposable VM can be accessed via other tools (such as `qvm-copy-to-vm`) using its `disp####` name as shown in the Qubes Manager or `qvm-ls`.
 
 Starting an arbitrary application in a Disposable VM via command line (from Dom0)
 ---------------------------------------------------------------------------------
@@ -83,6 +123,12 @@ Starting an arbitrary application in a Disposable VM via command line (from Dom0
 The Start Menu has shortcuts for opening a terminal and a web browser in dedicated DispVMs, since these are very common tasks.
 However, it is possible to start an arbitrary application in a DispVM directly from Dom0 by running
 
+R4.0 (border colour will be inherited from that set in the `dispvm-template`)
+~~~
+[joanna@dom0 ~]$ qvm-run --dispvm=dispvm-template --service qubes.StartApp+xterm
+~~~
+
+R3.2 (border colour can be specified in the command)
 ~~~
 [joanna@dom0 ~]$ echo xterm | /usr/lib/qubes/qfile-daemon-dvm qubes.VMShell dom0 DEFAULT red
 ~~~
@@ -92,8 +138,8 @@ However, it is possible to start an arbitrary application in a DispVM directly f
 Customizing Disposable VMs
 --------------------------
 
-You can change the template used to generate the Disposable VM, and change settings used in the Disposable VM savefile. 
+You can change the template used to generate the Disposable VMs, and change settings used in the Disposable VM savefile. 
-These changes will be reflected in every new Disposable VM. 
+These changes will be reflected in every new Disposable VM based on that template. 
 Full instructions can be found [here](/doc/dispvm-customization/).
 
 Disposable VMs and Local Forensics

common-tasks/full-screen-mode.md

@@ -24,7 +24,7 @@ If one allowed one of the VMs to "own" the full screen, e.g. to show a movie on
 Secure use of full screen mode
 ------------------------------
 
-However, it is possible to deal with full screen mode in a secure way assuming there are mechanisms that can be used at any time to show the full desktop, and which cannot be intercepted by the VM. An example of such q mechanism is the KDE's "Present Windows" and "Desktop Grid" effects, which are similar to Mac's "Expose" effect, and which can be used to immediately detect potential "GUI forgery", as they cannot be intercepted by any of the VM (as the GUID never passes down the key combinations that got consumed by KDE Window Manager), and so the VM cannot emulate those. Those effects are enabled by default in KDE once Compositing gets enabled in KDE (System Settings -\> Desktop -\> Enable Desktop Effects), which is recommended anyway. By default they are triggered by Ctrl-F8 and Ctrl-F9 key combinations, but can also be reassigned to other shortcuts.
+However, it is possible to deal with full screen mode in a secure way assuming there are mechanisms that can be used at any time to show the full desktop, and which cannot be intercepted by the VM. An example of such a mechanism is the KDE's "Present Windows" and "Desktop Grid" effects, which are similar to Mac's "Expose" effect, and which can be used to immediately detect potential "GUI forgery", as they cannot be intercepted by any of the VM (as the GUID never passes down the key combinations that got consumed by KDE Window Manager), and so the VM cannot emulate those. Those effects are enabled by default in KDE once Compositing gets enabled in KDE (System Settings -\> Desktop -\> Enable Desktop Effects), which is recommended anyway. By default they are triggered by Ctrl-F8 and Ctrl-F9 key combinations, but can also be reassigned to other shortcuts.
 Another option is to use Alt+Tab for switching windows. This shortcut is also handled by dom0.
 
 Enabling full screen mode for select VMs

common-tasks/managing-appvm-shortcuts.md

@@ -11,15 +11,16 @@ redirect_from:
 Managing shortcuts to applications in AppVMs
 ============================================
 
-For ease of use Qubes aggregates shortcuts to applications that are installed in AppVMs and shows them in one "start menu" in dom0. Clicking on such shortcut runs the assigned application in its AppVM.
+For ease of use Qubes aggregates shortcuts to applications that are installed in AppVMs and shows them in one "start menu" in dom0.
+Clicking on such shortcut runs the assigned application in its AppVM.
 
 ![dom0-menu.png"](/attachment/wiki/ManagingAppVmShortcuts/dom0-menu.png)
 
-To make newly installed applications show up in the menu, use the **qvm-sync-appmenus** command (Linux VMs does this automatically):
+To make newly installed applications show up in the menu, use the **qvm-sync-appmenus** command (Linux VMs do this automatically):
 
 `qvm-sync-appmenus vmname`
 
-After that, select the *Add more shortcuts* entry in VM's submenu to customize which applications are shown:
+After that, select the *Add more shortcuts* entry in the VM's submenu to customize which applications are shown:
 
 ![dom0-appmenu-select.png"](/attachment/wiki/ManagingAppVmShortcuts/dom0-appmenu-select.png)
 
@@ -33,16 +34,37 @@ What about applications in DispVMs?
 Behind the scenes
 -----------------
 
-The list of installed applications for each AppVM is stored in dom0's `/var/lib/qubes/vm-templates/templatename/apps.templates` (or in case of StandaloneVM: `/var/lib/qubes/appvms/vmname/apps.templates`). Each menu entry is a file that follows the [.desktop file format](https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) with some wildcards (*%VMNAME%*, *%VMDIR%*). Applications selected to appear in the menu are stored in `/var/lib/qubes/appvms/vmname/apps`.
+`qvm-sync-appmenus` works by invoking *GetAppMenus* [Qubes service](/doc/qrexec/) in the target domain.
+This service enumerates installed applications and sends formatted info back to the dom0 script (`/usr/libexec/qubes-appmenus/qubes-receive-appmenus`) which creates .desktop files in the AppVM/TemplateVM directory.
 
-Actual command lines for the menu shortcuts involve `qvm-run` command which starts a process in another domain. Examples: `qvm-run -q --tray -a w7s 'cmd.exe /c "C:\\ProgramData\\Microsoft\\Windows\\Start Menu\\Programs\\Accessories\\Calculator.lnk"'` or `qvm-run -q --tray -a untrusted 'firefox %u'`
+For Linux VMs the service script is in `/etc/qubes-rpc/qubes.GetAppMenus`. 
-Note that you can create a shortcut that points to a .desktop file in your AppVM with e.g. `qvm-run -q --tray -a personal -- 'qubes-desktop-run /home/user/application.desktop'`
+In Windows it's a PowerShell script located in `c:\Program Files\Invisible Things Lab\Qubes OS Windows Tools\qubes-rpc-services\get-appmenus.ps1` by default.
 
-`qvm-sync-appmenus` works by invoking *GetAppMenus* [Qubes service](/doc/qrexec/) in the target domain. This service enumerates installed applications and sends formatted info back to the dom0 script (`/usr/libexec/qubes-appmenus/qubes-receive-appmenus`) which creates .desktop files in the AppVM/TemplateVM directory.
+ * R4.0
+ 
+   The list of installed applications for each AppVM is stored in dom0's `~/.local/share/qubes-appmenus/vmname/apps.templates`.
+   Each menu entry is a file that follows the [.desktop file format](https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) with some wildcards (*%VMNAME%*, *%VMDIR%*).
+   Applications selected to appear in the menu are stored in `~/.local/share/qubes-appmenus/vmname/apps`.
+    
+   Actual command lines for the menu shortcuts involve `qvm-run` command which starts a process in another domain. 
+   Examples: `qvm-run -q -a --service -- %VMNAME% qubes.StartApp+7-Zip-7-Zip_File_Manager` or `qvm-run -q -a --service -- %VMNAME% qubes.StartApp+firefox`
 
-For Linux VMs the service script is in `/etc/qubes-rpc/qubes.GetAppMenus`. In Windows it's a PowerShell script located in `c:\Program Files\Invisible Things Lab\Qubes OS Windows Tools\qubes-rpc-services\get-appmenus.ps1` by default.
+   Note that you can create a shortcut that points to a .desktop file in your AppVM with e.g. `qvm-run -q -a --service -- personal qubes.StartApp+firefox`
+
+ * R3.2
+
+   The list of installed applications for each AppVM is stored in dom0's `/var/lib/qubes/vm-templates/templatename/apps.templates` (or in case of StandaloneVM: `/var/lib/qubes/appvms/vmname/apps.templates`). 
+   Each menu entry is a file that follows the [.desktop file format](https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) with some wildcards (*%VMNAME%*, *%VMDIR%*). 
+   Applications selected to appear in the menu are stored in `/var/lib/qubes/appvms/vmname/apps`.
+    
+   Actual command lines for the menu shortcuts involve `qvm-run` command which starts a process in another domain. 
+   Examples: `qvm-run -q --tray -a w7s 'cmd.exe /c "C:\\ProgramData\\Microsoft\\Windows\\Start Menu\\Programs\\Accessories\\Calculator.lnk"'` or `qvm-run -q --tray -a untrusted 'firefox %u'`
+
+   Note that you can create a shortcut that points to a .desktop file in your AppVM with e.g. `qvm-run -q --tray -a personal -- 'qubes-desktop-run /home/user/application.desktop'`.
 
 What if my application has not been automatically included in the list of available apps?
 -----------------------------------------------------------------------------------------
 
-You can manually create new entries in the "available applications" list of shortcuts. See [Signal](/doc/signal/) for a worked example of creating a new menu item for a Chrome .desktop shortcut.
+You can manually create new entries in the "available applications" list of shortcuts.
+See [Signal](/doc/signal/) for a working example of creating a new menu item for a Chrome .desktop shortcut.
+

common-tasks/software-update-dom0.md

@@ -14,7 +14,7 @@ Updating software in dom0
 Why would one want to update software in dom0?
 ----------------------------------------------
 
-Normally, there should be few reasons for updating software in dom0. This is because there is no networking in dom0, which means that even if some bugs are discovered e.g. in the dom0 Desktop Manager, this really is not a problem for Qubes, because none of the third-party software running in dom0 is accessible from VMs or the network in any way. Some exceptions to this include: Qubes GUI daemon, Xen store daemon, and disk back-ends. (We plan move the disk backends to an untrusted domain.) Of course, we believe this software is reasonably secure, and we hope it will not need patching.
+Normally, there should be few reasons for updating software in dom0. This is because there is no networking in dom0, which means that even if some bugs are discovered e.g. in the dom0 Desktop Manager, this really is not a problem for Qubes, because none of the third-party software running in dom0 is accessible from VMs or the network in any way. Some exceptions to this include: Qubes GUI daemon, Xen store daemon, and disk back-ends. (We plan move the disk backends to an untrusted domain in a future Qubes release.) Of course, we believe this software is reasonably secure, and we hope it will not need patching.
 
 However, we anticipate some other situations in which updating dom0 software might be necessary or desirable:
 

common-tasks/software-update-vm.md

@@ -14,15 +14,20 @@ Installing and updating software in VMs
 How TemplateVMs work in Qubes
 ------------------------------
 
-Most of the AppVMs (domains) are based on a *TemplateVM*, which means that their root filesystem (i.e. all the programs and system files) is based on the root filesystem of the corresponding template VM. This dramatically saves disk space, because each new AppVM needs disk space only for storing the user's files (i.e. the home directory). Of course the AppVM has only read-access to the template's filesystem -- it cannot modify it in any way.
+Most of the AppVMs (domains) are based on a *TemplateVM*, which means that their root filesystem (i.e. all the programs and system files) is based on the root filesystem of the corresponding template VM.
+This dramatically saves disk space, because each new AppVM needs disk space only for storing the user's files (i.e. the home directory).
+Of course the AppVM has only read-access to the template's filesystem -- it cannot modify it in any way.
 
-In addition to saving on the disk space, and reducing domain creation time, another advantage of such scheme is the possibility for centralized software update. It's just enough to do the update in the template VM, and then all the AppVMs based on this template get updates automatically after they are restarted.
+In addition to saving on the disk space, and reducing domain creation time, another advantage of such scheme is the possibility for centralized software update.
+It's just enough to do the update in the template VM, and then all the AppVMs based on this template get updates automatically after they are restarted.
 
 The default template is called **fedora-23** in Qubes R3.2 and **fedora-26** in Qubes R4.0.
 
-The side effect of this mechanism is, of course, that if you install any software in your AppVM, more specifically in any directory other than `/home`, `/usr/local`, or `/rw` then it will disappear after the AppVM reboots (as the root filesystem for this AppVM will again be "taken" from the TemplateVM). **This means one normally installs software in the TemplateVM, not in AppVMs.**
+The side effect of this mechanism is, of course, that if you install any software in your AppVM, more specifically in any directory other than `/home`, `/usr/local`, or `/rw` then it will disappear after the AppVM reboots (as the root filesystem for this AppVM will again be "taken" from the TemplateVM).
+**This means one normally installs software in the TemplateVM, not in AppVMs.**
 
-Unlike VM private filesystems, under R3.x the template VM root filesystem does not support discard by default, so deleting files does not free the space in dom0. See [these instructions](/doc/template/fedora/upgrade-23-to-24/#compacting-the-upgraded-template) to recover space in dom0.
+Unlike VM private filesystems, under R3.x the template VM root filesystem does not support discard by default, so deleting files does not free the space in dom0.
+See [these instructions](/doc/template/fedora/upgrade-23-to-24/#compacting-the-upgraded-template) to recover space in dom0.
 
 In R4.0 and higher, the template root filesystem is created in a thin pool so manual trims are no longer needed.
 
@@ -35,9 +40,13 @@ In order to permanently install new software, you should:
 
 -   Start the template VM and then start either console (e.g. `gnome-terminal`) or dedicated software management application, such as `gpk-application` (*Start-\>Applications-\>Template: fedora-XX-\>Add/Remove software*),
 
--   Install/update software as usual (e.g. using dnf, or the dedicated GUI application). Then, shutdown the template VM,
+-   Install/update software as usual (e.g. using dnf, or the dedicated GUI application).
+    Then, shutdown the template VM.
 
--   You will see now that all the AppVMs based on this template (by default all your VMs) will be marked as "outdated" in the manager. This is because their filesystems have not been yet updated -- in order to do that, you must restart each VM. You don't need to restart all of them at the same time -- e.g. if you just need the newly installed software to be available in your 'personal' domain, then restart only this VM. You will restart others whenever this will be convenient to you.
+-   You will see now that all the AppVMs based on this template (by default all your VMs) will be marked as "outdated" in the manager.
+    This is because their filesystems have not been yet updated -- in order to do that, you must restart each VM.
+    You don't need to restart all of them at the same time -- e.g. if you just need the newly installed software to be available in your 'personal' domain, then restart only this VM.
+    You can restart others whenever this will be convenient to you.
 
 Testing repositories
 --------------------
@@ -46,15 +55,12 @@ Testing repositories
 
 There are three Qubes VM testing repositories (where `*` denotes the Release):
 
-* `qubes-vm-*-current-testing` -- testing packages that will eventually land in the stable
+* `qubes-vm-*-current-testing` -- testing packages that will eventually land in the stable (`current`) repository
-  (`current`) repository
+* `qubes-vm-*-security-testing` -- a subset of `qubes-vm-*-current-testing` that contains packages that qualify as security fixes
-* `qubes-vm-*-security-testing` -- a subset of `qubes-vm-*-current-testing` that contains packages
+* `qubes-vm-*-unstable` -- packages that are not intended to land in the stable (`qubes-vm-*-current`) repository; mostly experimental debugging packages
-  that qualify as security fixes
-* `qubes-vm-*-unstable` -- packages that are not intended to land in the stable (`qubes-vm-*-current`)
-  repository; mostly experimental debugging packages
 
-To temporarily enable any of these repos, use the `--enablerepo=<repo-name>`
+To temporarily enable any of these repos, use the `--enablerepo=<repo-name>` option.
-option. Example commands:
+Example commands:
 
 ~~~
 sudo dnf upgrade --enablerepo=qubes-vm-*-current-testing
@@ -62,50 +68,42 @@ sudo dnf upgrade --enablerepo=qubes-vm-*-security-testing
 sudo dnf upgrade --enablerepo=qubes-vm-*-unstable
 ~~~
 
-To enable or disable any of these repos permanently, change the corresponding boolean in
+To enable or disable any of these repos permanently, change the corresponding boolean in `/etc/yum.repos.d/qubes-*.repo`.
-`/etc/yum.repos.d/qubes-*.repo`.
 
 ### Debian ###
 
 Debian also has three Qubes VM testing repositories (where `*` denotes the Release):
 
-* `*-testing` -- testing packages that will eventually land in the stable
+* `*-testing` -- testing packages that will eventually land in the stable (`current`) repository
-  (`current`) repository
+* `*-securitytesting` -- a subset of `*-testing` that contains packages that qualify as security fixes
-* `*-securitytesting` -- a subset of `*-testing` that contains packages
+* `*-unstable` -- packages that are not intended to land in the stable repository; mostly experimental debugging packages
-  that qualify as security fixes
-* `*-unstable` -- packages that are not intended to land in the stable
-  repository; mostly experimental debugging packages
 
-To enable or disable any of these repos permanently, uncomment the corresponding `deb` line in
+To enable or disable any of these repos permanently, uncomment the corresponding `deb` line in `/etc/apt/sources.list.d/qubes-r*.list`
-`/etc/apt/sources.list.d/qubes-r*.list`
 
 Reverting changes to a TemplateVM (R4.0)
 ---------------------------------
 
-TBD- Qubes 4.0 uses a CoW system that permits snapshotting. To revert changes, one would...
+Qubes 4.0 uses a CoW system that permits snapshotting.
+Reversion functionality is still being developed at the time of writing.
+See [issue #3256](https://github.com/QubesOS/qubes-issues/issues/3256) for details.
 
 Reverting changes to a TemplateVM (R3.2)
 ---------------------------------
 
 Perhaps you've just updated your TemplateVM, and the update broke your template.
-Or perhaps you've made a terrible mistake, like accidentally confirming the
+Or perhaps you've made a terrible mistake, like accidentally confirming the installation of an unsigned package that could be malicious.
-installation of an unsigned package that could be malicious. Fortunately,
+Fortunately, it's easy to revert changes to TemplateVMs using the `qvm-revert-template-changes` command.
-it's easy to revert changes to TemplateVMs using the
-`qvm-revert-template-changes` command.
 
-**Important:** This command will roll back any changes made *during the last
+**Important:** This command will roll back any changes made *during the last time the TemplateVM was run, but **not** before.*
-time the TemplateVM was run, but **not** before.* This means that if you have
+This means that if you have already restarted the TemplateVM, using this command is unlikely to help, and you'll likely want to reinstall it from the repository instead.
-already restarted the TemplateVM, using this command is unlikely to help, and
+On the other hand, if the template is already broken or compromised, it won't hurt to try reverting first.
-you'll likely want to reinstall it from the repository instead. On the other
+Just make sure to **back up** all of your data and changes first!
-hand, if the template is already broken or compromised, it won't hurt to try
-reverting first. Just make sure to **back up** all of your data and changes
-first!
 
 For example, to revert changes to the `fedora-23` TemplateVM:
 
 1. Shut down all VMs based on `fedora-23`.
-2. Shut down `fedora-23`. If you've already just shut it down, do **not** start
+2. Shut down `fedora-23`.
-   it again (see above).
+   If you've already just shut it down, do **not** start it again (see above).
 3. In a dom0 terminal, type:
 
         qvm-revert-template-changes fedora-23
@@ -114,46 +112,63 @@ For example, to revert changes to the `fedora-23` TemplateVM:
 
         qvm-revert-template-changes --force fedora-23
 
-For the technical details about how this command works and the steps it
+For the technical details about how this command works and the steps it performs, see [here](/doc/template-implementation/#rollback-template-changes).
-performs, see [here](/doc/template-implementation/#rollback-template-changes).
 
 Notes on trusting your TemplateVM(s)
 -------------------------------------
 
-As the TemplateVM is used for creating filesystems for other AppVMs, where you actually do the work, it means that the TemplateVM is as trusted as the most trusted AppVM based on this template. In other words, if your template VM gets compromised, e.g. because you installed an application, whose *installer's scripts* were malicious, then *all* your AppVMs (based on this template) will inherit this compromise.
+As the TemplateVM is used for creating filesystems for other AppVMs where you actually do the work, it means that the TemplateVM is as trusted as the most trusted AppVM based on this template.
+In other words, if your template VM gets compromised, e.g. because you installed an application, whose *installer's scripts* were malicious, then *all* your AppVMs (based on this template) will inherit this compromise.
 
 There are several ways to deal with this problem:
 
--   Only install packages from trusted sources -- e.g. from the pre-configured Fedora repositories. All those packages are signed by Fedora, and as we expect that at least the package's installation scripts are not malicious. This is enforced by default (at the [firewall VM level](/doc/firewall/)), by not allowing any networking connectivity in the default template VM, except for access to the Fedora repos.
+-   Only install packages from trusted sources -- e.g. from the pre-configured Fedora repositories.
+    All those packages are signed by Fedora, and we expect that at least the package's installation scripts are not malicious.
+    This is enforced by default (at the [firewall VM level](/doc/firewall/)), by not allowing any networking connectivity in the default template VM, except for access to the Fedora repos.
 
 -   Use *standalone VMs* (see below) for installation of untrusted software packages.
 
--   Use multiple templates (see below) for different classes of domains, e.g. a less trusted template, used for creation of less trusted AppVMs, would get various packages from somehow less trusted vendors, while the template used for more trusted AppVMs will only get packages from the standard Fedora repos.
+-   Use multiple templates (see below) for different classes of domains, e.g. a less trusted template, used for creation of less trusted AppVMs, would get various packages from less trusted vendors, while the template used for more trusted AppVMs will only get packages from the standard Fedora repos.
 
 Some popular questions:
 
--   So, why should we actually trust Fedora repos -- it also contains large amount of third-party software that might buggy, right?
+-   So, why should we actually trust Fedora repos -- it also contains large amount of third-party software that might be buggy, right?
 
-As long as template's compromise is considered, it doesn't really matter whether /usr/bin/firefox is buggy and can be exploited, or not. What matters is whether its *installation* scripts (such as %post in the rpm.spec) are benign or not. Template VM should be used only for installation of packages, and nothing more, so it should never get a chance to actually run the /usr/bin/firefox and got infected from it, in case it was compromised. Also, some of your more trusted AppVMs, would have networking restrictions enforced by the [firewall VM](/doc/firewall/), and again they should not fear this proverbial /usr/bin/firefox being potentially buggy and easy to compromise.
+As far as the template's compromise is concerned, it doesn't really matter whether `/usr/bin/firefox` is buggy and can be exploited, or not.
+What matters is whether its *installation* scripts (such as %post in the rpm.spec) are benign or not.
+Template VM should be used only for installation of packages, and nothing more, so it should never get a chance to actually run `/usr/bin/firefox` and get infected from it, in case it was compromised.
+Also, some of your more trusted AppVMs would have networking restrictions enforced by the [firewall VM](/doc/firewall/), and again they should not fear this proverbial `/usr/bin/firefox` being potentially buggy and easy to compromise.
 
 -   But why trust Fedora?
 
-Because we chose to use Fedora as a vendor for the Qubes OS foundation (e.g. for Dom0 packages and for AppVM packages). We also chose to trust several other vendors, such as Xen.org, kernel.org, and a few others whose software we use in Dom0. We had to trust *somebody* as we are unable to write all the software from scratch ourselves. But there is a big difference in trusting all Fedora packages to be non-malicious (in terms of installation scripts) vs. trusting all those packages are non-buggy and non-exploitable. We certainly do not assume the latter.
+Because we chose to use Fedora as a vendor for the Qubes OS foundation (e.g. for Dom0 packages and for AppVM packages).
+We also chose to trust several other vendors, such as Xen.org, kernel.org, and a few others whose software we use in Dom0.
+We had to trust *somebody* as we are unable to write all the software from scratch ourselves.
+But there is a big difference in trusting all Fedora packages to be non-malicious (in terms of installation scripts) vs. trusting all those packages are non-buggy and non-exploitable.
+We certainly do not assume the latter.
 
 -   So, are the template VMs as trusted as Dom0?
 
-Not quite. Dom0 compromise is absolutely fatal, and it leads to Game Over<sup>TM</sup>. However, a compromise of a template affects only a subset of all your AppVMs (in case you use more than one template, or also some standalone VMs). Also, if your AppVMs are network disconnected, even though their filesystems might get compromised due to the corresponding template compromise, it still would be difficult for the attacker to actually leak out the data stolen in an AppVM. Not impossible (due to existence of cover channels between VMs on x86 architecture), but difficult and slow.
+Not quite.
+Dom0 compromise is absolutely fatal, and it leads to Game Over<sup>TM</sup>.
+However, a compromise of a template affects only a subset of all your AppVMs (in case you use more than one template, or also some standalone VMs).
+Also, if your AppVMs are network disconnected, even though their filesystems might get compromised due to the corresponding template compromise, it still would be difficult for the attacker to actually leak out the data stolen in an AppVM.
+Not impossible (due to existence of cover channels between VMs on x86 architecture), but difficult and slow.
 
 Standalone VMs
 --------------
 
-Standalone VMs have their own copy of the whole filesystem, and thus can be updated and managed on its own. But this means that they take a few GBs on disk, and also that centralized updates do not apply to them.
+Standalone VMs have their own copy of the whole filesystem, and thus can be updated and managed on their own.
+But this means that they take a few GBs on disk, and also that centralized updates do not apply to them.
 
-Sometime it might be convenient to have a VM that has its own filesystem, where you can directly introduce changes, without the need to start/stop the template VM. Such situations include e.g.:
+Sometimes it might be convenient to have a VM that has its own filesystem, where you can directly introduce changes, without the need to start/stop the template VM.
+Such situations include e.g.:
 
--   VMs used for development (devel environments requires a lot of \*-devel packages and specific devel tools)
+-   VMs used for development (devel environments require a lot of \*-devel packages and specific devel tools)
 
--   VMs used for installing untrusted packages. Normally you install digitally signed software from Red Hat/Fedora repositories, and it's reasonable that such software has non malicious *installation* scripts (rpm pre/post scripts). However, when you would like to install some packages form less trusted sources, or unsigned, then using a dedicated (untrusted) standalone VM might be a better way.
+-   VMs used for installing untrusted packages.
+    Normally you install digitally signed software from Red Hat/Fedora repositories, and it's reasonable that such software has non malicious *installation* scripts (rpm pre/post scripts).
+    However, when you would like to install some packages from less trusted sources, or unsigned, then using a dedicated (untrusted) standalone VM might be a better way.
 
 In order to create a standalone VM you can use a command line like this (from console in Dom0):
 
@@ -166,9 +181,14 @@ qvm-create <vmname> --standalone --label <label>
 Using more than one template
 ----------------------------
 
-It's also possible to have more than one template VM in the system. E.g. one could clone the default template using the `qvm-clone` command in Dom0. This allows to have a customized template, e.g. with devel packages, or less trusted apps, shared by some subset of domains. It is important to note that the default template is "system managed" and therefore cannot be backed up using Qubes' built-in backup function. In order to ensure the preservation of your custom settings and the availability of a "known-good" backup template, you may wish to clone the default system template and use your clone as the default template for your AppVMs.
+It's also possible to have more than one template VM in the system.
+E.g. one could clone the default template using the `qvm-clone` command in Dom0.
+This allows to have a customized template, e.g. with devel packages, or less trusted apps, shared by some subset of domains.
+It is important to note that the default template is "system managed" and therefore cannot be backed up using Qubes' built-in backup function.
+In order to ensure the preservation of your custom settings and the availability of a "known-good" backup template, you may wish to clone the default system template and use your clone as the default template for your AppVMs.
 
-When you create a new domain you can choose which template this VM should be based on. If you use command line, you should use the `--template` switch:
+When you create a new domain you can choose which template this VM should be based on.
+If you use command line, you should use the `--template` switch:
 
 ~~~
 qvm-create <vmname> --template <templatename> --label <label>
@@ -177,52 +197,103 @@ qvm-create <vmname> --template <templatename> --label <label>
 Temporarily allowing networking for software installation
 ---------------------------------------------------------
 
-Some third-party applications cannot be installed using the standard yum repositories, and need to be manually downloaded and installed. When the installation requires internet connection to access third-party repositories, it will naturally fail when run in a Template VM because the default firewall rules for templates only allow connections to standard yum repositories. So it is necessary to modify firewall rules to allow less restrictive internet access for the time of the installation, if one really wants to install those applications into a template. As soon as software installation is completed, firewall rules should be returned back to the default state. The user should decided by themselves whether such third-party applications should be equally trusted as the ones that come from the standard Fedora signed repositories and whether their installation will not compromise the default Template VM, and potentially consider installing them into a separate template or a standalone VM (in which case the problem of limited networking access doesn't apply by default), as described above.
+Some third-party applications cannot be installed using the standard yum repositories, and need to be manually downloaded and installed.
+When the installation requires internet connection to access third-party repositories, it will naturally fail when run in a Template VM because the default firewall rules for templates only allow connections from package managers.
+So it is necessary to modify firewall rules to allow less restrictive internet access for the time of the installation, if one really wants to install those applications into a template.
+As soon as software installation is completed, firewall rules should be returned back to the default state.
+The user should decide by themselves whether such third-party applications should be equally trusted as the ones that come from the standard Fedora signed repositories and whether their installation will not compromise the default Template VM, and potentially consider installing them into a separate template or a standalone VM (in which case the problem of limited networking access doesn't apply by default), as described above.
 
-Updates proxy (some content applies only to versions earlier than R3.2)
+Updates proxy
 -------------
 
-Updates proxy is a service which filter http access to allow access to only something that looks like yum or apt repository. This is meant to mitigate user errors (like using browser in the template VM), rather than some real isolation. It is done with http proxy instead of simple firewall rules because it is hard to list all the repository mirrors (and keep that list up to date). The proxy is used only to filter the traffic, not to cache anything.
+Updates proxy is a service which allows access only from package managers.
+This is meant to mitigate user errors (like using browser in the template VM), rather than some real isolation.
+It is done with http proxy (tinyproxy) instead of simple firewall rules because it is hard to list all the repository mirrors (and keep that list up to date).
+The proxy is used only to filter the traffic, not to cache anything.
 
-The proxy is running in selected VMs (by default all the NetVMs (1)) and intercept traffic directed to 10.137.255.254:8082. Thanks to such configuration all the VMs can use the same proxy address, and if there is a proxy on network path, it will handle the traffic (of course when firewall rules allows that). If the VM is configured to have access to the updates proxy (2), the startup scripts will automatically configure dnf to really use the proxy (3). Also access to updates proxy is independent of any other firewall settings (VM will have access to updates proxy, even if policy is set to block all the traffic).
+The proxy is running in selected VMs (by default all the NetVMs (1)) and intercepts traffic directed to 10.137.255.254:8082.
+Thanks to such configuration all the VMs can use the same proxy address, and if there is a proxy on network path, it will handle the traffic (of course when firewall rules allow that).
+If the VM is configured to have access to the updates proxy (2), the startup scripts will automatically configure dnf to really use the proxy (3).
+Also access to updates proxy is independent of any other firewall settings (VM will have access to updates proxy, even if policy is set to block all the traffic).
 
-(1) Services tab -\> "qubes-yum-proxy" entry; check qvm-service manual for details
+There are two services ([qvm-service](https://www.qubes-os.org/doc/dom0-tools/qvm-service/), [service framework](https://www.qubes-os.org/doc/qubes-service/)):
 
-(2) Firewall tab -\> Allow connections to Updates Proxy; this setting works immediately (once OK is clicked)
+1. qubes-updates-proxy (and its deprecated name: qubes-yum-proxy) - a service providing a proxy for templates - by default enabled in NetVMs (especially: sys-net)
+2. updates-proxy-setup (and its deprecated name: yum-proxy-setup) - use a proxy provided by another VM (instead of downloading updates directly), enabled by default in all templates
 
-(3) Services tab -\> "yum-proxy-setup" entry; this setting works at next VM startup
+This is generally the same in R3.2 and R4.0 - in both cases both the old and new names work.
+And in both cases defaults listed above are applied if the service is not explicitly listed in services tab.
 
-### Technical details
+### Technical details (R4.0)
 
-1.  Updates proxy: It is running as "qubes-yum-proxy" service. Startup script of this service setup firewall rule to intercept proxy traffic:
+Instead of using a network connection like in R3.2, R4.0 uses RPC/qrexec.
+The proxy is configured in qrexec policy: `/etc/qubes-rpc/policy/qubes.UpdatesProxy`.
+By default this is set to sys-net and/or sys-whonix, depending on firstboot choices.
+This new design allows for templates to be updated even when they are not connected to any netvm.
+
+
+Example policy file in R4.0 (with whonix installed, but not set as default updatevm for all templates):
+```
+# any VM with tag `whonix-updatevm` should use `sys-whonix`; this tag is added to `whonix-gw` and `whonix-ws` during installation and is preserved during template clone
+$tag:whonix-updatevm $default allow,target=sys-whonix
+$tag:whonix-updatevm $anyvm deny
+
+# other templates use sys-net
+$type:TemplateVM $default allow,target=sys-net
+$anyvm $anyvm deny
+```
+
+### Technical details (R3.2)
+
+The proxy is running in selected VMs (by default all the NetVMs).
+Thanks to such configuration all VMs can use the same proxy address, and if there is a proxy on network path, it will handle the traffic (of course when firewall rules allow that).
+The first proxy on the network path according to the template's netvm setting will be used.
+If the VM is configured to have access to the updates proxy (1), the startup scripts will automatically configure dnf to use the proxy.
+Also access to updates proxy is independent of any other firewall settings (VM will have access to updates proxy, even if the policy is set to block all the traffic).
+
+(1) Firewall tab -\> Allow connections to Updates Proxy; this setting works immediately (once OK is clicked)
+
+1.  Updates proxy: It is running as "qubes-updates-proxy" service.
+    Startup script of this service sets up a firewall rule to intercept traffic directed to 10.137.255.254:8082:
 
     ~~~
     iptables -t nat -A PR-QBS-SERVICES -d 10.137.255.254/32 -i vif+ -p tcp -m tcp --dport 8082 -j REDIRECT
     ~~~
 
-1.  VM using the proxy service Startup script (qubes-misc-post service) configure yum using /etc/yum.conf.d/qubes-proxy.conf file. It can either contain
+2.  VMs using the proxy service Startup script (updates-proxy-setup or qubes-misc-post service) configure
+dnf using `/etc/yum.conf.d/qubes-proxy.conf` file.
+    It can either contain
 
     ~~~
     proxy=http://10.137.255.254:8082/
     ~~~
 
-    line, or be empty. Note that this file is specifically included from main yum.conf, yum does not support real conf.d configuration style...
+    line, or be empty. Note that this file is specifically included from main yum.conf, dnf does not support real conf.d configuration style...
 
 Note on treating AppVM's root filesystem non-persistence as a security feature
 ------------------------------------------------------------------------------
 
-As explained above, any AppVM that is based on a Template VM (i.e. which is not a Standalone VM) has its root filesystem non-persistent across the VM reboots. In other words whatever changes the VM makes (or the malware running in this AppVM makes) to its root filesystem, are automatically discarded whenever one restarts the AppVM. This might seem like an excellent anti-malware mechanism to be used inside the AppVM...
+As explained above, any AppVM that is based on a Template VM (i.e. which is not a Standalone VM) has its root filesystem non-persistent across the VM reboots.
+In other words whatever changes the VM makes (or the malware running in this AppVM makes) to its root filesystem, are automatically discarded whenever one restarts the AppVM.
+This might seem like an excellent anti-malware mechanism to be used inside the AppVM...
 
-However, one should be careful with treating this property as a reliable way to keep the AppVM malware-free. This is because the non-persistence, in case of normal AppVMs, applies only to the root filesystem and not to the user filesystem (on which the `/home`, `/rw`, and `/usr/local` are stored) for obvious reasons. It is possible that malware, especially malware that could be specifically written to target a Qubes-based AppVMs, could install its hooks inside the user home directory files only. Examples of obvious places for such hooks could be: `.bashrc`, the Firefox profile directory which contains the extensions, or some PDF or DOC documents that are expected to be opened by the user frequently (assuming the malware found an exploitable bug in the PDF or DOC reader), and surely many others places, all in the user's home directory.
+However, one should be careful with treating this property as a reliable way to keep the AppVM malware-free.
+This is because the non-persistence, in the case of normal AppVMs, applies only to the root filesystem and not to the user filesystem (on which the `/home`, `/rw`, and `/usr/local` are stored) for obvious reasons.
+It is possible that malware, especially malware that could be specifically written to target a Qubes-based AppVMs, could install its hooks inside the user home directory files only.
+Examples of obvious places for such hooks could be: `.bashrc`, the Firefox profile directory which contains the extensions, or some PDF or DOC documents that are expected to be opened by the user frequently (assuming the malware found an exploitable bug in the PDF or DOC reader), and surely many others places, all in the user's home directory.
 
-One advantage of the non-persistent rootfs though, is that the malware is still inactive before the user's filesystem gets mounted and "processed" by system/applications, which might theoretically allow for some scanning programs (or a skilled user) to reliably scan for signs of infections of the AppVM. But, of course, the problem of finding malware hooks in general is hard, so this would work likely only for some special cases (e.g. an AppVM which doesn't use Firefox, as otherwise it would be hard to scan the Firefox profile directory reliably to find malware hooks there). Also note that the user filesystem's metadata might got maliciously modified by malware in order to exploit a hypothetical bug in the AppVM kernel whenever it mounts the malformed filesystem. However, these exploits will automatically stop working (and so the infection might be cleared automatically) after the hypothetical bug got patched and the update applied (via template update), which is an exceptional feature of Qubes OS.
+One advantage of the non-persistent rootfs though, is that the malware is still inactive before the user's filesystem gets mounted and "processed" by system/applications, which might theoretically allow for some scanning programs (or a skilled user) to reliably scan for signs of infections of the AppVM.
+But, of course, the problem of finding malware hooks in general is hard, so this would work likely only for some special cases (e.g. an AppVM which doesn't use Firefox, as otherwise it would be hard to scan the Firefox profile directory reliably to find malware hooks there).
+Also note that the user filesystem's metadata might got maliciously modified by malware in order to exploit a hypothetical bug in the AppVM kernel whenever it mounts the malformed filesystem.
+However, these exploits will automatically stop working (and so the infection might be cleared automatically) after the hypothetical bug got patched and the update applied (via template update), which is an exceptional feature of Qubes OS.
 
-Also note that Disposable VMs do not have persistent user filesystem, and so they start up completely "clean" every time. Note the word "clean" means in this context: the same as their template filesystem, of course.
+Also note that Disposable VMs do not have persistent user filesystem, and so they start up completely "clean" every time.
+Note the word "clean" means in this context: the same as their template filesystem, of course.
 
 RPMFusion for a Fedora TemplateVM
 ---------------------------------
 
-If you would like to enable the [RPM Fusion](http://rpmfusion.org/) repository: open a Terminal of the TemplateVM and type the following commands: 
+If you would like to enable the [RPM Fusion](http://rpmfusion.org/) repository, open a Terminal of the TemplateVM and type the following commands: 
 
 ~~~
 sudo dnf config-manager --set-enabled rpmfusion-free rpmfusion-nonfree

common-tasks/tips-and-tricks.md

@@ -10,9 +10,9 @@ This section provides user suggested tips that aim to increase Qubes OS usabilit
 
 Opening links in your preferred AppVM
 -------------------------------------
-To increase both security and usability you can set an AppVM so that it automatically opens any link in an different AppVM of your choice. You can do this for example in the email AppVM, in this way you avoid to make mistakes like opening links in it. to learn more you can check [security guidelines](/doc/security-guidelines/) and [security goals](/security/goals/).
+To increase both security and usability you can set an AppVM so that it automatically opens any link in an different AppVM of your choice. You can do this for example in the email AppVM, in this way you avoid to make mistakes like opening links in it. To learn more you can check [security guidelines](/doc/security-guidelines/) and [security goals](/security/goals/).
 
-The command `qvm-open-in-vm` lets you open a document or a URL in another VM, it takes two parameters: vmname and filename.
+The command `qvm-open-in-vm` lets you open a document or a URL in another VM. It takes two parameters: vmname and filename.
 
 For example, if you launch this command from your email AppVM:
 
@@ -20,7 +20,7 @@ For example, if you launch this command from your email AppVM:
 
 it will open duckduckgo.com in the `untrusted` AppVM (after you confirmed the request).
 
-If you want this to happen automatically you can creatte a .desktop file that advertises itself as a handler for http/https links, and then setting this as your default browser.
+If you want this to happen automatically you can create a .desktop file that advertises itself as a handler for http/https links, and then set this as your default browser.
 
 Open a text editor and copy and paste this into it:
 
@@ -46,9 +46,9 @@ Preventing data leaks
 ---------------------
 First make sure to read [Understanding and Preventing Data Leaks](/doc/data-leaks/) section to understand the limits of this tip.
 
-Suppose that you have a not so trusted enviroment, for example a Windows VM, an application that track and report it's usage or you simply want to protect your data.
+Suppose that you have within a not so trusted enviroment - for example, a Windows VM - an application that tracks and reports its usage, or you simply want to protect your data.
 
-Start Windows template VM (which has no user data), install/upgrade apps; then start Windows AppVM (with data) in offline mode. So, if you worry (hypothetically) that your Windows or app updater might want to send your data away, this Qubes OS trick will prevent this.
+Start the Windows TemplateVM (which has no user data), install/upgrade apps; then start Windows AppVM (with data) in offline mode. So, if you worry (hypothetically) that your Windows or app updater might want to send your data away, this Qubes OS trick will prevent this.
 This applies also to any TemplateBasedVM relative to its parent TemplateVM, but the privacy risk is especially high in the case of Windows.
 
 Credit: [Joanna Rutkovska](https://twitter.com/rootkovska/status/832571372085850112)

common-tasks/usb.md

@@ -22,84 +22,68 @@ Using and Managing USB Devices
 ==============================
 
 How to attach USB drives
-------------------------
+----------
 
-(**Note:** In the present context, the term "USB drive" denotes any
+(**Note:** In the present context, the term "USB drive" denotes any [USB mass storage device][mass-storage].
-[USB mass storage device][mass-storage]. In addition to smaller flash memory
+In addition to smaller flash memory sticks, this includes things like USB external hard drives.)
-sticks, this includes things like USB external hard drives.)
 
-Qubes OS supports the ability to attach a USB drive (or just one or more of its
+Qubes OS supports the ability to attach a USB drive (or just one or more of its partitions) to any qube easily, no matter which qube actually handles the USB controller.
-partitions) to any qube easily, no matter which qube actually handles the USB
-controller.
 
 ### R4.0 ###
 
-USB drive mounting is integrated into the Devices Widget. This is the tool tray
+USB drive mounting is integrated into the Devices Widget.
-icon with a yellow square located in the top right of your screen by default.
+This is the tool tray icon with a yellow square located in the top right of your screen by default.
-Simply insert
+Simply insert your USB drive and click on the widget.
-your USB drive and click on the widget. You will see multiple entries for your
+You will see multiple entries for your USB drive; typically, `sys-usb:sda`, `sys-usb:sda1`, and `sys-usb:2-1` for example.
-USB drive; typically, `sys-usb:sda`, `sys-usb:sda1`, and `sys-usb:2-1` for example.
+The simplest (but slightly less secure, see note below about attaching individual partitions) option is to attach the entire block drive.
-The simplest (but slightly less secure, see note below about attaching individual
+In our example, this is `sda`, so hover over it.
-partitions) option is to attach the entire block drive. In our example, this is `sda`,
-so hover over it.
 This will pop up a submenu showing running VMs to which the USB drive can be connected.
 Click on one and your USB drive will be attached!
 
-Note that attaching individual partitions can be slightly more secure because it doesn't
+Note that attaching individual partitions can be slightly more secure because it doesn't force the target AppVM to parse the partition table.
-force the target AppVM to parse the partition table. However, it often means the 
+However, it often means the AppVM won't detect the new partition and you will need to manually mount it inside the AppVM.
-AppVM won't detect the new partition and you will need to manually mount it inside
+See below for more detailed steps.
-the AppVM. See below for more detailed steps.
     
-The command-line tool you may use to mount whole USB drives or their partitions
+The command-line tool you may use to mount whole USB drives or their partitions is `qvm-block`.
-is `qvm-block`. This tool can be used to assign a USB drive to a qube as
+This tool can be used to assign a USB drive to a qube as follows:
-follows:
 
  1. Insert your USB drive.
 
- 2. In a dom0 console (running as a normal user), list all available block
+ 2. In a dom0 console (running as a normal user), list all available block devices:
-    devices:
 
         qvm-block
 
-    This will list all available block devices connected to any USB controller
+    This will list all available block devices connected to any USB controller in your system, no matter which qube hosts the controller.
-    in your system, no matter which qube hosts the controller. The name of the
+    The name of the qube hosting the USB controller is displayed before the colon in the device name.
-    qube hosting the USB controller is displayed before the colon in the device
+    The string after the colon is the name of the device used within the qube, like so:
-    name. The string after the colon is the name of the device used within the
-    qube, like so:
 
         dom0:sdb1     Cruzer () 4GiB
         
         usbVM:sdb1    Disk () 2GiB
 
-    **Note:** If your device is not listed here, you may refresh the list by
+    **Note:** If your device is not listed here, you may refresh the list by calling from the qube to which the device is connected (typically `sys-usb`):
-    calling from the qube to which the device is connected (typically `sys-usb`):
 
         sudo udevadm trigger --action=change
 
- 3.  Assuming your USB drive is attached to `sys-usb` and is `sdb`, we attach the
+ 3.  Assuming your USB drive is attached to `sys-usb` and is `sdb`, we attach the device to a qube with the name `personal` like so:
-     device to a qube with the name `personal` like so:
 
          qvm-block attach personal sys-usb:sdb
 
-     This will attach the device to the qube as `/dev/xvdi` if that name is not
+     This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc.
-     already taken by another attached device, or `/dev/xvdj`, etc.
 
-     You may also mount one partition at a time by using the same command with
+     You may also mount one partition at a time by using the same command with the partition number after `sdb`.
-     the partition number after `sdb`.
 
- 4.  The USB drive is now attached to the qube. If using a default qube, you may
+ 4.  The USB drive is now attached to the qube.
-     open the Nautilus file manager in the qube, and your drive should be
+     If using a default qube, you may open the Nautilus file manager in the qube, and your drive should be visible in the **Devices** panel on the left.
-     visible in the **Devices** panel on the left. If you've attached a single
+     If you've attached a single partition, you may need to manually mount before it becomes visible:
-     partition, you may need to manually mount before it becomes visible:
      ```
      cd ~
      mkdir mnt
      sudo mount /dev/xvdi mnt
      ```
 
- 5.  When you finish using your USB drive, click the eject button or right-click
+ 5.  When you finish using your USB drive, click the eject button or right-click and select **Unmount**.
-     and select **Unmount**. If you've manually mounted a single partition
+     If you've manually mounted a single partition in the above step, use:
-     in the above step, use:
      `sudo umount mnt`
 
  6.  In a dom0 console, detach the stick
@@ -110,75 +94,62 @@ follows:
 
 ### R3.2 ###
 
-USB drive mounting is integrated into the Qubes VM Manager GUI. Simply insert
+USB drive mounting is integrated into the Qubes VM Manager GUI.
-your USB drive, right-click on the desired qube in the Qubes VM Manager list,
+Simply insert your USB drive, right-click on the desired qube in the Qubes VM Manager list, click **Attach/detach block devices**, and select your desired action and device.
-click **Attach/detach block devices**, and select your desired action and
+However, this only works for the whole device.
-device. This, however, only works for the whole device. If you would like to
+If you would like to attach individual partitions, you must use the command-line tool.
-attach individual partitions, you must use the command-line tool.
 
-Note that attaching individual partitions can be slightly more secure because it doesn't
+Note that attaching individual partitions can be slightly more secure because it doesn't force the target AppVM to parse the partition table.
-force the target AppVM to parse the partition table. However, it often means the 
+However, it often means the AppVM won't detect the new partition and you will need to manually mount it inside the AppVM.
-AppVM won't detect the new partition and you will need to manually mount it inside
+See below for more detailed steps.
-the AppVM. See below for more detailed steps.
     
-The command-line tool you may use to mount whole USB drives or their partitions
+The command-line tool you may use to mount whole USB drives or their partitions is `qvm-block`.
-is `qvm-block`. This tool can be used to assign a USB drive to a qube as
+This tool can be used to assign a USB drive to a qube as follows:
-follows:
 
  1. Insert your USB drive.
 
- 2. In a dom0 console (running as a normal user), list all available block
+ 2. In a dom0 console (running as a normal user), list all available block devices:
-    devices:
 
         qvm-block
 
-    This will list all available block devices connected to any USB controller
+    This will list all available block devices connected to any USB controller in your system, no matter which qube hosts the controller.
-    in your system, no matter which qube hosts the controller. The name of the
+    The name of the qube hosting the USB controller is displayed before the colon in the device name.
-    qube hosting the USB controller is displayed before the colon in the device
+    The string after the colon is the name of the device used within the qube, like so:
-    name. The string after the colon is the name of the device used within the
-    qube, like so:
 
         dom0:sdb1     Cruzer () 4GiB
         
         usbVM:sdb1    Disk () 2GiB
 
-    **Note:** If your device is not listed here, you may refresh the list by
+    **Note:** If your device is not listed here, you may refresh the list by calling from the qube to which the device is connected (typically `sys-usb`):
-    calling from the qube to which the device is connected (typically `sys-usb`):
 
         sudo udevadm trigger --action=change
 
- 3.  Assuming your USB drive is attached to `sys-usb` and is `sdb`, we attach the
+ 3.  Assuming your USB drive is attached to `sys-usb` and is `sdb`, we attach the device to a qube with the name `personal` like so:
-     device to a qube with the name `personal` like so:
 
          qvm-block -a personal sys-usb:sdb
 
-     This will attach the device to the qube as `/dev/xvdi` if that name is not
+     This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc.
-     already taken by another attached device, or `/dev/xvdj`, etc.
 
-     You may also mount one partition at a time by using the same command with
+     You may also mount one partition at a time by using the same command with the partition number after `sdb`.
-     the partition number after `sdb`. This is slightly more secure because it
+     This is slightly more secure because it does not force the target AppVM to parse the partition table.
-     does not force the target AppVM to parse the partition table.
 
-     **Warning:** when working with single partitions, it is possible to assign
+     **Warning:** when working with single partitions, it is possible to assign the same partition to multiple qubes.
-     the same partition to multiple qubes. For example, you could attach `sdb1`
+     For example, you could attach `sdb1` to qube1 and then `sdb` to qube2.
-     to qube1 and then `sdb` to qube2. It is up to the user not to make this
+     It is up to the user not to make this mistake.
-     mistake. The Xen block device framework currently does not provide an easy
+     The Xen block device framework currently does not provide an easy way around this.
-     way around this. Point 2 of [this comment on issue 1072][1072-comm2] gives
+     Point 2 of [this comment on issue 1072][1072-comm2] gives details about this.
-     details about this.
 
- 4.  The USB drive is now attached to the qube. If using a default qube, you may
+ 4.  The USB drive is now attached to the qube.
-     open the Nautilus file manager in the qube, and your drive should be
+     If using a default qube, you may open the Nautilus file manager in the qube, and your drive should be visible in the **Devices** panel on the left.
-     visible in the **Devices** panel on the left. If you've attached a single
+     If you've attached a single partition, you may need to manually mount before it becomes visible:
-     partition, you may need to manually mount before it becomes visible:
      ```
      cd ~
      mkdir mnt
      sudo mount /dev/xvdi mnt
      ```
    
- 5.  When you finish using your USB drive, click the eject button or right-click
+ 5.  When you finish using your USB drive, click the eject button or right-click and select **Unmount**.
-     and select **Unmount**. If you've manually mounted a single partition
+     If you've manually mounted a single partition in the above step, use:
-     in the above step, use:
      `sudo umount mnt`
 
  6.  In a dom0 console, detach the stick
@@ -192,84 +163,69 @@ follows:
  7.  You may now remove the device.
 
 **Warning:** Do not remove the device before detaching it from the VM!
-Otherwise, you will not be able to attach it anywhere later. See issue [1082]
+Otherwise, you will not be able to attach it anywhere later.
-for details.
+See issue [1082] for details.
 
-If the device does not appear in Nautilus, you will need to mount it
+If the device does not appear in Nautilus, you will need to mount it manually.
-manually. The device will show up as `/dev/xvdi` (or `/dev/xvdj` if there is
+The device will show up as `/dev/xvdi` (or `/dev/xvdj` if there is already one device attached -- if two, `/dev/xvdk`, and so on).
-already one device attached -- if two, `/dev/xvdk`, and so on).
 
 
 ### What if I removed the device before detaching it from the VM? (R3.2) ###
 
-Currently (until issue [1082] gets implemented), if you remove the device
+Currently (until issue [1082] gets implemented), if you remove the device before detaching it from the qube, Qubes OS (more precisely, `libvirtd`) will think that the device is still attached to the qube and will not allow attaching further devices under the same name.
-before detaching it from the qube, Qubes OS (more precisely, `libvirtd`) will
+The easiest way to recover from such a situation is to reboot the qube to which the device was attached.
-think that the device is still attached to the qube and will not allow attaching
+If this isn't an option, you can manually recover from the situation by following these steps:
-further devices under the same name. The easiest way to recover from such a
-situation is to reboot the qube to which the device was attached, but if this
-isn't an option, you can manually recover from the situation by following these
-steps:
 
- 1. Physically connect the device back. You can use any device as long as it
+ 1. Physically connect the device back.
-    will be detected under the same name (for example, `sdb`).
+    You can use any device as long as it will be detected under the same name (for example, `sdb`).
 
- 2. Attach the device manually to the same VM using the `xl block-attach`
+ 2. Attach the device manually to the same VM using the `xl block-attach` command.
-    command. It is important to use the same "frontend" device name (by default,
+    It is important to use the same "frontend" device name (by default, `xvdi`).
-    `xvdi`). You can get it from the `qvm-block` listing:
+    You can get it from the `qvm-block` listing:
 
         [user@dom0 ~]$ qvm-block
         sys-usb:sda DataTraveler_2.0 () 246 MiB (attached to 'testvm' as 'xvdi')
         [user@dom0 ~]$ sudo xl block-attach testvm phy:/dev/sda backend=sys-usb xvdi
 
-    In above example, all `xl block-attach` parameters can be deduced from the
+    In above example, all `xl block-attach` parameters can be deduced from the output of `qvm-block`.
-    output of `qvm-block`. In order:
+    In order:
 
-    * `testvm` - name of target qube to which device was attached - listed in
+    * `testvm` - name of target qube to which device was attached - listed in brackets by `qvm-block` command
-      brackets by `qvm-block` command
+    * `phy:/dev/sda` - physical path at which device appears in source qube (just after source qube name in `qvm-block` output)
-    * `phy:/dev/sda` - physical path at which device appears in source qube
+    * `backend=sys-usb` - name of source qube, can be omitted in the case of dom0
-      (just after source qube name in `qvm-block` output)
+    * `xvdi` - "frontend" device name (listed at the end of line in `qvm-block` output)
-    * `backend=sys-usb` - name of source qube, can be omitted in case of dom0
-    * `xvdi` - "frontend" device name (listed at the end of line in `qvm-block`
-      output)
 
- 3. Now properly detach the device, either using Qubes VM Manager or the
+ 3. Now properly detach the device, either using Qubes VM Manager or the `qvm-block -d` command.
-    `qvm-block -d` command.
 
 
 Attaching a single USB device to a qube (USB passthrough)
 ---------------------------------------------------------
 
-Starting with Qubes 3.2, it is possible to attach a single USB device to any
+Starting with Qubes 3.2, it is possible to attach a single USB device to any Qube.
-Qube. While this is useful feature, it should be used with care, because there
+While this is a useful feature, it should be used with care, because there are [many security implications][usb-challenges] from using USB devices and USB passthrough will **expose your target qube** to most of them.
-are [many security implications][usb-challenges] from using USB devices and USB
+If possible, use a method specific for particular device type (for example, block devices described above), instead of this generic one.
-passthrough will **expose your target qube** for most of them. If possible, use 
-method specific for particular device type (for example block devices described
-above), instead of this generic one.
 
 ### Installation of qubes-usb-proxy ###
 [installation]: #installation-of-qubes-usb-proxy
 
-To use this feature, you need to install [`qubes-usb-proxy`][qubes-usb-proxy] package in the
+To use this feature, you need to install [`qubes-usb-proxy`][qubes-usb-proxy] package in the templates used for the USB qube and qubes you want to connect USB devices to.
-templates used for the USB qube and qubes you want to connect USB devices to. Note
+Note you cannot pass through devices from dom0 (in other words: USB VM is required).
-you cannot pass through devices from dom0 (in other words: USB VM is required).
 `qubes-usb-proxy` should be installed by default in the template VM.
-However, if you receive this error: `ERROR: qubes-usb-proxy not installed in the VM`,
+However, if you receive this error: `ERROR: qubes-usb-proxy not installed in the VM`, you can install the `qubes-usb-proxy` with the package manager in the VM you want to attach the USB device to.
-you can install the `qubes-usb-proxy` with the package manager in the VM
-you want to attach the USB device to.
 
 - Fedora: `sudo dnf install qubes-usb-proxy`
 - Debian/Ubuntu: `sudo apt-get install qubes-usb-proxy`
 
 ### Usage of qubes-usb-proxy (R4.0) ###
 
-This feature is also available from the Devices Widget. This is the tool tray
+This feature is also available from the Devices Widget.
-icon with a yellow square located in the top right of your screen by default.
+This is the tool tray icon with a yellow square located in the top right of your screen by default.
-Simply insert
+Simply insert your USB device and click on the widget.
-your USB device and click on the widget. You will see an entry for your device
+You will see an entry for your device such as `sys-usb:2-5 - 058f_USB_2.0_Camera` for example.
-such as `sys-usb:2-5 - 058f_USB_2.0_Camera` for example.
 Hover over it.
 This will pop up a submenu showing running VMs to which the USB device can be connected.
-Click on one and your device will be attached! You may also use the command line:
+Click on one and your device will be attached!
+You may also use the command line:
 
 Listing available USB devices:
 
@@ -288,16 +244,16 @@ Attaching selected USB device:
     sys-usb:2-1     03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
 
 Now, you can use your USB device (camera in this case) in the `conferences` qube.
-If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead,
+If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section][installation].
-please refer to the [Installation Section][installation].
 
-When you finish, detach the device. This can be done in the GUI by
+When you finish, detach the device.
-clicking on the Devices Widget. You will see an entry in bold for your device
+This can be done in the GUI by clicking on the Devices Widget.
-such as **`sys-usb:2-5 - 058f_USB_2.0_Camera`**.
+You will see an entry in bold for your device such as **`sys-usb:2-5 - 058f_USB_2.0_Camera`**.
 Hover over it.
-This will pop up a submenu showing running VMs. The one which your device is
+This will pop up a submenu showing running VMs.
-connected to will have an Eject button next to it. Click that and your device
+The one to which your device is connected will have an Eject button next to it.
-will be detached. You may also use the command line:
+Click that and your device will be detached.
+You may also use the command line:
 
     [user@dom0 ~]$ qvm-usb detach conferences sys-usb:2-5
     [user@dom0 ~]$ qvm-usb
@@ -324,8 +280,7 @@ Attaching selected USB device:
     sys-usb:2-1     03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
 
 Now, you can use your USB device (camera in this case) in the `conferences` qube.
-If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead,
+If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section][installation].
-please refer to the [Installation Section][installation].
 
 When you finish, detach the device:
 
@@ -340,76 +295,62 @@ This feature is not available in Qubes Manager.
 Creating and Using a USB qube
 -----------------------------
 
-**Warning:** This has the potential to prevent you from connecting a keyboard to Qubes via USB. There are problems with doing this in an encrypted install (LUKS). If you find yourself in this situation, see this [issue][2270-comm23].
+**Warning:** This has the potential to prevent you from connecting a keyboard to Qubes via USB.
+There are problems with doing this in an encrypted install (LUKS).
+If you find yourself in this situation, see this [issue][2270-comm23].
 
-Connecting an untrusted USB device to dom0 is a security risk since dom0,
+The connection of an untrusted USB device to dom0 is a security risk since dom0, like almost every OS, reads partition tables automatically.
-like almost every OS, reads partition tables automatically. The whole
+The whole USB stack is put to work to parse the data presented by the USB device in order to determine if it is a USB mass storage device, to read its configuration, etc.
-USB stack is put to work to parse the data presented by the USB device in order
-to determine if it is a USB mass storage device, to read its configuration, etc.
 This happens even if the drive is then assigned and mounted in another qube.
 
 To avoid this risk, it is possible to prepare and utilize a USB qube.
 
-A USB qube acts as a secure handler for potentially malicious USB devices,
+A USB qube acts as a secure handler for potentially malicious USB devices, preventing them from coming into contact with dom0 (which could otherwise be fatal to the security of the whole system).
-preventing them from coming into contact with dom0 (which could otherwise be
+With a USB qube, every time you connect an untrusted USB drive to a USB port managed by that USB controller, you will have to attach it to the qube in which you wish to use it (if different from the USB qube itself), either by using Qubes VM Manager or the command line (see instructions above).
-fatal to the security of the whole system). With a USB qube, every time you
+The USB controller may be assigned on the **Devices** tab of a qube's settings page in Qubes VM Manager or by using the [qvm-pci][Assigning Devices] command.
-connect an untrusted USB drive to a USB port managed by that USB controller, you
+For guidance on finding the correct USB controller, see [here][usb-controller].
-will have to attach it to the qube in which you wish to use it (if different
+You can create a USB qube using the management stack by performing the following steps as root in dom0:
-from the USB qube itself), either by using Qubes VM Manager or the command line
-(see instructions above). The USB controller may be assigned on the **Devices** tab of a
-qube's settings page in Qubes VM Manager or by using the
-[qvm-pci][Assigning Devices] command. For guidance on finding the correct USB
-controller, see [here][usb-controller].
-You can create a USB qube using the management stack by performing the following
-as root in dom0:
 
     sudo qubesctl state.sls qvm.sys-usb
 
 Alternatively, you can create a USB qube manually as follows:
 
- 1.  Read the [Assigning Devices] page to learn how to list and identify your
+ 1.  Read the [Assigning Devices] page to learn how to list and identify your USB controllers.
-     USB controllers. Carefully check whether you have a USB controller that
+     Carefully check whether you have a USB controller that would be appropriate to assign to a USB qube.
-     would be appropriate to assign to a USB qube. Note that it should have no
+     Note that it should be free of input devices, programmable devices, and any other devices that must be directly available to dom0.
-     input devices, programmable devices, and any other devices that must be
+     If you find a free controller, note its name and proceed to step 2.
-     directly available to dom0. If you find a free controller, note its name
+ 2.  Create a new qube.
-     and proceed to step 2.
+     Give it an appropriate name and color label (recommended: `sys-usb`, red).
- 2.  Create a new qube. Give it an appropriate name and color label
+     If you need to attach a networking device, it might make sense to create a NetVM.
-     (recommended: `sys-usb`, red). If you need to attach a networking device,
+     If not, an AppVM might make more sense.
-     it might make sense to create a NetVM. If not, an AppVM might make more
+     (The default `sys-usb` is a NetVM.)
-     sense. (The default `sys-usb` is a NetVM.)
+ 3.  In the qube's settings, go to the "Devices" tab.
- 3.  In the qube's settings, go to the "Devices" tab. Find the USB controller
+     Find the USB controller that you identified in step 1 in the "Available" list.
-     that you identified in step 1 in the "Available" list. Move it to the
+     Move it to the "Selected" list.
-     "Selected" list.
 
-     **Caution:** By assigning a USB controller to a USB qube, it will no longer
+     **Caution:** By assigning a USB controller to a USB qube, it will no longer be available to dom0.
-     be available to dom0. This can make your system unusable if, for example,
+     This can make your system unusable if, for example, you have only one USB controller, and you are running Qubes off of a USB drive.
-     you have only one USB controller, and you are running Qubes off of a USB
-     drive.
 
- 4.  Click "OK." Restart the qube.
+ 4.  Click `OK`.
- 5.  Recommended: Check the box on the "Basic" tab which says "Start VM
+     Restart the qube.
-     automatically on boot." (This will help to mitigate attacks in which
+ 5.  Recommended: Check the box on the "Basic" tab which says "Start VM automatically on boot".
-     someone forces your system to reboot, then plugs in a malicious USB
+     (This will help to mitigate attacks in which someone forces your system to reboot, then plugs in a malicious USB device.)
-     device.)
 
 If the USB qube will not start, see [here][faq-usbvm].
 
 How to hide all USB controllers from dom0
 -----------------------------------------
 
-If you create a USB qube manually, there will be a brief period of time during the
+If you create a USB qube manually, there will be a brief period of time during the boot process when dom0 will be exposed to your USB controllers (and any attached devices).
-boot process during which dom0 will be exposed to your USB controllers (and any
+This is a potential security risk, since even brief exposure to a malicious USB device could result in dom0 being compromised.
-attached devices). This is a potential security risk, since even brief exposure
+There are two approaches to this problem:
-to a malicious USB device could result in dom0 being compromised. There are two
-approaches to this problem:
 
 1. Physically disconnect all USB devices whenever you reboot the host.
 2. Hide (i.e., blacklist) all USB controllers from dom0.
 
-**Warning:** If you use a USB [AEM] device, do not use the second option. Using
+**Warning:** If you use a USB [AEM] device, do not use the second option.
-a USB AEM device requires dom0 to have access to the USB controller to which
+Using a USB AEM device requires dom0 to have access to the USB controller to which your USB AEM device is attached.
-your USB AEM device is attached. If dom0 cannot read your USB AEM device, AEM
+If dom0 cannot read your USB AEM device, AEM will hang.
-will hang.
 
 The procedure to hide all USB controllers from dom0 is as follows:
 
@@ -430,23 +371,19 @@ The procedure to hide all USB controllers from dom0 is as follows:
  4. Save and close the file.
  5. Reboot.
 
-(Note: Beginning with R3.2, `rd.qubes.hide_all_usb` is set automatically if you
+(Note: Beginning with R3.2, `rd.qubes.hide_all_usb` is set automatically if you opt to create a USB qube during installation.
-opt to create a USB qube during installation. This also occurs automatically if
+This also occurs automatically if you choose to [create a USB qube] using the `qubesctl` method, which is the
-you choose to [create a USB qube] using the `qubesctl` method, which is the
 first pair of steps in the linked section.)
 
-**Warning:** USB keyboard cannot be used to type the disk passphrase
+**Warning:** A USB keyboard cannot be used to type the disk passphrase if USB controllers were hidden from dom0.
-if USB controllers were hidden from dom0. Before hiding USB controllers
+Before hiding USB controllers, make sure your laptop keyboard is not internally connected via USB (by checking output of the `lsusb` command) or that you have a PS/2 keyboard at hand (if using a desktop PC).
-make sure your laptop keyboard is not internally connected via USB
+Failure to do so will render your system unusable.
-(by checking output of `lsusb` command) or that you have a PS/2 keyboard at hand
-(if using a desktop PC). Failure to do so will render your system unusable.
 
 
 Removing a USB qube
 -------------------
 
-**Warning:** This procedure will result in your USB controller(s) being attached
+**Warning:** This procedure will result in your USB controller(s) being attached directly to dom0.
-directly to dom0.
 
  * GRUB2
  
@@ -476,7 +413,7 @@ Security Warning about USB Input Devices
 
 If you connect USB input devices (keyboard and mouse) to a VM, that VM will effectively have control over your system.
 Because of this, the benefits of using a USB qube are much smaller than using a fully untrusted USB qube.
-In addition to having control over your system, such VM can also sniff all the input you enter there (for example, passwords in the case of a USB keyboard).
+In addition to having control over your system, such a VM can also sniff all the input you enter there (for example, passwords in the case of a USB keyboard).
 
 There is no simple way to protect against sniffing, but you can make it harder to exploit control over input devices.
 
@@ -538,11 +475,9 @@ How to use a USB mouse
 
 **Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding.
 
-In order to use a USB mouse, you must first attach it to a USB qube, then give that
+In order to use a USB mouse, you must first attach it to a USB qube, then give that qube permission to pass mouse input to dom0.
-qube permission to pass mouse input to dom0.
+The following steps are already done by default if you created the sys-usb qube with `qubesctl state.sls qvm.sys-usb` above, or let Qubes create it for you on first boot.
-The following steps are already done by default if you created the sys-usb qube with
+However, if you've created the USB qube manually:
-`qubesctl state.sls qvm.sys-usb` above, or let Qubes create it for you on first boot. However,
-if you've created the USB qube manually:
 
 Edit the `qubes.InputMouse` policy file in dom0, which is located here:
 

configuration/assigning-devices.md

@@ -11,72 +11,101 @@ redirect_from:
 Assigning Devices to VMs
 ========================
 
-In order to assign a whole PCI(e) device to a VM, one should use the `qvm-pci`
+Sometimes you may need to assign an entire PCI or PCI Express device directly to a qube.
-tool. First, list the available PCI devices:
+This is also known as PCI pass-through.
+The Qubes installer does this by default for `sys-net` (assigning all network class controllers), as well as `sys-usb` (assigning all USB controllers) if you chose to create the USB qube during install.
+While this covers most use cases, there are some occasions when you may want to manually assign one NIC to `sys-net` and another to a custom NetVM, or have some other type of PCI controller you want to manually assign.
+
+Note that one can only assign full PCI or PCI Express devices by default.
+This limit is imposed by the PC and VT-d architectures.
+This means if a PCI device has multiple functions, all instances of it need to be assigned to the same qube unless you have disabled the strict requirement for FLR with the `no-strict-reset` (R4.0) or `pci_strictreset` (R3.2) option.
+In the steps below, you can tell if this is needed if you see the BDF for the same device listed multiple times with only the number after the "." changing.
+
+While PCI device can only be used by one powered on VM at a time, it *is* possible to *assign* the same device to more than one VM at a time. 
+This means that you can use the device in one VM, shut that VM down, start up a different VM (to which the same device is also assigned), then use the device in that VM.
+This can be useful if, for example, you have only one USB controller, but you have multiple security domains which all require the use of different USB devices.
+
+R4.0
+------------------------
+
+In order to assign a whole PCI(e) device to a VM, one should use the `qvm-pci` tool.
+First, list the available PCI devices:
+
+~~~
+qvm-pci
+~~~
+
+This will show you the `backend:BDF` address of each PCI device. 
+It will look something like `dom0:00_1a.0`.
+Once you've found the address of the device you want to assign, then attach it like so:
+
+~~~
+qvm-pci attach --persistent <vmname> <backend>:<bdf>
+~~~
+
+For example, if `00_1a.0` is the BDF of the device you want to assign to the "personal" domain, you would do this:
+
+~~~
+qvm-pci attach --persistent personal dom0:00_1a.0
+~~~
+
+R3.2
+------------------------
+
+In order to assign a whole PCI(e) device to a VM, one should use the `qvm-pci` tool.
+First, list the available PCI devices:
 
 ~~~
 lspci
 ~~~
 
-This will show you the BDF address of each PCI device. It will look something
+This will show you the BDF address of each PCI device.
-like `00:1a.0`. Once you've found the BDF address of the device you want to
+It will look something like `00:1a.0`. 
-assign, then attach it like so:
+Once you've found the BDF address of the device you want to assign, then attach it like so:
 
 ~~~
 qvm-pci -a <vmname> <bdf>
 ~~~
 
-For example, if `00:1a.0` is the BDF of the device I want to assign to the
+For example, if `00:1a.0` is the BDF of the device you want to assign to the "personal" domain, you would do this:
-"personal" domain, I would do this:
 
 ~~~
 qvm-pci -a personal 00:1a.0
 ~~~
 
-Note that one can only assign full PCI or PCI Express devices. This means one
-cannot assign single USB devices -- only the whole USB controller with whatever
-USB devices are connected to it. This limit is imposed by the PC and VT-d
-architectures. More information on using and managing USB devices with qubes is
-available on the [USB] page.
-
-While a device can only be attached to one VM at a time, it *is* possible to
-*assign* the same device to more than one VM at a time. This means that you can
-use the device in one VM, shut that VM down, start up a different VM (to which
-the same device is also assigned), then use the device in that VM. This can be
-useful if, for example, you have only one USB controller, but you have multiple
-security domains which all require the use of different USB devices.
-
-
 Using Qubes Manager
 -------------------
 
-The above steps can also be done in Qubes Manager. Simply go into the VM
+The above steps can also be done in Qubes Manager.
-settings of your desired VM, then go to the "Devices" tab. This will show you a
+Simply go into the VM settings of your desired VM, then go to the "Devices" tab.
-list of available devices, which you can select to be assigned to that VM.
+This will show you a list of available devices, which you can select to be assigned to that VM.
 
 
 Finding the right USB controller
 --------------------------------
 
-If you want assign a certain [USB] device to a VM (by attaching the whole
+Some USB devices are not compatible with the USB pass-through method Qubes employs.
-USB controller), you need to figure out which PCI device is the right
+In situations like this, you can still often get the USB device to work by passing through the entire USB controller to a qube.
-controller. First, check to which USB bus the device is connected:
+However, with this approach one cannot assign single USB devices, only the whole USB controller with whatever USB devices are connected to it. 
+More information on using and managing USB devices with qubes is available on the [USB] page. 
+If you want assign a certain USB device to a VM by attaching the whole USB controller, you need to figure out which PCI device is the right controller. 
+First, check to which USB bus the device is connected (note that these steps need to be run from a terminal inside `dom0`):
 
 ~~~
 lsusb
 ~~~
 
-For example, I want assign a broadband modem to the netvm. In the out put of
+For example, I want assign a broadband modem to the NetVM. 
-`lsusb` it can be listed as something like this. (In this case, the device isn't
+In the output of `lsusb` it can be listed as something like this. 
-fully identified):
+(In this case, the device isn't fully identified):
 
 ~~~
 Bus 003 Device 003: ID 413c:818d Dell Computer Corp.
 ~~~
 
-The device is connected to USB bus \#3. Then check which other devices are
+The device is connected to USB bus \#3. 
-connected to the same bus, since *all* of them will be assigned to the same VM.
+Then check which other devices are connected to the same bus, since *all* of them will be assigned to the same VM.
-Now is the time to find right USB controller:
+Now is the time to find the right USB controller:
 
 ~~~
 readlink /sys/bus/usb/devices/usb3
@@ -88,37 +117,74 @@ This should output something like:
 ../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
 ~~~
 
-Now you see the BDF address in the path (right before final `usb3`). Strip the
+Now you see the BDF address in the path (right before final `usb3`).
-leading `0000:` and pass the rest to the `qvm-pci` tool:
+Strip the leading `0000:` and pass the rest to the `qvm-pci` tool to attach the controller with the version specific steps above.
-
-~~~
-qvm-pci -a netvm 00:1a.0
-~~~
-
 
 Possible issues
 ---------------
 
 ### DMA buffer size
 
-VMs with assigned PCI devices in Qubes have allocated a small buffer for DMA
+VMs with assigned PCI devices in Qubes have allocated a small buffer for DMA operations (called swiotlb).
-operations (called swiotlb). By default it is 2MB, but some devices need a
+By default it is 2MB, but some devices need a larger buffer.
-larger buffer. To change this allocation, edit VM's kernel parameters (this is
+To change this allocation, edit VM's kernel parameters (this is expressed in 512B chunks):
-expressed in 512B chunks):
 
 ~~~
 # qvm-prefs netvm |grep kernelopts
 kernelopts       : iommu=soft swiotlb=2048 (default)
-# qvm-prefs -s netvm kernelopts "iommu=soft swiotlb=4096"
+# qvm-prefs -s netvm kernelopts "iommu=soft swiotlb=8192"
 ~~~
 
-This is [known to be needed][ml1] for the Realtek RTL8111DL Gigabit Ethernet
+This is [known to be needed][ml1] for the Realtek RTL8111DL Gigabit Ethernet Controller.
-Controller.
 
 ### PCI passthrough issues
 
-Sometimes PCI arbitrator is too strict. There is a way to enable permissive mode
+Sometimes the PCI arbitrator is too strict. 
-for it. Create `/etc/systemd/system/qubes-pre-netvm.service`:
+There is a way to enable permissive mode for it.
+See also: [this thread][ml2] and the Xen wiki's [PCI passthrough] page.
+
+**NOTE:** By setting the permissive flag for the PCI device, you're potentially weakening the device isolation, especially if your system is not equipped with a VT-d Interrupt Remapping unit. 
+See [Software Attacks on Intel VT-d] (page 7)
+for more details.
+
+At other times, you may instead need to disable the FLR requirement on a device.
+This will also weaken device isolation; see the "I created a usbVM..." entry in the [FAQ](/doc/user-faq/) for more details.
+
+R4.0
+------------------------
+
+Permissive mode and strict reset are options set as part of PCI device attachment. 
+If you've already attached the PCI device to a VM, detach it first either with Qube Manager or `qvm-pci`, then list the available PCI devices:
+
+~~~
+qvm-pci
+~~~
+
+This will show you the `backend:BDF` address of each PCI device.
+It will look something like `dom0:00_1a.0`. 
+Once you've found the address of the device you want to assign, then attach it like so:
+
+~~~
+qvm-pci attach --persistent --option <option1> [--option <option2>] <vmname> <backend>:<bdf>
+~~~
+
+For example, if `00_1a.0` is the BDF of the device you want to assign to the "personal" domain, and it is particularly difficult to pass through you would do this:
+
+~~~
+qvm-pci attach --persistent --option permissive=true --option no-strict-reset=true personal dom0:00_1a.0
+~~~
+
+Running `qvm-pci` again should then show your PCI device attached with both the `permissive` and `no-strict-reset` options set.
+
+**Note** again that in most cases you should not need either of these options set. 
+Only set one or more of them as required to get your device to function, or replace the device with one that functions properly with Qubes.
+
+R3.2
+------------------------
+
+Permissive mode is enabled system wide per device.
+
+Create `/etc/systemd/system/qubes-pre-netvm.service`:
 
 ~~~
 [Unit]
@@ -136,22 +202,21 @@ WantedBy=multi-user.target
 
 Then enable it with `systemctl enable qubes-pre-netvm.service`
 
-See also: [this thread][ml2] and the Xen wiki's [PCI passthrough] page.
+The strict reset option is set for all devices attached to a VM with:
 
-**NOTE:** By setting the permissive flag for the PCI device, you're potentially
+```
-weakening the device isolation, especially if your system is not equipped with
+qvm-prefs usbVM -s pci_strictreset false
-VT-d Interrupt Remapping unit. See [Software Attacks on Intel VT-d] (page 7)
+```
-for more details.
 
+**Note** again that in most cases you should not need either of these options set.
+Only set one or more of them as required to get your device to function, or replace the device with one that functions properly with Qubes.
 
 Bringing PCI device back to dom0
 --------------------------------
 
-By default, when a device is detached from a VM (or when a VM with an attached
+By default, when a device is detached from a VM (or when a VM with an attached PCI device is shut down), the device is *not* automatically attached back to dom0. 
-PCI device is shut down), the device is *not* automatically attached back to
+This is an intended feature. 
-dom0. This is an intended feature. A device which was previously assigned to a
+A device which was previously assigned to a VM less trusted than dom0 (which, in Qubes, is *all* of them) could attack dom0 if it were automatically reassigned there.
-VM less trusted than dom0 (which, in Qubes, is *all* of them) could attack dom0
-if it were automatically reassigned there.
 
 In order to re-enable the device in dom0, either:
 
@@ -159,9 +224,8 @@ In order to re-enable the device in dom0, either:
 
 or
 
- *  Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the
+ *  Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver, and attach it back to the original driver. 
-    pciback driver, and attach it back to the original driver. Replace `<BDF>`
+    Replace `<BDF>` with your device, for example `00:1c.2`:
-    with your device, for example `00:1c.2`:
 
     ~~~
     echo 0000:<BDF> > /sys/bus/pci/drivers/pciback/unbind

configuration/config-files.md

@@ -12,13 +12,11 @@ redirect_from:
 Qubes specific VM config files
 ==============================
 
-Those files are placed in /rw, which survives VM restart, so can be 
+These files are placed in /rw, which survives a VM restart.
-used to customize single VM (not all VMs based on the same template). 
+That way, they can be used to customize a single VM instead of all VMs based on the same template. 
 The scripts here all run as root.
 
--   `/rw/config/rc.local` - script run at VM startup. Good place to 
+-   `/rw/config/rc.local` - script runs at VM startup. Good place to change some service settings, replace config files with its copy stored in /rw/config, etc. Example usage:
-change some service settings, replace config files with its copy stored 
-in /rw/config etc. Example usage:
 
     ~~~
     # Store bluetooth keys in /rw to keep them across VM restarts
@@ -26,29 +24,24 @@ in /rw/config etc. Example usage:
     ln -s /rw/config/var-lib-bluetooth /var/lib/bluetooth
     ~~~
 
--   `/rw/config/qubes-ip-change-hook` - script run in NetVM after 
+-   `/rw/config/qubes-ip-change-hook` - script runs in NetVM after every external IP change and on "hardware" link status change.
-external IP change (or connection to the network)
 
--   `/rw/config/qubes-firewall-user-script` - script run in ProxyVM 
+-   `/rw/config/qubes-firewall-user-script` - script runs in ProxyVM/AppVM with `qvm-features <vmname> qubes-firewall true` after each firewall update.
-after each firewall update. Good place to write own custom firewall 
+    Good place to write own custom firewall rules.
-rules
 
--   `/rw/config/suspend-module-blacklist` - list of modules (one per 
+-   `/rw/config/suspend-module-blacklist` - list of modules (one per line) to be unloaded before system goes to sleep.
-line) to be unloaded before system going to sleep. The file is used 
+    The file is used only in a VM with PCI devices attached.
-only in VM with some PCI devices attached. Supposed to be used for 
+    Intended for use with problematic device drivers.
-problematic device drivers.
 
 Note that scripts need to be executable (chmod +x) to be used.
 
-Also take a look at [bind-dirs][/doc/bind-dirs] for instruction how to easily
+Also, take a look at [bind-dirs](/doc/bind-dirs) for instructions on how to easily modify arbitrary system files in an AppVM and have those changes persist.
-modify arbitrary system file in AppVM and have those changes persistent.
 
 GUI and audio configuration in dom0
 ===================================
 
-GUI configuration file `/etc/qubes/guid.conf` in one of few not managed 
+The GUI configuration file `/etc/qubes/guid.conf` in one of a few not managed by qubes-prefs or the Qubes Manager tool.
-by qubes-prefs nor Qubes Manager tool. Sample config (included in 
+Sample config (included in default installation):
-default installation):
 
 ~~~
 # Sample configuration file for Qubes GUI daemon
@@ -78,25 +71,18 @@ VM: {
 
 Currently supported settings:
 
--   `allow_fullscreen` - allow VM to request its windows to go 
+-   `allow_fullscreen` - allow VM to request its windows to go fullscreen (without any colorful frame).
-fullscreen (without any colorful frame).
 
-    **Note:** Regardless of this setting, you can always put a window into
+    **Note:** Regardless of this setting, you can always put a window into fullscreen mode in Xfce4 using the trusted window manager by right-clicking on a window's title bar and selecting "Fullscreen".
-fullscreen mode in Xfce4 using the trusted window manager by right-clicking on
+    This functionality should still be considered safe, since a VM window still can't voluntarily enter fullscreen mode.
-a window's title bar and selecting "Fullscreen". This functionality should still
+    The user must select this option from the trusted window manager in dom0.
-be considered safe, since a VM window still can't voluntarily enter fullscreen
+    To exit fullscreen mode from here, press `alt` + `space` to bring up the title bar menu again, then select "Leave Fullscreen".
-mode. The user must select this option from the trusted window manager in dom0.
-To exit fullscreen mode from here, press `alt` + `space` to bring up the title
-bar menu again, then select "Leave Fullscreen".
 
--   `allow_utf8_titles` - allow to use UTF-8 in window titles, 
+-   `allow_utf8_titles` - allow the use of UTF-8 in window titles; otherwise, non-ASCII characters are replaced by an underscore.
-otherwise non-ASCII characters are replaced by underscore.
 
--   `secure_copy_sequence` and `secure_paste_sequence` - key sequences 
+-   `secure_copy_sequence` and `secure_paste_sequence` - key sequences used to trigger secure copy and paste.
-used to trigger secure copy and paste
 
--   `windows_count_limit` - limit on concurrent windows count.
+-   `windows_count_limit` - limit on concurrent windows.
 
--   `audio_low_latency` - force low-latency audio mode (about 40ms 
+-   `audio_low_latency` - force low-latency audio mode (about 40ms compared to 200-500ms by default).
-compared to 200-500ms by default). Note that this will cause much 
+    Note that this will cause much higher CPU usage in dom0.
-higher CPU usage in dom0.

configuration/disk-trim.md

@@ -8,31 +8,89 @@ redirect_from:
 - /wiki/DiskTRIM/
 ---
 
-VMs have already TRIM enabled by default, but dom0 doesn't. There are some security implications (read for example [this article](https://asalor.blogspot.com/2011/08/trim-dm-crypt-problems.html)), but IMO not very serious.
+Disk Trim
+----------
 
-To enable TRIM in dom0 you need:
+Disk trimming is the procedure by which the operating system informs the underlying storage device of which storage blocks are no longer in use.
+It does this by issuing an `ATA_TRIM` command for the block. This is also known as a `discard`.
+In this way, the storage device can perform garbage collection of the unused blocks and internally prepare them for reuse. SSDs in general benefit from this, while HDDs do not.
 
-1.  Get your LUKS device UUID:
+In a Linux system running on bare metal, this is relatively straight-forward. 
+When instructed by the operating system, discards are issued by the file-system driver directly to the storage driver and then to the SSD.
+
+In Qubes, this gets more complex due to virtualization, LUKS, and LVM (and thin pools on R4.0 and up).
+If you run `fstrim --all` inside a TemplateVM, in a worst case the `discard` can follow a path like:
+
+    OS -> File-system Driver -> Virtual Storage Driver -> Backend Storage Driver -> LVM Storage Driver -> LUKS Driver -> Physical Storage Driver -> Physical Storage Device
+    
+If discards are not supported at any one of those layers, it will not make it to the underlying physical device.
+
+There are some security implications to permitting TRIM (read for example [this article](https://asalor.blogspot.com/2011/08/trim-dm-crypt-problems.html)), but in most cases not exploitable.
+
+
+Configuration
+----------
+
+In all versions of Qubes, you may want to set up a periodic job in `dom0` to trim the disk.
+This can be done with either systemd (weekly only) or cron (daily or weekly).
+
+ * **Systemd**
+
+   From a terminal as a regular user:
+
+   ```
+   systemctl enable fstrim.timer
+   systemctl start fstrim.timer
+   ```
+
+ * **Cron**
+
+   This can be done from a terminal as root, by creating a `trim` file in `/etc/cron.daily` (or `/etc/cron.weekly`).
+    Add the following contents:
+
+    ```
+   #!/bin/bash
+   /sbin/fstrim --all
+   ```
+   And mark it as executable with `chmod 755 /etc/cron.daily/trim`.
+
+**Note** Although discards can be issued on every delete inside `dom0` by adding the `discard` mount option to `/etc/fstab`, this option can hurt performance so the above procedure is recommended instead.
+However, inside App and Template qubes, the `discard` mount option is on by default to notify the LVM thin pool driver (R4.0) or sparse file driver (R3.2) that the space is no longer needed and can be zeroed and re-used.
+
+If you are using Qubes with LVM, you may also want to set `issue_discards = 1` in `/etc/lvm/lvm.conf`.
+Setting this option will permit LVM to issue discards to the SSD when logical volumes are shrunk or deleted.
+In R4.x, LVM Logical volumes are frequently deleted (every time a disposable VM is shut down, for example) so setting `issue_discards = 1` is recommended if using an SSD.
+However, this is relatively rare in R3.x.
+
+
+LUKS
+----------
+
+If you have enabled LUKS in dom0, discards will not get passed down to the storage device. 
+
+To enable TRIM support in dom0 with LUKS you need to:
+
+1. Get your LUKS device UUID:
 
     ~~~
     ls /dev/mapper/luks-*
     ~~~
 
-2.  Add entry to `/etc/crypttab` (replace luks-\<UUID\> with the device name and the \<UUID\> with UUID alone):
+2. Add entry to `/etc/crypttab` (replace luks-\<UUID\> with the device name and the \<UUID\> with UUID alone):
 
     ~~~
-    luks-<UUID> UUID=<UUID> none allow-discards
+    luks-<UUID> UUID=<UUID> none discard
     ~~~
 
-3.  Add `rd.luks.allow-discards=1` to kernel cmdline (`/etc/default/grub`, GRUB\_CMDLINE\_LINUX line)
+3. Add `rd.luks.options=discard` to kernel cmdline (follow either GRUB2 or EFI, not both): 
-4.  Rebuild grub config (`grub2-mkconfig -o /boot/grub2/grub.cfg`)
+    * GRUB2: `/etc/default/grub`, `GRUB_CMDLINE_LINUX` line and  
-5.  Rebuild initrd **in hostonly mode**:
+      Rebuild grub config (`grub2-mkconfig -o /boot/grub2/grub.cfg`), then  
+      Rebuild initrd **in hostonly mode** (`dracut -H -f`)
+    * EFI: `/boot/efi/EFI/qubes/xen.cfg`, `kernel=` line(s), then  
+      Rebuild initrd **in hostonly mode** (`dracut -H -f /boot/efi/EFI/qubes/initramfs-$(uname -r).img $(uname -r)`)
 
-    ~~~
+4. Reboot the system.
-    dracut -H -f
+
-    ~~~
+5. To verify if discards are enabled you may use `dmsetup table` (confirm the line for your device mentions "discards") or just run `fstrim -av` (you should see a `/` followed by the number of bytes trimmed).
 
-6.  Add "discard" option to `/etc/fstab` for root device
-7.  Reboot the system, verify that allow-discards is really enabled (`dmsetup table`)
 
-There is a [bug affecting allow-discards option](https://bugzilla.redhat.com/show_bug.cgi?id=890533), once it will be fixed, first two steps will be no longer needed.

configuration/external-audio.md

@@ -14,19 +14,24 @@ Using External Audio Devices
 Why you want to use external audio devices
 ------------------------------------------
 
-Qubes audio virtualization protocol does not implement latency reporting for security reasons, keeping the protocol as simple as possible. Also, in a compromise between low latency and low CPU usage, latency may be around 200 ms. So applications demanding higher audio quality (even Skype) need a better environment. But Qubes flexibility fully allows that using external audio devices. These are mostly USB audio cards, but firewire devices also might be used.
+Qubes audio virtualization protocol does not implement latency reporting for security reasons, keeping the protocol as simple as possible.
+Also, in a compromise between low latency and low CPU usage, latency may be around 200 ms.
+So applications demanding higher audio quality (even Skype) need a better environment.
+But Qubes flexibility fully allows that using external audio devices. 
+These are mostly USB audio cards, but firewire devices also might be used.
 
 Implementing external audio devices
 -----------------------------------
 
-First you need to identify an user VM dedicated to audio and [assign a device](/doc/AssigningDevices) to it. In the most common case the assigned device is the USB controller to which your USB audio card will be connected.
+First you need to identify an user VM dedicated to audio and [assign a device](/doc/AssigningDevices) to it.
+In the most common case the assigned device is the USB controller to which your USB audio card will be connected.
 
 ### Fedora VMs
 
 In a terminal of the template from which you user VM depends, install pavucontrol with:
 
 ~~~
-sudo yum install pavucontrol
+sudo dnf install pavucontrol
 ~~~
 
 Close the template and start or restart your user VM, insert your external audio device, open a terminal and prepare pulseaudio to use it with:
@@ -38,9 +43,10 @@ pactl load-module module-udev-detect
 
 Start the audio application that is going to use the external audio device.
 
-Launch pavucontrol, for example using "run command in VM" of Qubes Manager and select you external audio card in pavucontrol. You need to do that only the first time you use a new external audio device, then pulse audio will remember you selection.
+Launch pavucontrol, for example using "run command in VM" of Qubes Manager and select your external audio card in pavucontrol.
+You need to do that only the first time you use a new external audio device, then pulse audio will remember your selection.
 
-If you detach your external audio device, then want to insert it again, or change it with another one, you need to repeat the previous commands in terminal, adding an other line at the beginning:
+If you detach your external audio device, then want to insert it again (or want to change it with another one), you need to repeat the previous commands in terminal adding another line at the beginning:
 
 ~~~
 pactl unload-module module-udev-detect

configuration/http-filtering-proxy.md

@@ -31,10 +31,10 @@ prevents websites that use DNS-based load balancers from working
 unless the user reloads the firewall rules (which re-resolve the DNS
 names) whenever the balancer transfer her session to another IP. Third
 the initial setup of the rules is complicated as the firewall drops
-the connection silently. As a workaround on can use browser's network
+the connection silently. As a workaround one can use browser's network
 console to see what is blocked, but this is time-consuming and one can
 trivially miss some important cases like including in the firewall
-white list sites for OCSP SSL certificate verification.
+white-list sites for OCSP SSL certificate verification.
 
 These drawbacks can be mitigated if one replaces iptable-based rules
 with a filtering HTTP proxy. The following describes how to setup
@@ -94,7 +94,7 @@ Setup
         name.ip-address-of-app-vm
 
    The name part before the dot can be arbitrary. For convenience one can
-   use AppVm name here, but this is not required. It is important to get
+   use AppVM name here, but this is not required. It is important to get
    ip address part right as this is what the control script uses to
    determine for which AppVM to apply the proxy rules. One can check the
    IP address of AppVM in Qubes VM manager in the VM settings dialog, see

configuration/managing-vm-kernel.md

@@ -9,17 +9,20 @@ redirect_from:
 VM kernel managed by dom0
 =========================
 
-By default VMs kernels are provided by dom0. This means that:
+By default, VMs kernels are provided by dom0. This means that:
 
-1. You can select kernel version in VM settings;
+1. You can select the kernel version in VM settings;
 2. You can modify kernel options in VM settings;
-3. You can **not** modify any of above from inside of VM;
+3. You can **not** modify any of the above from inside a VM;
 4. Installing additional kernel modules is cumbersome.
 
-To select which kernel a given VM will use, you can use either use Qubes Manager (VM settings, advanced tab), or `qvm-prefs` tool:
+*Note* In the examples below, although the specific version numbers might be old, the commands have been verified on R3.2 with debian-9 and fedora-26 templates.
+At the time of writing, there is a blocking issue for R4.0 [3563](https://github.com/QubesOS/qubes-issues/issues/3563).
+
+To select which kernel a given VM will use, you can either use Qubes Manager (VM settings, advanced tab), or the `qvm-prefs` tool:
 
 ~~~
-[user@dom0 ~]$ qvm-prefs my-appvm -s kernel
+[user@dom0 ~]$ qvm-prefs -s my-appvm kernel
 Missing kernel version argument!
 Possible values:
 1) default
@@ -29,11 +32,11 @@ Possible values:
   - 3.18.17-4
   - 3.19.fc20
   - 3.18.10-2
-[user@dom0 ~]$ qvm-prefs my-appvm -s kernel 3.18.17-4
+[user@dom0 ~]$ qvm-prefs -s my-appvm kernel 3.18.17-4
-[user@dom0 ~]$ qvm-prefs my-appvm -s kernel default
+[user@dom0 ~]$ qvm-prefs -s my-appvm kernel default
 ~~~
 
-To check/change the default kernel you can go either to "Global settings" in Qubes Manager, or use `qubes-prefs` tool:
+To check/change the default kernel you can either go to "Global settings" in Qubes Manager, or use the `qubes-prefs` tool:
 
 ~~~
 [user@dom0 ~]$ qubes-prefs
@@ -49,7 +52,9 @@ updatevm          : sys-firewall
 Installing different kernel using Qubes kernel package
 ----------------------------------
 
-VM kernels are packages by Qubes team in `kernel-qubes-vm` packages. Generally system will keep the 3 newest available versions. You can list them with the `rpm` command:
+VM kernels are packages by Qubes team in `kernel-qubes-vm` packages.
+Generally, the system will keep the three newest available versions.
+You can list them with the `rpm` command:
 
 ~~~
 [user@dom0 ~]$ rpm -qa 'kernel-qubes-vm*'
@@ -58,10 +63,11 @@ kernel-qubes-vm-3.18.16-3.pvops.qubes.x86_64
 kernel-qubes-vm-3.18.17-4.pvops.qubes.x86_64
 ~~~
 
-If you want more recent version, you can check `qubes-dom0-unstable` repository. As the name suggest, keep in
+If you want a more recent version, you can check the `qubes-dom0-unstable` repository.
-mind that those packages may be less stable than the default ones.
+There is also the `kernel-latest-qubes-vm` package which should provide a more recent (non-LTS) kernel, but has received much less testing.
+As the names suggest, keep in mind that those packages may be less stable than the default ones.
 
-Checking available versions in `qubes-dom0-unstable` repository:
+To check available versions in the `qubes-dom0-unstable` repository:
 
 ~~~
 [user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable --action=list kernel-qubes-vm
@@ -82,7 +88,7 @@ kernel-qubes-vm.x86_64 1000:3.18.17-4.pvops.qubes @qubes-dom0-cached
 
 ~~~
 
-Installing new version from `qubes-dom0-unstable` repository:
+Installing a new version from `qubes-dom0-unstable` repository:
 
 ~~~
 [user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable kernel-qubes-vm
@@ -127,24 +133,25 @@ Failed:
   kernel-qubes-vm.x86_64 1000:3.18.10-2.pvops.qubes
 
 Complete!
-[marmarek@dom0 ~]$
+[user@dom0 ~]$
 ~~~
 
-In the above example, it tries to remove 3.18.10-2.pvops.qubes kernel (to keep only 3 installed), but since some VM uses it, it fails. Installation of new package is unaffected by this event.
+In the above example, it tries to remove the 3.18.10-2.pvops.qubes kernel (to keep only three installed), but since some VM uses it, it fails.
+Installation of the new package is unaffected by this event.
 
-The newly installed package is set as default VM kernel.
+The newly installed package is set as the default VM kernel.
 
 Installing different VM kernel based on dom0 kernel
 ---------------------------------------------------
 
-It is possible to package kernel installed in dom0 as VM kernel. This makes it
+It is possible to package a kernel installed in dom0 as a VM kernel.
-possible to use VM kernel, which is not packaged by Qubes team. This includes:
+This makes it possible to use a VM kernel which is not packaged by Qubes team.
- * using Fedora kernel package
+This includes:
- * using manually compiled kernel
+ * using a Fedora kernel package
+ * using a manually compiled kernel
 
-To prepare such VM kernel, you need to install `qubes-kernel-vm-support`
+To prepare such a VM kernel, you need to install the `qubes-kernel-vm-support` package in dom0 and also have matching kernel headers installed (`kernel-devel` package in the case of a Fedora kernel package).
-package in dom0 and also have matching kernel headers installed (`kernel-devel`
+You can install requirements using `qubes-dom0-update`:
-package in case of Fedora kernel package). You can install required stuff using `qubes-dom0-update`:
 
 ~~~
 [user@dom0 ~]$ sudo qubes-dom0-update qubes-kernel-vm-support kernel-devel
@@ -187,10 +194,9 @@ Installed:
 Complete!
 ~~~
 
-Then you can call `qubes-prepare-vm-kernel` tool to actually package the
+Then you can call the `qubes-prepare-vm-kernel` tool to actually package the kernel.
-kernel. The first parameter is kernel version (exactly as seen by the kernel),
+The first parameter is kernel version (exactly as seen by the kernel), the second one (optional) is short name.
-the second one (optional) is short name being visible in Qubes Manager and
+This is visible in Qubes Manager and the `qvm-prefs` tool.
-`qvm-prefs` tool.
 
 ~~~
 [user@dom0 ~]$ sudo qubes-prepare-vm-kernel 4.1.9-6.pvops.qubes.x86_64 4.1.qubes
@@ -207,14 +213,18 @@ Using kernel installed in the VM
 
 **This option is available only in Qubes R3.1 or newer**
 
-It is possible to use kernel installed in the VM (in most cases - TemplateVM).
+It is possible to use a kernel installed in the VM (in most cases - TemplateVM).
-This is possible thanks to PV GRUB2 - GRUB2 running in the VM. To make it happen, you need to:
+This is possible thanks to PV GRUB2 - GRUB2 running in the VM.
+To make it happen, at a high level you need to:
 
-1. Install PV GRUB2 in dom0 - package is named `grub2-xen`.
+1. Install PV GRUB2 (`grub2-xen`) in dom0.
-2. Install kernel in the VM. As with all VM software installation - this needs to be done in TemplateVM (of StandaloneVM if you are using one).
+2. Install kernel in the VM (see below for Fedora and Debian steps).
-3. Set VM kernel to `pvgrub2` value. You can use `pvgrub2` in selected VMs, not necessary all of them, even when it's template has kernel installed. You can still use dom0-provided kernel for selected VMs.
+   As with all VM software installation - this needs to be done in a TemplateVM (or StandaloneVM if you are using one).
+3. Set VM kernel to `pvgrub2` value.
+   You can use `pvgrub2` in selected VMs, but it's not necessary in all of them, even if its template has a kernel installed.
+   You can still use a dom0-provided kernel for selected VMs.
 
-**WARNING: When using kernel from within VM, `kernelopts` parameter is ignored.**
+**WARNING: When using a kernel from within a VM, the `kernelopts` parameter is ignored.**
 
 ### Installing PV GRUB2
 
@@ -226,28 +236,31 @@ sudo qubes-dom0-update grub2-xen
 
 ### Installing kernel in Fedora VM
 
-In Fedora based VM, you need to install `qubes-kernel-vm-support` package. This
+In a Fedora based VM, you need to install the `qubes-kernel-vm-support` package.
-package include required additional kernel module and initramfs addition
+This package includes the additional kernel module and initramfs addition required to start a Qubes VM (for details see [template implementation](/doc/template-implementation/)).
-required to start Qubes VM (for details see
+Additionally, you need some GRUB tools to create its configuration. 
-[template implementation](/doc/template-implementation/)). Additionally you
+Note: You don't need an actual grub bootloader as it is provided by dom0, but having one shouldn't hurt.
-need some GRUB tools to create it's configuration. Note: you don't need actual
-grub bootloader as it is provided by dom0. But having one also shouldn't harm.
 
 ~~~
-sudo yum install qubes-kernel-vm-support grub2-tools
+sudo dnf install qubes-kernel-vm-support grub2-tools
 ~~~
 
-Then install whatever kernel you want. If you are using distribution kernel
+Then install whatever kernel you want.
-package (`kernel` package), initramfs and kernel module should be handled
+You need to also ensure you have the `kernel-devel` package for the same kernel version installed.
-automatically, but you need to ensure you have `kernel-devel` package for the
-same kernel version installed. If you are using manually build kernel, you need
-to handle this on your own. Take a look at `dkms` and `dracut` documentation.
-Especially `dkms autoinstall` command may be useful.
 
-When kernel is installed, you need to create GRUB configuration. 
+If you are using a distribution kernel package (`kernel` package), the initramfs and kernel modules may be handled automatically. 
-You may want to adjust some settings in `/etc/default/grub`, for example lower
+If you are using a manually built kernel, you need to handle this on your own.
-`GRUB_TIMEOUT` to speed up VM startup. Then you need to generate actual configuration:
+Take a look at the `dkms` documentation, especially the `dkms autoinstall` command may be useful.
-In Fedora it can be done using `grub2-mkconfig` tool:
+If you did not see the `kernel` install rebuild your initramfs, or are using a manually built kernel, you will need to rebuild it yourself with the following (replace version numbers with those appropriate for your kernel):
+
+~~~
+dracut -f /boot/initramfs-4.14.16-200.fc26.x86_64.img 4.14.16-200.fc26.x86_64
+~~~
+
+Once the kernel is installed, you need to create a GRUB configuration. 
+You may want to adjust some settings in `/etc/default/grub`; for example, lower `GRUB_TIMEOUT` to speed up VM startup. 
+Then, you need to generate the actual configuration:
+In Fedora it can be done using the `grub2-mkconfig` tool:
 
 ~~~
 sudo grub2-mkconfig -o /boot/grub2/grub.cfg
@@ -259,29 +272,34 @@ You can safely ignore this error message:
 grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map
 ~~~
 
-Then shutdown the VM. From now you can set `pvgrub2` as VM kernel and it will
+Then shutdown the VM.
-start kernel configured within VM. 
+Now you can set `pvgrub2` as the VM kernel and it will start the kernel configured within your VM. 
+
+**Note:** On first boot the VM will automatically allocate swap space.
+This can take a while to complete- longer than your `qrexec_timeout` setting, which will make the VM appear to have hung on boot.
+To confirm this is the case, see [Troubleshooting](/doc/managing-vm-kernel/#troubleshooting) below or just wait for five minutes and shutdown the VM.
+It should respond normally on future boots.
 
 ### Installing kernel in Debian VM
 
-In Debian based VM, you need to install `qubes-kernel-vm-support` package. This
+In a Debian based VM, you need to install the `qubes-kernel-vm-support` package.
-package include required additional kernel module and initramfs addition
+This package includes the additional kernel module and initramfs addition required to start a Qubes VM (for details see [template implementation](/doc/template-implementation/)).
-required to start Qubes VM (for details see
+Additionally, you need some GRUB tools to create its configuration. 
-[template implementation](/doc/template-implementation/)). Additionally you
+Note: You don't need an actual grub bootloader as it is provided by dom0, but having one shouldn't hurt.
-need some GRUB tools to create it's configuration. Note: you don't need actual
-grub bootloader as it is provided by dom0. But having one also shouldn't harm.
 
 ~~~
-sudo apt-get update
+sudo apt update
-sudo apt-get install qubes-kernel-vm-support grub2-common
+sudo apt install qubes-kernel-vm-support grub2-common
 ~~~
 
+If prompted for a GRUB install device, choose `/dev/mapper/dmroot`.
+You will receive an error about GRUB failed to install to it, but just continue anyways.
+
 Ignore warnings about `version '...' has bad syntax`.
 
-Then install whatever kernel you want. If you are using distribution kernel
+Then install whatever kernel you want.
-package (`linux-image-amd64` package), initramfs and kernel module should be
+If you are using a distribution kernel package (`linux-image-amd64` package), the initramfs and kernel modules should be handled automatically.
-handled automatically. If not, or you are building kernel manually, do this on
+If not, or you are building the kernel manually, do this using `dkms` and `initramfs-tools`:
-using `dkms` and `initramfs-tools`:
 
     sudo dkms autoinstall -k <kernel-version> # replace this <kernel-version> with actual kernel version
     sudo update-initramfs -u
@@ -303,10 +321,9 @@ The output should look like this:
 	$ sudo update-initramfs -u
 	update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64
 
-When kernel is installed, you need to create GRUB configuration. 
+When the kernel is installed, you need to create a GRUB configuration. 
-You may want to adjust some settings in `/etc/default/grub`, for example lower
+You may want to adjust some settings in `/etc/default/grub`; for example, lower `GRUB_TIMEOUT` to speed up VM startup.
-`GRUB_TIMEOUT` to speed up VM startup. Then you need to generate actual configuration:
+Then, you need to generate the actual configuration with the `update-grub2` tool:
-In Fedora it can be done using `update-grub2` tool:
 
 ~~~
 sudo mkdir /boot/grub
@@ -319,17 +336,21 @@ You can safely ignore this error message:
 grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map
 ~~~
 
-Then shutdown the VM. From now you can set `pvgrub2` as VM kernel and it will
+Then shutdown the VM.
-start kernel configured within VM.
+Now you can set `pvgrub2` as the VM kernel and it will start the kernel configured within your VM.
 
-When starting the VM you can safely ignore any warnings about a missing module 'dummy-hcd'
+When starting the VM you can safely ignore any warnings about a missing module 'dummy-hcd'.
+
+**Note:** on first boot the VM will automatically allocate swap space.
+This can take a while to complete- longer than your `qrexec_timeout` setting, which will make the VM appear to have hung on boot.
+To confirm this is the case, see [Troubleshooting](/doc/managing-vm-kernel/#troubleshooting) below or just wait for five minutes and shutdown the VM.
+It should respond normally on future boots.
 
 ### Troubleshooting
 
-In case of problems, you can access VM console (using `sudo xl console VMNAME` in dom0) to access
+In case of problems, you can access the VM console using `sudo xl console VMNAME` in dom0, then access the GRUB menu.
-GRUB menu. You need to call it just after starting VM (until `GRUB_TIMEOUT`
+You need to call it just after starting the VM (until `GRUB_TIMEOUT` expires); for example, in a separate dom0 terminal window.
-expires) - for example in separate dom0 terminal window.
 
-In any case you can later access VM logs (especially VM console log (`guest-VMNAME.log`). 
+In any case you can later access the VM's logs (especially the VM console log `guest-VMNAME.log`).
 
-You can always set kernel back to some dom0-provided value to fix VM kernel installation.
+You can always set the kernel back to some dom0-provided value to fix a VM kernel installation.

configuration/multiboot.md

@@ -178,7 +178,7 @@ If you install Qubes without making any backups beforehand, don't worry.
 If you didn't overwrite the original partitions, then it is usually
 possible to recover your old systems relatively easily, as described above.
 
-If you decided to use a shared /boot and *dont* have backups of your previous
+If you decided to use a shared /boot and *don't* have backups of your previous
 grub config, it is quite easy to fix this.  
 This example may help.  
 

configuration/mutt.md

@@ -25,7 +25,9 @@ not very convenient.
 Installation
 ------------
 
-`yum install mutt`
+`dnf install mutt cyrus-sasl-plain`
+
+`cyrus-sasl-plain` package is necessary for SMTP authentication to work.
 
 Configuration
 -------------

configuration/network-bridge-support.md

@@ -42,12 +42,12 @@ First, retrieve the attachment of this Wifi article in dom0. Then apply the thre
 
 Finally restart the qubes manager GUI.
 
-A new option is now available in the AppVM Settings to enable set the NetVM in bridge mode. For a bridged AppVM, you should the select a netvm instead of a firewall vm, enabled the Bridge option and restart your AppVM.
+An option is available in the AppVM Settings to enable setting the NetVM in bridge mode. For a bridged AppVM, you should then select a NetVM instead of a FirewallVM/  ProxyVM, enable the Bridge option, and restart your AppVM.
 
 NetVM patch (Qubes R2B2)
 ------------------------
 
-You need to modify manually the NetVM iptable script inside the NetVM. The reason is that by default the NetVM only accept traffic coming from network interfaces called vif\* (in our case, we will use an additional interface called bridge0. The second reason is that all trafic is NATed by default. In our case, we want to forward traffic from the bridge interface without modifying it, while NATing traffic coming from vif\* interfaces.
+You need to modify manually the NetVM iptable script inside the NetVM. The reason is that by default the NetVM only accepts traffic coming from network interfaces called vif\* (in our case, we will use an additional interface called bridge0. The second reason is that all trafic is NATed by default. In our case, we want to forward traffic from the bridge interface without modifying it, while NATing traffic coming from vif\* interfaces.
 
 Modify manually the Template you use for your NetVM (not the NetVM itself). This is by default fedora-x86\_64. Edit the file /etc/sysconfig/iptables. You need to modify two parts of the file.
 
@@ -95,7 +95,7 @@ This requires:
 
 Note: A wireless interface cannot be bridged.
 
-The bridge edition GUI is somehow buggy as it does not remember all the parameter you setup. You can fix it by editing manually the files in /etc/NetworkManager/system-connections/. Here is one example for these files:
+The bridge edition GUI is somewhat buggy as it does not remember all the parameters you set up. You can fix it by editing manually the files in /etc/NetworkManager/system-connections/. Here is one example for these files:
 
 -   Bridge-DHCP
 
@@ -137,7 +137,7 @@ Note: Do not forget to put stp=false if you bridge only eth0 because sending BPD
     slave-type=bridge
     ~~~
 
-If you do not manager to start your bridge, you can start it manually from a NetVM terminal:
+If you do not manage to start your bridge, you can start it manually from a NetVM terminal:
 
 ~~~
 $ nmcli con up id bridge0-eth0

configuration/network-printer.md

@@ -14,27 +14,42 @@ Configuring a network printer for Qubes AppVMs
 Where to configure printers and install drivers?
 ------------------------------------------------
 
-One would normally want to configure a printer in a template VM, rather than in particular AppVMs. This is because all the global settings made to AppVMs (those stored in its /etc, as well as binaries installed in /usr) would be discarded upon AppVM shutdown. When printer is added and configured in a template VM, then all the AppVMs based on this template should automatically be able to use it (without the need for the template VM to be running, of course).
+One would normally want to configure a printer in a template VM, rather than in particular AppVMs.
+This is because all the global settings made to AppVMs (those stored in its /etc, as well as binaries installed in /usr) would be discarded upon AppVM shutdown. 
+When printer is added and configured in a template VM, then all the AppVMs based on this template should automatically be able to use it (without the need for the template VM to be running, of course).
 
 Alternatively one can add a printer in a standalone VM, but this would limit the printer usage to this particular VM.
 
 Security considerations for network printers and drivers
 --------------------------------------------------------
 
-Some printers require third-party drivers, typically downloadable from the vendor's website. Such drivers are typically distributed in a form of ready to install RPM packages. However, they are often unsigned, and additionally the downloads are available via HTTP connections only. As a result, installation of such third-party RPMs in a default template VM exposes a risk of compromise of this template VM, which, in turn, leads automatically to compromise of all the AppVMs based on the template. (Again, it's not buggy or malicious drivers that we fear here, but rather malicious installation scripts for those drivers).
+Some printers require third-party drivers, typically downloadable from the vendor's website. 
+Such drivers are typically distributed in a form of ready to install RPM packages. 
+However, they are often unsigned, and additionally the downloads are available via HTTP connections only.
+As a result, installation of such third-party RPMs in a default template VM exposes a risk of compromise of this template VM, which, in turn, leads automatically to compromise of all the AppVMs based on the template. 
+(Again, it's not buggy or malicious drivers that we fear here, but rather malicious installation scripts for those drivers).
 
-In order to mitigate this risk, one might consider creating a custom template (i.e. clone the original template) and then install the third-party, unverified drivers there. Such template might then be made the default template for [Disposable VM creation](/doc/dispvm/), which should allow one to print any document by right-clicking on it, choosing "Open in Disposable VM" and print from there. This would allow to print documents from more trusted AppVMs (based on a trusted default template, that is not poisoned by third-party printer drivers).
+In order to mitigate this risk, one might consider creating a custom template (i.e. clone the original template) and then install the third-party, unverified drivers there.
+Such template might then be made a DVM template for [Disposable VM creation](/doc/dispvm/), which should allow one to print any document by right-clicking on it, choosing "Open in Disposable VM" and print from there.
+This would allow to print documents from more trusted AppVMs (based on a trusted default template that is not poisoned by third-party printer drivers).
 
-However, one should be aware that most (all?) network printing protocols are insecure, unencrypted protocols. This means, that an attacker who is able to sniff the local network, or who is controlling the (normally untrusted) Qubes NetVM, will likely to be able to see the documents being printed. This is a limitation of today's printers and printing protocols, something that cannot be solved by Qubes or any other OS.
+However, one should be aware that most (all?) network printing protocols are insecure, unencrypted protocols. 
+This means, that an attacker who is able to sniff the local network, or who is controlling the (normally untrusted) Qubes NetVM, will likely to be able to see the documents being printed.
+This is a limitation of today's printers and printing protocols, something that cannot be solved by Qubes or any other OS.
 
-Additionally, the printer drivers as well as CUPS application itself, might be buggy and might got exploited when talking to a compromised printer (or by an attacker who controls the local network, or the default NetVM). Consider not using printing from your more trusted AppVMs for this reason.
+Additionally, the printer drivers as well as CUPS application itself, might be buggy and might get exploited when talking to a compromised printer (or by an attacker who controls the local network, or the default NetVM).
+Consider not using printing from your more trusted AppVMs for this reason.
 
 Steps to configure a network printer in a template VM
 ----------------------------------------------------------
 
 1.  Start the "Printer Settings" App in a template VM (either via Qubes "Start Menu", or by launching the `system-config-printer` in the template).
-2.  Add/Configure the printer in the same way as one would do on any normal Linux. Be sure to allow network access from the template VM to your printer, as normally the template VM is not allowed any network access, except to the Qubes proxy for software installation. One can use Qubes Manager to modify firewall rules for particular VMs.
+2.  Add/Configure the printer in the same way as one would do on any normal Linux.
+  You may need to allow network access from the template VM to your printer to complete configuration, as normally the template VM is not allowed any network access except to the Qubes proxy for software installation.
+  One can use Qubes Manager to modify firewall rules for particular VMs.
 3.  Optional: Test the printer by printing a test page. If it works, shut down the template VM.
-4.  Open an AppVM (make sure it's based on the template where you just installed the printer, normally all AppVMs are based on the default template), and test if printing works. If it doesn't then probably the AppVM doesn't have networking access to the printer -- in that case adjust the firewall settings for that AppVM in Qubes Manager. Also, make sure that the AppVM gets restarted after the template was shutdown.
+4.  Open an AppVM (make sure it's based on the template where you just installed the printer, normally all AppVMs are based on the default template), and test if printing works.
+  If it doesn't then probably the AppVM doesn't have networking access to the printer -- in that case adjust the firewall settings for that AppVM in Qubes Manager. 
+  Also, make sure that the AppVM gets restarted after the template was shutdown.
 5.  Alternatively if you do not want to modify the firewall rules of the template VM (that have security scope) you can simply shut down the template VM without trying to print the test page (which will not work), start or restart an AppVM based on the template and test printing there.
 

configuration/postfix.md

@@ -99,14 +99,14 @@ alias_maps = hash:/etc/aliases
 @localhost your.mail@example.com
 ~~~
 
-`/usr/local/etc/postfix/sender_relay`. This is important file. Put there all your SMTP servers. Pay attention to port (smtp/submission). Square brackets have their special meaning, they are almost certainly needed. For more info consult Postfix manual.
+`/usr/local/etc/postfix/sender_relay`. This is an important file. Put all your SMTP servers there. Pay attention to port (smtp/submission). Square brackets have their special meaning, they are almost certainly needed. For more info consult Postfix manual.
 
 ~~~
 your.mail@exmaple.com         [mail.example.com]:submission
 your.other@mail.com         [smtp.mail.com]:smtp
 ~~~
 
-`/usr/local/etc/postfix/saslpass`. Here you put passwords to above mentioned servers. It depends on provider if you need to put whole email as username or just the part before `@`.
+`/usr/local/etc/postfix/saslpass`. Here you put passwords to above mentioned servers. It depends on your provider if you need to put whole email as username or just the part before `@`.
 
 ~~~
 [mail.example.com]:submission     your.mail:y0urP4ssw0rd

configuration/resize-disk-image.md

@@ -4,110 +4,98 @@ title: Resize Disk Image
 permalink: /doc/resize-disk-image/
 redirect_from:
 - /en/doc/resize-disk-image/
+- /en/doc/resize-root-disk-image/
 - /doc/ResizeDiskImage/
+- /doc/ResizeRootDiskImage/
 - /wiki/ResizeDiskImage/
+- /wiki/ResizeRootDiskImage/
 ---
 
 Resize Disk Image
 -----------------
 
-There are several disk images which can be easily extended. But pay attention to the overall consumed space of your sparse disk images.
+There are several disk images which can be easily extended, but pay attention to the overall consumed space of your sparse/thin disk images.
+See also [OS Specific Follow-up Instructions](/doc/resize-disk-image/#os-specific-follow-up-instructions) at the end of this page.
 
-### Private disk image
 
-1048576 MB is the maximum size which can be assigned to a private storage through qubes-manager.
+### Template disk image (R4.0)
 
-To grow the private disk image of a AppVM beyond this limit [qubes-grow-private](/doc/dom0-tools/qvm-grow-private/) can be used:
+If you want install a lot of software in your TemplateVM, you may need to increase the amount of disk space your TemplateVM can use. 
+*Make sure changes in the TemplateVM between reboots don't exceed 10G.*
+
+1.  Resize the *root image* using Qubes version specific procedure below.
+2.  Start the template.
+3.  Resize the filesystem using OS appropriate tools (Qubes will handle this automatically under Linux).
+4.  Verify available space in the template using `df -h` or OS specific tools.
+5.  Shutdown the template.
+
+### Template disk image (R3.2)
+
+If you want install a lot of software in your TemplateVM, you may need to increase the amount of disk space your TemplateVM can use. 
+*Make sure changes in the TemplateVM between reboots don't exceed 10G.*
+
+1.  Make sure that all the VMs based on this template are shut down (including netvms etc).
+2.  Resize the *root image* using Qubes version specific procedure below.
+3.  If any netvm/proxyvm used by this template is based on it, set template's netvm to none.
+4.  Start the template.
+5.  Resize the filesystem using OS appropriate tools (Linux is `sudo resize2fs /dev/mapper/dmroot`).
+6.  Verify available space in the template using `df -h` or OS specific tools.
+7.  Shutdown the template.
+8.  Restore original netvm setting (if changed), and check firewall settings (setting netvm to none causes the firewall to reset to "block all")
+
+### Expand disk image (R4.0)
+
+1048576 MiB is the maximum size which can be assigned to storage through Qube Manager.
+
+To grow the root or private disk image of an AppVM beyond this limit, `qvm-volume` can be used:
 
 ~~~
-qvm-grow-private <vm-name> <size>
+qvm-volume extend <vm_name>:root <size>
+~~~
+OR
+~~~
+qvm-volume extend <vm_name>:private <size>
 ~~~
 
 Note: Size is the target size (i.e. 4096MB or 16GB, ...), not the size to add to the existing disk.
 
-### Shrinking private disk image (Linux VM)
+### Expand disk image (R3.2)
 
-**This operation is dangerous and this is why it isn't available in standard Qubes tools. If you have enough disk space, it is safer to create new VM with smaller disk and move the data.**
+1048576 MB is the maximum size which can be assigned to storage through Qubes Manager.
 
-The basic idea is to:
+To grow the private disk image of an AppVM beyond this limit, `qvm-grow-root` or [qvm-grow-private](/doc/dom0-tools/qvm-grow-private/) can be used:
-
-1.  Shrink filesystem on the private disk image.
-2.  Then shrink the image.
-
-Ext4 does not support online shrinking, so can't be done as convenient as image grown. Note that we don't want to touch the VM filesystem directly in dom0 for security reasons. First you need to start VM without `/rw` mounted. One of the possibility is to interrupt its normal startup by adding `rd.break` kernel option:
 
 ~~~
-qvm-prefs -s <vm-name> kernelopts rd.break
+qvm-grow-root <vm-name> <size>
-qvm-start --no-guid <vm-name>
+~~~
+OR
+~~~
+qvm-grow-private <vm-name> <size>
 ~~~
 
-And wait for qrexec connect timeout (or simply press Ctrl-C). Then you can connect to VM console and shrink the filesystem:
+Note: Size is the target size (i.e. 4096MB or 16GB, ...), not the size to add to the existing disk. 
 
-~~~
+### Resize a StandaloneVM Root Image
-sudo xl console <vm-name>
-# you should get dracut emergency shell here
-mount --bind /dev /sysroot/dev
-chroot /sysroot
-mount /proc
-e2fsck -f /dev/xvdb
-resize2fs /dev/xvdb <new-desired-size>
-umount /proc
-exit
-umount /sysroot/dev
-poweroff
-~~~
 
-Now you can resize the image:
+For more flexibility, you may also turn your TemplateVM into a StandaloneVM.
+Doing this means it will have its own root filesystem *(StandaloneVMs use a copy of the template, instead of smart sharing)*.
+To do this run `qvm-create --standalone` from `dom0` console, then perform the [OS Specific Follow-up Instructions](/doc/resize-disk-image/#os-specific-follow-up-instructions) below.
 
-~~~
+### Shrinking a disk image
-truncate -s <new-desired-size> /var/lib/qubes/appvms/<vm-name>/private.img
-~~~
 
-**It is critical to use the same (or bigger for some safety margin) size in truncate call compared to resize2fs call. Otherwise you will loose your data!** Then reset kernel options back to default:
+Ext4 and most other filesystems do not support online shrinking, so it can't be done as conveniently as growing the image.
+Note that we don't want to touch the VM filesystem directly in dom0 for security reasons. 
 
-~~~
+1.  Create a new qube with smaller disk using Qube Manager or `qvm-create`
-qvm-prefs -s <vm-name> kernelopts default
+2.  Move data to the new qube using `qvm-copy`, backup & restore, or OS utilities
-~~~
+3.  Delete old qube using Qube Manager or `qvm-remove`
 
-Done.
+OS Specific Follow-up Instructions
+-----------------
 
->In order to avoid error, you might want to first reduce the filesystem to a smaller size than desired (say 3G), then truncate the image to the target size (for example 4G), and lastly grow the filesystem to the target size. In order to do this, after the `truncate` step, start the vm again in maintenance mode and use the following command to extend the filesystem to the correct size : `resize2fs /dev/xvdb`.
+After expanding volumes, the partition table and file-system may need to be adjusted.
->
+Use tools appropriate to the OS in your qube.
->With no argument, resize2fs grows the filesystem to match the underlying block device (the .img file you just shrunk)
+Brief instructions for Windows 7, FreeBSD, and Linux are provided below.
-
-
-### Template disk image
-
-If you want install a lot of software in your TemplateVM, you may need to increase the amount of disk space your TemplateVM can use. See also additional information and caveats about [resizing the root disk image].
-
-1.  Make sure that all the VMs based on this template are shut off (including netvms etc).
-2.  Sanity check: verify that none of loop device are pointing at this template root.img. Run this in dom0: `sudo losetup -a`
-3.  Resize root.img file. Run this in dom0: `truncate -s <desired size> <path to root.img>` (the root.img path can be obtained from qvm-prefs).
-4.  If any netvm/proxyvm used by this template is based on it, set template netvm to none.
-5.  Start the template.
-6.  Execute `sudo resize2fs /dev/mapper/dmroot` in the template.
-7.  Verify available space in the template using `df -h`
-8.  Shutdown the template.
-9.  Restore original netvm setting (if changed), check firewall settings (setting netvm to none causes firewall reset to "block all")
-
-### HVM disk image
-
-In this example we will grow the disk image of an HVM to 30GB.
-
-First, stop/shutdown the HVM.
-
-Then, from a Dom0 terminal (in KDE: System Tools -\> Terminal Emulator) do the following:
-
-~~~
-cd /var/lib/qubes/appvms/<yourHVM>/
-ls -lh root.img  (<--verify current size of disk image)
-truncate -s 30GB root.img
-ls -lh root.img  (<--verify new size of disk image)
-~~~
-
-The partition table and file-system must be adjusted after this change.
-Use tools appropriate to the OS in your HVM. Brief instructions for Windows 7,
-FreeBSD, and Linux are provided below.
 
 #### Windows 7
 
@@ -129,8 +117,6 @@ zpool online -e poolname ada0
 
 #### Linux
 
+Qubes will automatically grow the filesystem for you on AppVMs but not HVMs (or Template root images on R3.2).
 You will see that there is unallocated free space at the end of your primary disk.
-You can use standard linux tools like fdisk and mkfs to make this space available.
+You can use standard linux tools like `fdisk` and `resize2fs` to make this space available.
-
-
-[resizing the root disk image]: /doc/resize-root-disk-image/

configuration/resize-root-disk-image.md

@@ -1,54 +0,0 @@
----
-layout: doc
-title: Resize Root Disk Image
-permalink: /doc/resize-root-disk-image/
-redirect_from:
-- /en/doc/resize-root-disk-image/
-- /doc/ResizeRootDiskImage/
-- /wiki/ResizeRootDiskImage/
----
-
-Resize Root Disk Image
-----------------------
-
-The safest way to increase the size of `root.img` is to turn your TemplateVM into a StandaloneVM. Doing this means it will have it's own root filesystem *(StandaloneVMs use a copy of template, instead of smart sharing)*. To do this run `qvm-create --standalone` from `dom0` Konsole.
-
-### Resize a StandaloneVM Root Image
-
-In `dom0` Konsole run the following command (replace the size and path):
-
-~~~
-truncate -s 20G /var/lib/qubes/appvms/standalonevm/root.img
-~~~
-
-Then start Terminal for this StandaloneVM and run:
-
-~~~
-sudo resize2fs /dev/mapper/dmroot
-~~~
-
-Shutdown the StandaloneVM and you will have extended the size of it's `root.img`
-
-
-### Resize a TemplateVM Root Image
-
-Shut down the TemplateVM, as well as all VMs based on that template (since they
-share `root.img`).
-In `dom0` Konsole run the following command (replace the size and path):
-*Make sure changes in the TemplateVM between reboots didn't exceed 10G.*
-
-~~~
-truncate -s 20G /var/lib/qubes/vm-templates/fedora-21/root.img
-~~~
-
-Then start only the TemplateVM and run the following. Note that if you are
-resizing the TemplateVM used by, e.g., your NetVM, you may need to disable
-networking so when the TemplateVM is started, it does not autostart other VMs
-based on the same `root.img`. Otherwise you will get an error message `Nothing
-to do!`.
-
-~~~
-sudo resize2fs /dev/mapper/dmroot
-~~~
-
-Shutdown the TemplateVM and you will have extended the size of it's `root.img`.

configuration/rxvt.md

@@ -16,12 +16,16 @@ Rxvt
 Installation
 ------------
 
-`yum install rxvt-unicode-256color-ml` will bring both base `rxvt-unicode` and extension. Let me also recommend excellent Terminus font: `yum install terminus-fonts`.
+`dnf install rxvt-unicode-256color-ml` will bring both base `rxvt-unicode` and extension.
+Let me also recommend excellent Terminus font: `dnf install terminus-fonts`.
 
 Xresources
 ----------
 
-In TemplateVM create file `/etc/X11/Xresources.urxvt` and paste config below. `!`-lines are comments and may be left out. `#`-lines are directives to CPP (C preprocessor) and are necessary. This shouldn't go to `/etc/X11/Xresources`, because that file is not preprocessed by default.
+In TemplateVM create file `/etc/X11/Xresources.urxvt` and paste config below.
+`!`-lines are comments and may be left out.
+`#`-lines are directives to CPP (C preprocessor) and are necessary.
+This shouldn't go to `/etc/X11/Xresources`, because that file is not preprocessed by default.
 
 ~~~
 ! CGA colour palette
@@ -132,7 +136,8 @@ URxvt.insecure:                 False
 !URxvt.termName:                rxvt-256color
 ~~~
 
-Then create script to automatically merge those to xrdb. File `/etc/X11/xinit/xinitrc.d/urxvt.sh`:
+Then create script to automatically merge those to xrdb.
+File `/etc/X11/xinit/xinitrc.d/urxvt.sh`:
 
 ~~~
 #!/bin/sh
@@ -143,4 +148,5 @@ Then create script to automatically merge those to xrdb. File `/etc/X11/xinit/xi
 Shortcuts
 ---------
 
-For each AppVM, go to *Qubes Manager \> VM Settings \> Applications*. Find `rxvt-unicode` (or `rxvt-unicode (256-color) multi-language`) and add.
+For each AppVM, go to *Qubes Manager \> VM Settings \> Applications*. 
+Find `rxvt-unicode` (or `rxvt-unicode (256-color) multi-language`) and add.

configuration/salt.md

@@ -242,7 +242,7 @@ compromise cannot spread from one VM to another.
 
 ## Writing Your Own Configurations
 
-Let's start with quick a example:
+Let's start with a quick example:
 
     my new and shiny VM:
       qvm.present:

configuration/secondary-storage.md

@@ -11,33 +11,60 @@ redirect_from:
 Storing AppVMs on Secondary Drives
 ==================================
 
-Suppose you have a fast but small primary SSD and a large but slow secondary
+Suppose you have a fast but small primary SSD and a large but slow secondary HDD.
-HDD.  You want to store a subset of your AppVMs on the HDD. In dom0:
+You want to store a subset of your AppVMs on the HDD.
 
-1. `# mv /var/lib/qubes/appvms/my-new-appvm
+### R4.0 ###
-/path/to/secondary/drive/my-new-appvm`
 
-2. `# ln -s /path/to/secondary/drive/my-new-appvm /var/lib/qubes/appvms/`
+Qubes 4.0 is more flexible than earlier versions about placing different VMs on different disks. 
+For example, you can keep templates on one disk and AppVMs on another, without messy symlinks.
 
-Now, `my-new-appvm` will behave as if it were still stored on the primary SSD
+Assuming you have already created a separate [volume group](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/logical_volume_manager_administration/vg_admin#VG_create) and [thin pool](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/logical_volume_manager_administration/thinly_provisioned_volume_creation) (not thin volume) for your HDD, first collect some information in a dom0 terminal:
-(except that it will probably be slower, since it's actually stored on the
-secondary HDD).
 
-Known Issues
+    sudo pvs
-------------
+    sudo lvs
 
- * The above procedure does **not** interfere with [Qubes Backup][]. However,
+Take note of the VG and thin pool names for your HDD, then register it with Qubes:
-   attempting to symlink a `private.img` file (rather than the whole AppVM
-   directory) is known to prevent the `private.img` file from being backed up.
-   The same problem may occur if the above procedure is attempted on a
-   [TemplateVM][]. [[1]]
 
- * This issue applies only to R3.1, not R3.2 or later:
+    # pool_name is a freely chosen pool name
-   After implementing the above procedure, starting `my-new-appvm` will cause
+    # vg_name is LVM volume group name
-   dom0 notifications to occur stating that loop devices have been attached to
+    # thin_pool_name is LVM thin pool name
-   dom0. This is normal. (No untrusted devices are actually being mounted to
+    qvm-pool --add pool_name lvm_thin -o volume_group=vg_name,thin_pool=thin_pool_name
-   dom0.) Do not attempt to detach these disks. (They will automatically be
+    
-   detached when you shut down the AppVM.) [[2]]
+Now, you can create qubes in that pool:
+
+    qvm-create -P pool_name --label red vmname
+
+It isn't possible to directly migrate an existing qube to the new pool, but you can clone it there, then remove the old one:
+
+    qvm-clone -P pool_name old_name new_name
+    qvm-remove old_name
+
+If that was a template, or other qube referenced elsewhere (NetVM or such), you will need to adjust those references manually after moving.
+For example:
+
+    qvm-prefs appvm_based_on_old_name_template template new_name
+
+In theory, you can still use file-based disk images ("file" pool driver), but it lacks some features such as you won't be able to do backups without shutting down the qube.
+
+### R3.2 ###
+
+In dom0:
+
+    mv /var/lib/qubes/appvms/my-new-appvm /path/to/secondary/drive/my-new-appvm
+    ln -s /path/to/secondary/drive/my-new-appvm /var/lib/qubes/appvms/
+
+Now, `my-new-appvm` will behave as if it were still stored on the primary SSD (except that it will probably be slower, since it's actually stored on the secondary HDD).
+
+ * The above procedure does **not** interfere with [Qubes Backup][].
+   However, attempting to symlink a `private.img` file (rather than the whole AppVM directory) is known to prevent the `private.img` file from being backed up.
+   The same problem may occur if the above procedure is attempted on a [TemplateVM][]. [[1]]
+
+ * After implementing the above procedure, starting `my-new-appvm` will cause dom0 notifications to occur stating that loop devices have been attached to dom0.
+   This is normal. 
+   (No untrusted devices are actually being mounted to dom0.)
+   Do not attempt to detach these disks.
+   (They will automatically be detached when you shut down the AppVM.) [[2]]
 
 [Qubes Backup]: /doc/BackupRestore/
 [TemplateVM]: /doc/Templates/

customization/bind-dirs.md

@@ -8,14 +8,14 @@ redirect_from:
 
 # How to make any file in a TemplateBasedVM persistent using bind-dirs #
 
-## What is bind-dirs? ##
+## What are bind-dirs? ##
 
 With [bind-dirs](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/vm-systemd/bind-dirs.sh)
 any arbitrary files or folders can be made persistent in TemplateBasedVMs.
 
 ## What is it useful for? ##
 
-In a TemplateBasedVM all of the file system comes from the template except /home and /usr/local.
+In a TemplateBasedVM all of the file system comes from the template except `/home`, `/usr/local`, and `/rw`.
 This means that changes in the rest of the filesystem are lost when the TemplateBasedVM is shutdown.
 bind-dirs provides a mechanism whereby files usually taken from the template can be persisted across reboots.
 
@@ -39,7 +39,6 @@ Inside your TemplateBasedVM.
 3. Edit the file 50_user.conf to append a folder or file name to the `binds` variable. (In the following example we are using folder `/var/lib/tor`. You can replace that name with a folder or file name of your choice.)
 
        binds+=( '/var/lib/tor' )
-       binds+=( '/etc/tor/torrc' )
 
 Multiple entries are possible, each on a separate line.
 
@@ -49,7 +48,7 @@ Multiple entries are possible, each on a separate line.
 
 6. Done.
 
-If you added for example folder `/var/lib/tor` to the `binds` variable, from now any files within that folder would persist reboots. If you added for example file `/etc/tor/torrc` to the `binds` variable, from now any modifications to that file would persist reboots.
+If you added for example folder `/var/lib/tor` to the `binds` variable, from now on any files within that folder will persist reboots. If you added for example file `/etc/tor/torrc` to the `binds` variable, from now on any modifications to that file will persist reboots.
 
 ## Other Configuration Folders ##
 
@@ -89,7 +88,7 @@ For example, if you wanted to make `/var/lib/tor` non-persistant in `sys-whonix`
 binds=( "${binds[@]/'/var/lib/tor'}" )
 ~~~
 
-(Editing `/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf` directly is recommended against, since such changes get lost when that file is changed in the package on upgrades.)
+(Editing `/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf` directly is strongly discouraged, since such changes get lost when that file is changed in the package on upgrades.)
 
 ## Discussion ##
 

customization/dark-theme.md

@@ -70,7 +70,7 @@ This is the result after applying the steps described here.
 
         ![result black Qubes Manager](/attachment/wiki/Dark-Theme/kde-black-qubes-manager.png)
 
-**Note:** Chaning the `Window Decorations` from `Plastik for Qubes` will remove the border color and the VM name. The problem with `Plastik for Qubes` is, that it does not overwrite the background and text color for Minimize, Maximize and Close buttons. The three button are therefor hard to read.
+**Note:** Changing the `Window Decorations` from `Plastik for Qubes` will remove the border color and the VM name. The problem with `Plastik for Qubes` is, that it does not overwrite the background and text color for Minimize, Maximize and Close buttons. The three button are therefore hard to read.
 
 Dark XCFE in Dom0
 -----------------
@@ -109,7 +109,7 @@ This is the result after applying the steps described here.
 Dark App VM, Template VM, Standalone VM, HVM (Linux Gnome)
 ==========================================================
 
-Almost all Qubes VM's are based on the Gnome desktop. Therefor the description below is focused on the Gnome Desktop Environment.
+Almost all Qubes VMs use default applications based on the GTK toolkit. Therefore the description below is focused on tools from the Gnome Desktop Environment.
 
 Using "Gnome-Tweak-Tool"
 ------------------------
@@ -120,7 +120,7 @@ The advantage of creating a dark themed Template VM is, that each AppVM which is
 
 1. Start VM
 
-    **Note:** In case of App VM start the Template on which the AppVM is based on.
+    **Note:** Remember that if you want to make the change persistent, the change needs to be made in the TemplateVM, not the AppVM.
 
 2. Install `Gnome-Tweak-Tool`
 
@@ -174,7 +174,7 @@ Manually works for Debian, Fedora and Archlinux.
 
 1. Start VM
 
-    **Note:** In case of App VM start the Template on which the AppVM is based on.
+    **Note:** Remember that if you want to make the change persistent, the change needs to be made in the TemplateVM, not the AppVM.
 
 2. Enable `Global Dark Theme`
 

customization/dispvm-customization.md

@@ -10,10 +10,65 @@ redirect_from:
 ---
 
 Disposable VM Customization
-====================
+============================
 
-Changing the DVM Template
+Qubes 4.0
--------------------------
+----------
+
+Disposable VM (DispVM) in Qubes 4.0 can be based on any TemplateBasedVM. You can also choose to use different AppVMs for different Disposable VMs. To prepare AppVM to be a base for Disposable VM, you need to set `template_for_dispvms` property, for example:
+
+    [user@dom0 ~]$ qvm-prefs fedora-26-dvm template_for_dispvms True
+
+Additionally, if you want to have menu entries for starting applications in Disposable VM based on this AppVM (instead of in the AppVM itself), you can achieve it with `appmenus-dispvm` feature:
+
+    [user@dom0 ~]$ qvm-features fedora-26-dvm appmenus-dispvm 1
+
+### Creating new Disposable VM base AppVM ###
+
+In Qubes 4.0, you're no longer restricted to a single DVM Template. Instead, you can create as many as you want. Whenever you start a new Disposable VM, you can choose to base it on whichever DVM Template you like.
+To create new DVM Template, lets say `custom-dvm`, based on `debian-9` template, use following commands:
+
+    [user@dom0 ~]$ qvm-create --template debian-9 --label red custom-dvm
+    [user@dom0 ~]$ qvm-prefs custom-dvm template_for_dispvms True
+    [user@dom0 ~]$ qvm-features custom-dvm appmenus-dispvm 1
+
+Additionally you may want to set it as default DVM Template:
+
+    [user@dom0 ~]$ qubes-prefs default_dispvm custom-dvm
+
+The above default is used whenever a qube request starting a new Disposable VM 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/qrexec3/#extra-keywords-available-in-qubes-40-and-later) for details.
+
+If you wish to use the `fedora-minimal` template as a DVM Template, see the "DVM Template" use case under [fedora-minimal customization](/doc/templates/fedora-minimal/#customization).
+
+
+### Customization of Disposable VM ###
+
+It is possible to change the settings for each new Disposable VM (DispVM). This can be done by customizing the base AppVM:
+
+1.  Start a terminal in the `fedora-26-dvm` qube (or another base for DispVM) 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 DispVM based on that VM (`fedora-26-dvm`). Not in that VM (`fedora-26-dvm`) itself).
+
+        [user@dom0 ~]$ qvm-run -a fedora-26-dvm gnome-terminal
+
+2.  Change the qube's settings and/or applications, as desired. Some examples of changes you may want to make include:
+    -   Changing Firefox's default startup settings and homepage.
+    -   Changing default editor, image viewer.
+    -   Changing the DispVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DispVM, you can choose your desired ProxyVM manually (by changing the newly-started DispVMs settings). This is useful if you sometimes wish to use a DispVM with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DispVM.
+
+4.  Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal).
+
+
+### Adding programs to Disposable VM Application Menu ###
+
+For added convenience, arbitrary programs can be added to the Application Menu of the Disposable VM. 
+
+In order to do that, select "Qube settings" entry in selected base AppVM, 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.
+
+Qubes 3.2
+----------
+
+### Changing the DVM Template ###
 
 You may want to use a non-default template the [DVM Template](/doc/glossary/#dvm-template). One example is to use a less-trusted template with some less trusted, third-party, often unsigned, applications installed, such as e.g. third-party printer drivers.
 
@@ -37,8 +92,7 @@ One can easily verify if the new Disposable VM template is indeed based on a cus
 If you wish to use the `fedora-minimal` template as a DVM Template, see the "DVM Template" use case under [fedora-minimal customization](/doc/templates/fedora-minimal/#customization).
 
 
-Customization of Disposable VM
+### Customization of Disposable VM ###
-------------------------------
 
 It is possible to change the settings of each new Disposable VM (DispVM). This can be done by customizing the DispVM template:
 
@@ -50,7 +104,7 @@ It is possible to change the settings of each new Disposable VM (DispVM). This c
 2.  Change the VM's settings and/or applications, as desired. Note that currently Qubes supports exactly one DispVM template, so any changes you make here will affect all DispVMs. Some examples of changes you may want to make include:
     -   Changing Firefox's default startup settings and homepage.
     -   Changing Nautilus' default file preview settings.
-    -   Changing the DispVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DispVM, you can choose your desired ProxyVM manually (by changing the newly-started DipsVMs settings). This is useful if you sometimes wish to use a DispVM with a TorVM, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DispVM.
+    -   Changing the DispVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DispVM, you can choose your desired ProxyVM manually (by changing the newly-started DispVM's settings). This is useful if you sometimes wish to use a DispVM with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DispVM.
 
 3.  Create an empty `/home/user/.qubes-dispvm-customized` file in the VM (not in dom0):
 
@@ -70,10 +124,9 @@ It is possible to change the settings of each new Disposable VM (DispVM). This c
 **Note:** All of the above requires at least qubes-core-vm \>= 2.1.2 installed in template.
 
 
-Adding arbitrary programs to Disposable VM Application Menu
+### Adding arbitrary programs to Disposable VM Application Menu ###
------------------------------------------------------------
 
-For added convenience, arbitrary programs can be added to the Application Menu of the Disposable VM. In order to do that create (e.g.) `arbitrary.desktop` file in `/usr/share/applications` in Dom0. That file will point to the desired program. Use the following template for the file:
+For added convenience, arbitrary programs can be added to the Application Menu of the Disposable VM. In order to do that create (e.g.) `arbitrary.desktop` file in `/usr/local/share/applications` in Dom0. That file will point to the desired program. Use the following template for the file:
 
     [Desktop Entry]
     Version=1.0

customization/fedora-minimal-template-customization.md

@@ -16,7 +16,7 @@ Template installation
 > [dom0]#qubes-dom0-update qubes-template-fedora-26-minimal
 
 
-*Note*: If you have doubts about a set of tool or package you want to install, start installing and testing it in an AppVM. 
+*Note*: If you have doubts about a set of tools or package you want to install, start installing and testing it in an AppVM. 
 You can then reproduce it later in your TemplateVM if you are satisfied.
 That is the template philosophy in QubesOS.
 
@@ -36,7 +36,7 @@ Administration (documented)
 Some recommendations here: check your current network using the Network manager applet (eg: 192.168.1.65). 
 Then run nmap in your current AppVM/TemplateVM to search for the selected printer/equipment: 
 	nmap -sP 192.168.1.-. 
-Don't forget to open temporarily the Qubes Firewall if you are doing this in a TemplateVM.
+Don't forget to temporarily allow traffic via the Qubes Firewall if you are doing this in a TemplateVM.
 
 Administration (undocumented)
 -------------------------------------------------
@@ -101,7 +101,7 @@ Manual operations
 
 - Don't forget to restart your TemplateVM or only the cups service when you installed cups (systemctl start cups)
 
-- First you need to search for your printer. If you don't know its name or IP, search for it using nmap: check your current network using the Network manager applet (eg: 192.168.1.65). Then run nmap in your current AppVM/TemplateVM to search for the selected printer/equipement: nmap -sP 192.168.1.-. Don't forget to allow temporarily the Qubes Firewall if you are inside a TemplateVM.
+- First you need to search for your printer. If you don't know its name or IP, search for it using nmap: check your current network using the Network manager applet (eg: 192.168.1.65). Then run nmap in your current AppVM/TemplateVM to search for the selected printer/equipement: nmap -sP 192.168.1.-. Don't forget to temporarily allow traffic via the Qubes Firewall if you are inside a TemplateVM.
 
 - Once you identified your printer, run system-config-printer GUI to install your printer
 
@@ -142,13 +142,13 @@ If you do not use password protected gpg keys, there is no need to install this
 GUI themes
 -----------------
 
-Managing GUI theme / appearance is often complex because when you do not want to depends on a specific desktop system.
+Managing GUI theme / appearance is often complex because when you do not want to depend on a specific desktop system.
 
 For this reason, we need to customize themes for each GUI framework that our application depends on.
 
 This often includes GTK2, GTK3 (which us a different configuration/themes than GTK2), Qt.
 
-The apparance of Windows can only be changed in dom0, however, the appearance of all buttons, menus, icons, widgets are specific to each AppVM.
+The appearance of Windows can only be changed in dom0, however, the appearance of all buttons, menus, icons, widgets are specific to each AppVM.
 
 ### Packages
 
@@ -162,7 +162,7 @@ You can check your currently installed theme packages (to eventually remove them
 
 ### Tweaking theme and appearance
 
-First you can get an insight of installed Gtk theme and see how it will appears using lxappearance.
+First you can get an insight of installed Gtk theme and see how it will appear using lxappearance.
 
 I recommend not applying settings using lxappearance (do not click on apply) because it will create multiple configuration files.
 
@@ -183,12 +183,12 @@ Cleaning the whole dconf settings is also possible by removing the following fil
 rm ~/.config/dconf/user
 ~~~
 
-*Note*: lxappearance only have effect on gtk3 theme so it won't work to change gtk2 themes (used by Firefox, Thunderbird ...).
+*Note*: lxappearance only has an effect on gtk3 themes so it won't work to change gtk2 themes (used by Firefox, Thunderbird ...).
              However, it is very lightweight and can be used to identify the name and look of themes you are interested in.
              Once you have the name, you can apply it using gsetting command line or gconf-editor.
 
-*Note*: if you really want a GUI theme editor, you can install gnome-tweak-tools, but this tool have a lot
+*Note*: if you really want a GUI theme editor, you can install gnome-tweak-tools, but this tool has a lot
-            of gnome dependencies (~150MB of dependencies). Eventually install it and uninstall it as soon as you changed your theme.
+            of gnome dependencies (~150MB of dependencies). You can install it and uninstall it as soon as you change your theme.
 
 #### Testing notes
 
@@ -265,7 +265,7 @@ Getting an uniform look for Qt & GTK is not achieved yet. A good source is on th
 Two case:
 
 1. You installed packages of the theme you selected both for Qt, GTK2 and GTK3.
-    (eg: Adwaita which is the default theme. I did not found another cross framework theme on fedora default packages).
+    (eg: Adwaita which is the default theme. I have not found another cross framework theme on fedora default packages).
 
 2. You want to use the GTK theme you selected for Qt but there is no qt package.
     In this case QGtkStyle will take precedence and convert the style automatically.

customization/language-localization.md

@@ -18,7 +18,7 @@ How to set up pinyin input in Qubes
 
 2. Close and shut down the TemplateVM. 
 
-3. Restart an AppVM which based on the template you installed `ibus-pinyin` and open a terminal.
+3. Restart an AppVM which is based on the template you installed `ibus-pinyin` in, and open a terminal.
  
 4. Run `ibus-setup`
 

customization/windows-template-customization.md

@@ -25,14 +25,14 @@ Only keep:
 
 *Note*: Windows search is recommended because it is a nightmare to find something in menus if it is not enabled (it removes the search bar from the start menu, from the explorer, and from the control panel).
 
-*Note*: Unselecting windows media, .Net and Internet Explorer will uninstall these components. on a new install it is generally old versions anyway and it will be quicker to install directly the new versions later.
+*Note*: Unselecting windows media, .Net and Internet Explorer will uninstall these components. On a new install they are generally old versions anyway and it will be quicker to install directly the new versions later.
 
 Windows services
 ---------------------------
 
 Disable the following services that are not required or have no sense in a VM context:
 
- * Base Filtering Engine (only required if your want to use Microsoft IPSEC)
+ * Base Filtering Engine (only required if you want to use Microsoft IPSEC)
  * DHCP Client
  * Function Discovery Provider Host
 
@@ -53,7 +53,7 @@ Disable the following services that are not required or have no sense in a VM co
 Windows update
 --------------------------
 
-I recommend disabling windows update (Never Check for Update) because checking for updates will start every time you start an AppVM if you don't started your template after some days.
+I recommend disabling windows update (Never Check for Update) because checking for updates will start every time you start an AppVM if you haven't started your template in a while.
 
 Running windows update is also apparently IO hungry.
 
@@ -62,10 +62,10 @@ Of course I recommend starting the template regularly and checking manually for
 System properties
 ---------------------------
 
-Right click on computer and go to Properties > Advanced > Performances:
+Right click on computer and go to Properties > Advanced > Performance:
 
- * If your don't care about visual effect, in Visual Effect select "Adjust for best performance"
+ * If you don't care about visual effect, in Visual Effect select "Adjust for best performance"
- * I personally tweak the page file size to win some place on my root.
+ * I personally tweak the page file size to gain some space on my root.
 
     In Advanced>Performances>Advanced tab, change Virtual memory:
 
@@ -75,16 +75,16 @@ Right click on computer and go to Properties > Advanced > Performances:
         4. click on set
         5. click on drive d:
         6. select customer size
-        7. use an initial size of 500 and a max size of 1000. If the page file is too small, you will notify a low memory pop up when working on windows. In this case, it often means that you should extend your AppVM RAM.
+        7. use an initial size of 500 and a max size of 1000. If the page file is too small, you will notice a low memory pop up when working on windows. In this case, it often means that you should extend your AppVM RAM.
 
  * System Protection
 
-    Here you can disable Shadow Folder because it has little sense in case of Qubes because
+    Here you can disable Shadow Folder because it has little sense in the case of Qubes because
 
-      * we do backup regularly of AppVMs/TemplateVMs;
+      * we do regular backups of AppVMs/TemplateVMs;
       * we can revert at least one template change if we break something.
 
-    Select drives where system protection is enabled and click Configure. "Turn of system protection" "Delete all restore points"
+    Select drives where system protection is enabled and click Configure. "Turn off system protection" "Delete all restore points"
 
  * Remote
 
@@ -157,7 +157,7 @@ Manual tasks that can/should be started in the template
 
             > mv root.img.clean root.img
 
-    * If don't managed to fill the free space with zeros, you can follow the following  *unsafe* undocumented procedure
+    * If it doesn't manage to fill the free space with zeros, you can follow the following *unsafe* undocumented procedure
 
         1. from dom0, go to /var/lib/templates-vm/yourtemplate
         2. check the partitioning to identify the filesystem offset of root.img

debugging/automated-tests.md

@@ -7,9 +7,12 @@ redirect_from:
 - /doc/AutomatedTests/
 ---
 
-Automatic tests
+Automated Tests
 ===============
 
+Unit and Integration Tests
+--------------------------
+
 Starting with Qubes R3 we use [python unittest][unittest] to perform automatic tests of Qubes OS. 
 Despite the name, we use it for both [unit tests](https://en.wikipedia.org/wiki/Unit_tests) and [integration tests](https://en.wikipedia.org/wiki/Integration_tests). 
 The main purpose is, of course, to deliver much more stable releases.
@@ -96,13 +99,13 @@ Example test run:
 
 ![snapshot-tests2.png](/attachment/wiki/developers/snapshot-tests2.png)
 
-## Adding a new test to core-admin
+### Adding a new test to core-admin
 After adding a new unit test to [core-admin/tests](https://github.com/QubesOS/qubes-core-admin/tree/master/tests) you'll have to make sure of two things:
 
 1. That the test will be added to the RPM file created by [QubesBuilder](/doc/qubes-builder/). For this you need to edit the [core-admin/tests/Makefile](https://github.com/QubesOS/qubes-core-admin/tree/master/tests/Makefile)
 2. That the test will be loaded by [core-admin/tests/\_\_init\_\_.py](https://github.com/QubesOS/qubes-core-admin/tree/master/tests/__init__.py)
 
-### Editing the Makefile
+#### Editing the Makefile
 To add your tests, you must append these two lines to the end of the makefile, which will copy your test and its compiled version to the right directory in the RPM file. 
 If your test is `example.py`, the appended lines would be:
 
@@ -110,8 +113,8 @@ If your test is `example.py`, the appended lines would be:
     cp example.py[co] $(DESTDIR)$(PYTHON_TESTSPATH)
 
 
-### Editing \_\_init\_\_.py
+#### Editing `__init__.py`
-You'll also need to add your test at the bottom of the \_\_init\_\_.py file, in the method `def load_tests`, in the for loop with `modname`.
+You'll also need to add your test at the bottom of the `__init__.py` file, in the method `def load_tests`, in the for loop with `modname`.
 Again, given the hypothetical `example.py` test:
 
 ~~~python
@@ -127,4 +130,25 @@ Again, given the hypothetical `example.py` test:
             ):
 ~~~
 
+
+Installation Tests with openQA
+------------------------------
+
+**URL:** <https://openqa.qubes-os.org/>  
+**Tests:** <https://github.com/marmarek/openqa-tests-qubesos>
+
+Manually testing the installation of Qubes OS is a time-consuming process.
+We use [openQA] 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.
+
+Using openQA to automatically test the Qubes installation process works as of Qubes 4.0-rc4 on 2018-01-26, provided that the versions of KVM and QEMU are new enough and the hardware has VT-x and EPT.
+KVM also supports nested virtualization, so HVM should theoretically work.
+In practice, however, either Xen or QEMU crashes when this is attempted.
+Nonetheless, PV works well, which is sufficient for automated installation testing.
+
+Thanks to an anonymous donor, our openQA system is hosted in a datacenter on hardware that meets these requirements.
+
 [unittest]: https://docs.python.org/2/library/unittest.html
+[OpenQA]: http://open.qa/
+

debugging/vm-interface.md

@@ -32,7 +32,7 @@ QubesDB
      - `none` - none
 -   `/qubes-timezone - name of timezone based on dom0 timezone. For example `Europe/Warsaw`
 -   `/qubes-keyboard` - keyboard layout based on dom0 layout. Its syntax is suitable for `xkbcomp` command (after expanding escape sequences like `\n` or `\t`). This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). This entry is created as part of gui-daemon initialization (so not available when gui-daemon disabled, or not started yet).
--   `/qubes-debug-mode` - flag whether VM have debug mode enabled (qvm-prefs setting). One of `1`, `0`
+-   `/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 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". List of currently supported services is in [qvm-service man page](/wiki/Dom0Tools/QvmService)
 -   `/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)
@@ -50,7 +50,7 @@ QubesDB
 QubesDB is also used to configure firewall in ProxyVMs. Rules are stored in
 separate key for each target VM. Entries:
 
-- `/qubes-iptables` - control entry - dom0 writing `reload` here signal `qubes-firewall` service to reload rules
+- `/qubes-iptables` - control entry - dom0 writing `reload` here signals `qubes-firewall` service to reload rules
 - `/qubes-iptables-header` - rules not related to any particular VM, should be applied before domains rules
 - `/qubes-iptables-domainrules/NNN` - rules for domain `NNN` (arbitrary number)
 in `iptables-save` format. Rules are self-contained - fill `FORWARD` iptables
@@ -59,7 +59,7 @@ final default action (`DROP`/`ACCEPT`)
 
 VM after applying rules may signal some error, writing a message to
 `/qubes-iptables-error` key. This does not exclude any other way of
-communicating problem - like a popup.
+communicating problems - like a popup.
 
 #### Firewall rules in 4.x ####
 
@@ -84,7 +84,7 @@ by space. Order of those pairs in a single rule is undefined. QubesDB enforces
 a limit on a single entry length - 3072 bytes.
 Possible options for a single rule:
 
- - `action`, values: `accept`, `drop`; this is present it every rule
+ - `action`, values: `accept`, `drop`; this is present in every rule
  - `dst4`, value: destination IPv4 address with a mask; for example: `192.168.0.0/24`
  - `dst6`, value: destination IPv6 address with a mask; for example: `2000::/3`
  - `dstname`, value: DNS hostname of destination host
@@ -98,19 +98,22 @@ Possible options for a single rule:
  echo request, valid only together with `proto=icmp`
  - `dpi`, value: Deep Packet Inspection protocol (like: HTTP, SSL, SMB, SSH, SMTP) or the default 'NO' as no DPI, only  packet filtering
 
+Options must appear in the rule in the order listed above. Duplicated options
+are forbidden.
+
 Rule matches only when all predicates matches. Only one of `dst4`, `dst6`,
 `dstname`, `specialtarget` can be used in a single rule.
 
-If tool applying firewall encounter any parse error (unknown option, invalid
+If tool applying firewall encounters any parse error (unknown option, invalid
-value etc), it should drop all the traffic coming from that `SOURCE_IP`,
+value, duplicated option, etc), it should drop all the traffic coming from that `SOURCE_IP`,
 regardless of properly parsed rules.
 
 Example valid rules:
 
 - `action=accept dst4=8.8.8.8 proto=udp dstports=53-53`
 - `action=drop dst6=2a00:1450:4000::/37 proto=tcp`
-- `specialtarget=dns action=accept`
+- `action=accept specialtarget=dns`
-- `specialtarget=dns action=drop proto=tcp` - drop DNS queries sent using TCP
+- `action=drop proto=tcp specialtarget=dns` - drop DNS queries sent using TCP
 - `action=drop`
 
 ### Keys set by VM for passing info to dom0 ###
@@ -118,7 +121,7 @@ Example valid rules:
 -   `memory/meminfo` (**xenstore**) - used memory (updated by qubes-meminfo-writer), input information for qmemman;
     - Qubes 3.x format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux.
     - Qubes 4.0+ format: used memory size in the VM, in kbytes
--   `/qubes-block-devices` - list of block devices exposed by this VM, each device (subdirectory) should be named in a way that VM can attach the device based on it. Each should contain those entries:
+-   `/qubes-block-devices` - list of block devices exposed by this VM, each device (subdirectory) should be named in a way that VM can attach the device based on it. Each should contain these entries:
     -   `desc` - device description (ASCII text)
     -   `size` - device size in bytes
     -   `mode` - default connection mode; `r` for read-only, `w` for read-write
@@ -131,7 +134,7 @@ Qubes RPC
 
 Services called by dom0 to provide some VM configuration:
 
--   `qubes.SetMonitorLayout` - provide list of monitors, one in a line, each line contains four numbers: `width height X Y width_mm height_mm` (physical dimensions - `width_mm` and `height_mm` - are optional)
+-   `qubes.SetMonitorLayout` - provide list of monitors, one per line. Each line contains four numbers: `width height X Y width_mm height_mm` (physical dimensions - `width_mm` and `height_mm` - are optional)
 -   `qubes.WaitForSession` - called to wait for full VM startup
 -   `qubes.GetAppmenus` - receive appmenus from given VM (template); TODO: describe format here
 -   `qubes.GetImageRGBA` - receive image/application icon. Protocol:
@@ -173,10 +176,10 @@ Other Qrexec services installed by default:
 - `qubes.Restore` - retrieve Qubes backup. The service receives backup location
   entered by the user (one line, terminated by '\n'), then should output backup
   archive in [qfile format](/doc/qfilecopy/) (core-agent-linux component contains
-  `tar2qfile` utility to do the conversion
+  `tar2qfile` utility to do the conversion)
 - `qubes.SelectDirectory`, `qubes.SelectFile` - services which should show
   file/directory selection dialog and return (to stdout) a single line
-  containing selected path, or nothing in case of cancellation
+  containing selected path, or nothing in the case of cancellation
 - `qubes.SuspendPre` - service called in every VM with PCI device attached just
   before system suspend
 - `qubes.SuspendPost` - service called in every VM with PCI device attached just
@@ -200,7 +203,7 @@ abstraction. This will change in the future. Those tools are:
 - `gpk-update-viewer` - called by Qubes Manager to display available updates in a TemplateVM
 - `systemctl start qubes-update-check.timer` (and similarly stop) - called when enabling/disabling updates checking in given VM (`qubes-update-check` [qvm-service](/doc/qubes-service/))
 
-Additionally automatic tests extensively calls various commands directly in VMs. We do not plan to change that.
+Additionally, automatic tests extensively run various commands directly in VMs. We do not plan to change that.
 
 GUI protocol
 ------------

doc.md

@@ -124,8 +124,7 @@ Configuration Guides
  * [How to set up a ProxyVM as a VPN Gateway](/doc/vpn/)
  * [Storing AppVMs on Secondary Drives](/doc/secondary-storage/)
  * [Multibooting](/doc/multiboot/)
- * [Resizing AppVM and HVM Disk Images](/doc/resize-disk-image/)
+ * [Resize Disk Image](/doc/resize-disk-image/)
- * [Extending `root.img` Size](/doc/resize-root-disk-image/)
  * [RPC Policies](/doc/rpc-policy/)
  * [Installing ZFS in Qubes](/doc/zfs/)
  * [Mutt Guide](/doc/mutt/)
@@ -139,7 +138,6 @@ Configuration Guides
  * [Enabling TRIM for SSD disks](/doc/disk-trim/)
  * [Configuring a Network Printer](/doc/network-printer/)
  * [Using External Audio Devices](/doc/external-audio/)
- * [Booting with GRUB2 and GPT](https://groups.google.com/group/qubes-devel/browse_thread/thread/e4ac093cabd37d2b/d5090c20d92c4128#d5090c20d92c4128)
  * [Rxvt Guide](/doc/rxvt/)
  * [Managing VM kernel](/doc/managing-vm-kernel/)
  * [Salt management stack](/doc/salt/)
@@ -234,6 +232,8 @@ System
  * [Security-critical elements of Qubes OS](/doc/security-critical-code/)
  * [Qubes Core Admin](https://dev.qubes-os.org/projects/core-admin/en/latest/)
  * [Qubes Core Admin Client](https://dev.qubes-os.org/projects/core-admin-client/en/latest/)
+ * [Qubes Admin API](/news/2017/06/27/qubes-admin-api/)
+ * [Qubes Core Stack](/news/2017/10/03/core3/)
  * [Qrexec: command execution in VMs](/doc/qrexec3/)
  * [Qubes GUI virtualization protocol](/doc/gui/)
  * [Networking in Qubes](/doc/networking/)

installing/live-usb.md

@@ -33,7 +33,7 @@ traditional Linux distros don't have to bother with:
    version, sorry.
 2. We discovered that the Fedora liveusb-create does *not* verify signatures on
    downloaded packages. We have temporarily fixed that by creating a local repo,
-   verifying the signatures manually (ok, with a script ;) and then building
+   verifying the signatures manually (ok, with a script ;) ) and then building
    from there. Sigh.
 3. We had to solve the problem of Qubes too easily triggering an Out Of Memory
    condition in Dom0 when running as Live OS.
@@ -69,7 +69,7 @@ Live USB variant:
    A nice variant of this persistence option, especially for frequent
    travelers, would be to augment our backup tools so that it was
    possible to create a LiveUSB-hosted backups of select VMs. One could then
-   pick a few of their VMs, necessary for a specific travel, back them to a
+   pick a few of their VMs, necessary for a specific trip, back them up to a
    LiveUSB stick, and take this stick when traveling to a hostile country (not
    risking taking other, more sensitive ones for the travel). This should make
    life a bit simpler
@@ -94,7 +94,7 @@ expectations accordingly.)
 3. Currently there is no "install to disk" option. We will be adding this
    in the future.
 4. The amount of "disk" space is limited by the amount of RAM the laptop
-   has. This has a side effect of e.g. not being able to restore (even few) VMs
+   has. This has a side effect of e.g. not being able to restore (even a few) VMs
    from a large Qubes backup blob.
 5. It's easy to generate Out Of Memory (OOM) in Dom0 by creating lots of VMs
    which are writing a lot into the VMs filesystem.

installing/upgrade/upgrade-to-r3.0.md

@@ -100,7 +100,7 @@ Now, when you have dom0 upgraded, you can install new templates from Qubes R3.0
 Upgrading template on already upgraded dom0
 -------------------------------------------
 
-When for some reason you did not upgraded all the templates and standalone VMs before upgrading dom0, you can still do this, but it will be somehow more complicated. This can be a case when you restore backup done on Qubes R2.
+If for some reason you did not upgrade all the templates and standalone VMs before upgrading dom0, you can still do this, but it will be more complicated. This can be the case when you restore backup done on Qubes R2.
 
 When you start R2 template/standalone VM on R3.0, there will be some limitations:
 

installing/version-scheme.md

@@ -17,7 +17,7 @@ From now on, it will be as follows.
 Qubes distributions and products
 --------------------------------
 
-We intend to make it easy to make a remix of qubes, targeting another
+We intend to make it easy to make a remix of Qubes, targeting another
 hypervisor or isolation provider. We may also create commercial products
 intended for specific circumstances. There is one distinguished distribution
 called **Qubes OS**. All source code for it is available for download under GPL
@@ -28,13 +28,13 @@ Release version
 ---------------
 
 Qubes OS as a whole is released from time to time. Version scheme for all
-releases is modeled after Linux kernel version numbers. When announcing new
+releases is modeled after Linux kernel version numbers. When announcing a new
 release, we decide on the major.minor version (like `3.0`) and release
 `3.0-rc1`. When we feel that enough progress has been made, we put `3.0-rc2`
 and so on. All these versions are considered unstable and not ready for
 production. You may ask for support on mailing lists (specifically
 **qubes-devel**), but it is not guaranteed (you may for example get answer
-„update to newer `-rc`”). Public ISO image may or may not be available.
+“update to newer `-rc`”). Public ISO image may or may not be available.
 
 When enough development has been made, we announce the first stable version,
 like e.g. `3.0.0` (i.e. without `-rc`). This version is considered stable and
@@ -46,7 +46,7 @@ bugfixes as `3.0.1`, `3.0.2` and so on, while new features come into the next
 release e.g. `3.1-rcX`.
 
 Tickets in the tracker are sorted out by release major.minor, such as `3.0`,
-`3.1` (trac calls this „milestone”).
+`3.1` (trac calls this “milestone”).
 
 Release schedule
 ----------------

managing-os/hvm.md

@@ -37,10 +37,11 @@ qvm-create win7 --hvm --label green
 
 The name of the domain ("win7") as well as its label ("green") are just exemplary of course.
 
-**Note:** It is unnecessary for Qubes 4 users to pass in the `--hvm` switch. To create a StandaloneVM in Qubes 4, use the --class option, as VMs are template-based by default:
+**Note:** To create a StandaloneVM in Qubes R4, use the --class option, as VMs are template-based by default
 
 ~~~
-qvm-create win7 --class StandaloneVM --label green
+qvm-create win7 --class StandaloneVM --property virt_mode=hvm --property kernel="" --property memory=4096 --property maxmem=4096 --property debug=True --label green
+qvm-features win7 video-model cirrus
 ~~~
 
 If you receive an error like this one, then you must first enable VT-x in your BIOS:
@@ -52,16 +53,18 @@ libvirt.libvirtError: invalid argument: could not find capabilities for arch=x86
 Now we need to install an OS inside this VM.  This can be done by attaching an installation ISO to and starting the VM (this can currently only be done from command line, but in the future we will surely add an option to do this also from the manager):
 
 ~~~
-qvm-start win7 --cdrom=/usr/local/iso/win7_en.iso
+qvm-start win7 --cdrom=DispVM:/home/user/win7.iso
+or
+qvm-start win7 --cdrom=dom0:/usr/local/iso/win7_en.iso
 ~~~
 
-The above command assumes the installation ISO was transferred to Dom0 (copied using `dd` command from an installation CDROM for example). If one wishes to use the actual physical media without copying it first to a file, then one can just pass `/dev/cdrom` as an argument to `--cdrom`:
+The above first command assumes the installation ISO was transferred to a DispVM (copied using `dd` command from an installation CDROM for example). The second is for when the iso is in Dom0, which is not recommended. If one wishes to use the actual physical media without copying it first to a file, then one can just pass `/dev/cdrom` as an argument to `--cdrom`:
 
 ~~~
 qvm-start win7 --cdrom=/dev/cdrom
 ~~~
 
-Next, the VM will start booting from the attached CDROM device (which in the example above just happens to be a Windows 7 installation disk). Depending on the OS being installed in the VM, one might be required to start the VM several times (as is the case with Windows 7 installations), because whenever the installer wants to "reboot the system" it actually shutdowns the VM and Qubes won't automatically start it.  Several invocations of qvm-start command (as shown above) might be needed.
+Next, the VM will start booting from the attached CDROM device (which in the example above just happens to be a Windows 7 installation disk). Depending on the OS being installed in the VM, one might be required to start the VM several times (as is the case with Windows 7 installations), because whenever the installer wants to "reboot the system" it actually shuts down the VM and Qubes won't automatically start it.  Several invocations of qvm-start command (as shown above) might be needed.
 
 **Note:** If your Windows installation gets stuck at the glowing Windows logo, you might want to read [Issue 2488](https://github.com/QubesOS/qubes-issues/issues/2488) for a solution.
 
@@ -185,7 +188,7 @@ Cloning HVM domains
 
 Just like normal AppVMs, the HVM domains can also be cloned either using a command-line `qvm-clone` command or via manager's 'Clone VM' option in the right-click menu.
 
-The cloned VM will get identical root and private image and will essentially be an identical of the original VM except that it will get a different MAC address for the networking interface:
+The cloned VM will get identical root and private images and will essentially be identical to the original VM except that it will get a different MAC address for the networking interface:
 
 ~~~
 [joanna@dom0 ~]$ qvm-prefs win7

managing-os/netbsd.md

@@ -9,7 +9,7 @@ How to Create a NetBSD VM
 
 1. Create a StandaloneVM with the default template.
 2. Replace `vmlinuz` with the `netbsd-INSTALL_XEN3_DOMU` kernel.
-3. During setup, chose to install on the `xbd1` hard disk.
+3. During setup, choose to install on the `xbd1` hard disk.
 4. Attach the CD to the VM.
 5. Configure the networking.
 6. Optionally enable SSHD during the post-install configuration.

managing-os/pentesting/blackarch.md

@@ -6,13 +6,13 @@ redirect_from:
 - /doc/blackarch/
 ---
 
-**General Remainder:**
+**General reminder:**
 
 - The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities.
 
-- Adding additional repositories or tools for installing software extends your trust to those tool provider.
+- Adding additional repositories or tools for installing software extends your trust to those tool providers.
 
-Please keep in mind that using such a VM or VM's based on the template for security and privacy critical tasks is not recommended.  
+Please keep in mind that using such a VM or VMs based on the template for security and privacy critical tasks is not recommended.  
 
 How to Create a BlackArch VM
 ============================

managing-os/pentesting/kali.md

@@ -10,7 +10,7 @@ redirect_from:
 
 - The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities.
 
-- Adding additional repositories or tools for installing software extends your trust to those tool provider.
+- Adding additional repositories or tools for installing software extends your trust to those tool providers.
 
 Please keep in mind that using such a VM or VM's based on the template for security and privacy critical tasks is not recommended.
 

managing-os/pentesting/ptf.md

@@ -6,11 +6,11 @@ redirect_from:
 - /doc/ptf/
 ---
 
-**General Remainder:**
+**General reminder:**
 
 - The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities.
 
-- Adding additional repositories or tools for installing software extends your trust to those tool provider.
+- Adding additional repositories or tools for installing software extends your trust to those tool providers.
 
 Please keep in mind that using such a VM or VM's based on the template for security and privacy critical tasks is not recommended.
 
@@ -21,7 +21,7 @@ How to create Penetration Testers Framework (PTF) VM
 
 PTF attempts to install all of your penetration testing tools (latest and greatest), compile them, build them, and make it so that you can install/update your distribution on any machine." (source [PTF Readme](https://github.com/trustedsec/ptf/blob/master/README.md))
 
-**Note** PTF works on Debian testing as well as on Debian 8. PTF itself works with Debian 8, but the software tools will have missing dependencies. Metasploit for examples requires a newer Ruby version than Debian 8 has in the repositories. Therefor the best way to install PTF is by upgrading a Debian 8 into Debian testing with additional Kali repositories. Instead of installing the tools from Kali, PTF will install and update the newest tools.
+**Note** PTF works on Debian testing as well as on Debian 8. PTF itself works with Debian 8, but the software tools will have missing dependencies. Metasploit for example requires a newer Ruby version than Debian 8 has in the repositories. Therefore the best way to install PTF is by upgrading a Debian 8 into Debian testing with additional Kali repositories. Instead of installing the tools from Kali, PTF will install and update the newest tools.
 
 Create Debian Based Penetration Testers Framework (PTF) Template
 ----------------------------------------------------------------
@@ -108,7 +108,7 @@ possible to do sudo ptf/ptf
                     [*] Exiting PTF - the easy pentest platform creation framework.
                     sudo msfconsole
 
-5. Create a AppVMs based on the `ptf` template
+5. Create an AppVM based on the `ptf` template
 
     - (Optional) Attach necessary devices
 

managing-os/reinstall-template.md

@@ -9,52 +9,100 @@ redirect_from:
 How to Reinstall a TemplateVM
 =============================
 
-If you suspect your [TemplateVM] is broken, misconfigured, or compromised, you
+If you suspect your [TemplateVM] is broken, misconfigured, or compromised, you can reinstall any TemplateVM that was installed from the Qubes repository.
-can reinstall any TemplateVM that was installed from the Qubes repository.
-Starting in Qubes 3.1, the process is greatly simplified.
 
-First, copy any files that you wish to keep from the TemplateVM's `/home` and
+The procedure varies by Qubes version and UpdateVM's distribution; see the appropriate section below.
-`/rw` folders to a safe storage location. Then, in a dom0 terminal, run:
+
+To determine your UpdateVM's distribution:
+
+1. Go to a `dom0` terminal prompt.
+2. Enter `qubes-prefs` and look for `updatevm`.
+3. Enter `qvm-prefs <UpdateVMName>` and look for `template`.
+
+This will typically be either `debian-9`, `fedora-26`, or `whonix-gw`.
+In the case of `whonix-gw`, refer to the Debian based UpdateVM method.
+ 
+
+Manual Reinstallation Method (Fedora based UpdateVM, R3.1+)
+----------------------------
+
+First, copy any files that you wish to keep from the TemplateVM's `/home` and `/rw` folders to a safe storage location.
+Then, in a dom0 terminal, run:
 
     $ sudo qubes-dom0-update --action=reinstall qubes-template-package-name
 
-Replace `qubes-template-package-name` with the name of the *package* of the
+Replace `qubes-template-package-name` with the name of the *package* of the template you wish to reinstall.
-template you wish to reinstall. For example, use `qubes-template-fedora-25` if
+For example, use `qubes-template-fedora-25` if you wish to reinstall the `fedora-25` template.
-you wish to reinstall the `fedora-25` template. Only one template can be
+Only one template can be reinstalled at a time.
-reinstalled at a time.
 
-Note that Qubes may initially refuse to perform the reinstall if the exact revision of
+Note that Qubes may initially refuse to perform the reinstall if the exact revision of the template package on your system is no longer in the Qubes online repository.
-the template package on your system is no longer in the Qubes online repository. In
+In this case, you can specify `upgrade` as the action instead and the newer version will be used. 
-this case, you can specify `upgrade` as the action instead and the newer version will be
+The other `dnf` package actions that are supported in addition to `reinstall` and `upgrade` are `upgrade-to` and `downgrade`.
-used. The other `dnf` package actions that are now supported in addition to `reinstall`
-and `upgrade` are `upgrade-to` and `downgrade`.
 
-**Reminder:** If you're trying to reinstall a template that is not in an enabled
+**Reminder:** If you're trying to reinstall a template that is not in an enabled repo, you must enable that repo.
-repo, you must enable that repo. For example:
+For example:
 
     $ sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinstall qubes-template-whonix-ws
 
-**Note:** VMs that are using the reinstalled template will not be affected until they are
+**Note:** VMs that are using the reinstalled template will not be affected until they are restarted.
-restarted.
 
 
-Manual Reinstallation Method
+Manual Reinstallation Method (Debian based UpdateVM, R3.1+)
 ----------------------------
 
-If you're using Qubes 3.0 or older, you should use the manual reinstallation
+In what follows, the term "target TemplateVM" refers to whichever TemplateVM you want to reinstall.
-method. You can also use this method on later Qubes versions if, for any reason,
+If you want to reinstall more than one TemplateVM, repeat these instructions for each one.
-you want to reinstall a template manually.
 
-In what follows, the term "target TemplateVM" refers to whichever TemplateVM you
+1. Clone the existing target TemplateVM.
-want to reinstall. If you want to reinstall more than one TemplateVM, repeat
+
-these instructions for each one.
+   This can be a good idea if you've customized the existing template and want to keep your customizations.
+   On the other hand, if you suspect that this template is broken, misconfigured, or compromised, be certain you do not start any VMs using it in the below procedure.
+
+2. Temporarily change all VMs based on the target TemplateVM to the new clone template, or remove them.
+
+   This can be a good idea if you have user data in these VMs that you want to keep.
+   On the other hand, if you suspect that these VMs (or the templates on which they are based) are broken, misconfigured, or compromised, you may want to remove them instead. 
+   You can do this in Qubes Manager by right-clicking on the VM and clicking **Remove VM**, or you can use the command `qvm-remove <vm-name>` in dom0.
+
+3. Uninstall the target TemplateVM from dom0:
+
+        $ sudo dnf remove <template-package-name>
+
+   For example, to uninstall the `whonix-gw` template:
+
+        $ sudo dnf remove qubes-template-whonix-gw
+
+4. Reinstall the target TemplateVM in dom0:
+
+        $ sudo qubes-dom0-update --enablerepo=<optional-additional-repo> \
+          <template-package-name>
+
+   For example, to install the `whonix-gw` template:
+
+        $ sudo qubes-dom0-update --enablerepo=qubes-templates-community \
+          qubes-template-whonix-gw
+
+5. If you temporarily changed all VMs based on the target TemplateVM to the clone template in step 3, change them back to the new target TemplateVM now.
+   If you instead removed all VMs based on the old target TemplateVM, you can recreate your desired VMs from the newly reinstalled target TemplateVM now.
+   
+6. Delete the cloned template.
+   You can do this in Qubes Manager by right-clicking on the VM and clicking **Remove VM**, or you can use the
+   command `qvm-remove <vm-name>` in dom0.
+   
+   
+Manual Reinstallation Method (R3.0 or earlier)
+----------------------------
+
+If you're using Qubes 3.0 or older, you should use the manual reinstallation method. 
+You can also use this method on later Qubes versions if, for any reason, you want to reinstall a template manually.
+
+In what follows, the term "target TemplateVM" refers to whichever TemplateVM you want to reinstall. 
+If you want to reinstall more than one TemplateVM, repeat these instructions for each one.
 
 1. (Optional) Clone the existing target TemplateVM.
 
-   This can be a good idea if you've customized the existing template and want
+   This can be a good idea if you've customized the existing template and want to keep your customizations. 
-   to keep your customizations. On the other hand, if you suspect that this
+   On the other hand, if you suspect that this template is broken, misconfigured, or compromised, you may want to remove it without cloning it.
-   template is broken, misconfigured, or compromised, you may want to remove it
-   without cloning it.
 
 2. Create a temporary dummy template:
 
@@ -62,19 +110,14 @@ these instructions for each one.
         touch /var/lib/qubes/vm-templates/dummy/{root.img,private.img}
         qvm-add-template dummy
 
-3. Temporarily change all VMs based on the target TemplateVM to the new dummy
+3. Temporarily change all VMs based on the target TemplateVM to the new dummy template, or remove them.
-   template, or remove them.
 
-   This can be a good idea if you have user data in these VMs that you want to
+   This can be a good idea if you have user data in these VMs that you want to keep. 
-   keep. On the other hand, if you suspect that these VMs (or the templates on
+   On the other hand, if you suspect that these VMs (or the templates on which they are based) are broken, misconfigured, or compromised, you may want to remove them instead.
-   which they are based) are broken, misconfigured, or compromised, you may
+   You can do this in Qubes Manager by right-clicking on the VM and clicking **Remove VM**, or you can use the command `qvm-remove <vm-name>` in dom0.
-   want to remove them instead. You can do this in Qubes Manager by
-   right-clicking on the VM and clicking **Remove VM**, or you can use the
-   command `qvm-remove <vm-name>` in dom0.
 
-   Using a dummy template as a temporary template is preferable to using another
+   Using a dummy template as a temporary template is preferable to using another real TemplateVM because you can't accidentally boot any VMs from the dummy template.
-   real TemplateVM because you can't accidentally boot any VMs from the dummy
+   (There is no OS in the dummy template, so the boot will fail.)
-   template. (There is no OS in the dummy template, so the boot will fail.)
 
 4. Uninstall the target TemplateVM from dom0:
 
@@ -94,10 +137,8 @@ these instructions for each one.
         $ sudo qubes-dom0-update --enablerepo=qubes-templates-community \
           qubes-template-whonix-gw
 
-6. If you temporarily changed all VMs based on the target TemplateVM to the
+6. If you temporarily changed all VMs based on the target TemplateVM to the dummy template in step 3, change them back to the new target TemplateVM now.
-   dummy template in step 3, change them back to the new target TemplateVM now.
+   If you instead removed all VMs based on the old target TemplateVM, you can recreate your desired VMs from the newly reinstalled target TemplateVM now.
-   If you instead removed all VMs based on the old target TemplateVM, you can
-   recreate your desired VMs from the newly reinstalled target TemplateVM now.
 
 [TemplateVM]: /doc/templates/
 

managing-os/templates/archlinux.md

@@ -54,12 +54,12 @@ In order to keep the template as small and simple as possible, default installed
 * Some font packages to keep good user experience
 * leafpad: a note pad
 * xfce4-terminal: a terminal
-* thunar: a file browser that support mounting usb keys
+* thunar: a file browser that supports mounting usb keys
 * firefox: web browser
 * thunderbird: a mail browser
 * evince: a document viewer
 
-Note that Archlinux does not install GUI packages by default as this decision is left to users. This packages have only been selected to have a usable template.
+Note that Archlinux does not install GUI packages by default as this decision is left to users. These packages have only been selected to have a usable template.
 
 ## Activating binary packages manually
 
@@ -85,9 +85,9 @@ For this reason, it is recommended to start from a new template in Qubes-4.0.
 
 ## Updating a Qubes-3.1 Archlinux Template
 
-If you decide to use binary packages but that you where using a Qubes-3.1 Template, your can follow these instructions to enable Qubes 3.2 agents.
+If you decide to use binary packages but that you were using a Qubes-3.1 Template, you can follow these instructions to enable Qubes 3.2 agents.
 
-You can use a template that you built for Qubes 3.1 in Qubes 3.2. The qrexec and gui agent functionnalities should still be working so that you can at least open a terminal.
+You can use a template that you built for Qubes 3.1 in Qubes 3.2. The qrexec and gui agent functionalities should still be working so that you can at least open a terminal.
 
 In order to enable binary packages for Qubes 3.2, add the following lines to the end of /etc/pacman.conf
 
@@ -99,22 +99,22 @@ Server = http://olivier.medoc.free.fr/archlinux/current/
 You should then follow the instruction related to pacman-key in order to sign the binary packages PGP key. With the key enabled, a pacman update will update qubes agents:
 ` # pacman -Suy `
 
-The two line that have just been added to /etc/pacman.conf should then be removed as they have been included in the qubes-vm-core update in the file `/etc/pacmand.d/99-qubes-repository-3.2.conf`
+The two lines that have just been added to /etc/pacman.conf should then be removed as they have been included in the qubes-vm-core update in the file `/etc/pacmand.d/99-qubes-repository-3.2.conf`
 
 ## Known Issues
 
 ### Package cannot be updated because of errors related to xorg-server or pulseaudio versions
 
-In case archlinux upgrade pulseaudio major version or xorg-server version, updating these packages will break the qubes GUI agent. To avoid breaking things, the update is blocked until a new version of the GUI agent is available.
+The Qubes GUI agent must be rebuilt whenever xorg-server or pulseaudio make major changes.
+If an update of one of these packages causes your template to break, simply [revert it](https://www.qubes-os.org/doc/software-update-vm/#reverting-changes-to-a-templatevm) and wait for corresponding Qubes package updates to be available (or attempt to build them yourself, if you're so inclined).
+This should not happen frequently.
 
-In this case, the gui-agent-linux component of Qubes-OS needs to be rebuild using these last xorg-server or pulseaudio libraries. You can try to rebuilt it yourself or wait for a new qubes-vm-gui package to be available.
+### qubes-vm is apparently starting properly (green dot) however graphical applications do not appear to work
 
-### qubes-vm is apparently starting properly (green dot) however graphical applications do not appears to work
+They are multiple potential reasons. Some of them are described in the following issue:
-
-They are multiple potential reasons. Some of them are described in the following issues:
 * https://github.com/QubesOS/qubes-issues/issues/2612
 
-In issue 2612, check that the option `noauto` is present for all lines in /etc/fstab related to /rw or /home. This bug can appears if you come from an old Archlinux Template (pre February 2017).
+In issue 2612, check that the option `noauto` is present for all lines in /etc/fstab related to /rw or /home. This bug can appear if you come from an old Archlinux Template (pre February 2017).
 
 ## Debugging a broken VM
 
@@ -124,7 +124,7 @@ In order to identify the issue, you should start by getting a console access to
 
 * Or by running in dom0 `sudo xl console yourbrokenvm`
 
-Starts by trying to run a GUI application such as xfce4-terminal in order to identify any error message.
+Start by trying to run a GUI application such as xfce4-terminal in order to identify any error message.
 
 Then you can check potential broken systemd service by running the following command inside the broken vm: `systemctl | grep fail`.
 
@@ -134,7 +134,7 @@ Finally, errors related to the GUI agent can be found inside the VM in `/home/us
 
 ## Packages manager wrapper
 
-Powerpill is a full Pacman wrapper that not only give easy proxy configuration but further offers numerous other advantages.
+Powerpill is a full Pacman wrapper that not only gives easy proxy configuration but further offers numerous other advantages.
 
 Please check out:
 
@@ -143,7 +143,7 @@ Please check out:
 [XYNE's (dev) Powerpill](http://xyne.archlinux.ca/projects/powerpill/)
 
 
-**Important Note:** As you are working in a template vm, by default, you will have to open network access to the template to download files manually, except for package managed which should be handled by the Qubes proxy. You can use the "allow full access for" a given time period in the FW settings of the template in the VMM or open up the various services through the same window.  Remember to change it back if you choose the later route.  Actions needing network access will be noted with (needs network access)
+**Important Note:** As you are working in a template vm, by default, you will have to open network access to the template to download files manually, except for managed packages which should be handled by the Qubes proxy. You can use the "allow full access for" a given time period in the FW settings of the template in the VMM or open up the various services through the same window.  Remember to change it back if you choose the later route.  Actions needing network access will be noted with (needs network access)
 
 <br>
 <br>
@@ -156,7 +156,7 @@ Please check out:
 
 *   **$ sudo nano -w /etc/pacman.conf**
         
-* Below is the output of a correct pacman.conf file  Make the changes so your file matches this one or rename the original and create a new one and copy and paste this text into it.  Text should be justified left in the file.  The changes from your default are to make gpg sig signing mandatory for packages but not required for DBs for the archlinux repos.  Also to add the repo (at the end) for the Powerpill package.
+* Below is the output of a correct pacman.conf file  Make the changes so your file matches this one or rename the original and create a new one and copy and paste this text into it.  Text should be justified left in the file.  The changes from your default are to make gpg signing mandatory for packages but not required for DBs for the archlinux repos.  Also to add the repo (at the end) for the Powerpill package.
 
 
 <br>

managing-os/templates/fedora-minimal.md

@@ -29,7 +29,7 @@ The download may take a while depending on your connection speed.
 Duplication and first steps
 ---------------------------
 
-It is higly recommended to clone the original template, and make any changes in the clone instead of the original template. The following command clones the template. Replace `your-new-clone` with your desired name.
+It is highly recommended to clone the original template, and make any changes in the clone instead of the original template. The following command clones the template. Replace `your-new-clone` with your desired name.
 
 ~~~
 [user@dom0 ~]$ qvm-clone fedora-26-minimal your-new-clone

managing-os/templates/fedora/upgrade-20-to-21.md

@@ -202,7 +202,7 @@ In this case, you have several options:
  1. [Increase the TemplateVM's disk image size](/doc/resize-disk-image/).
     This is the solution mentioned in the main instructions above.
  2. Delete files in order to free up space. One way to do this is by
-    uninstalling packages. You may then reinstalling them again after you
+    uninstalling packages. You may then reinstall them again after you
     finish the upgrade process, if desired). However, you may end up having to
     increase the disk image size anyway (see previous option).
  3. Increase the `root.img` size with `qvm-grow-root`. It should be easy to

managing-os/templates/fedora/upgrade-21-to-23.md

@@ -185,7 +185,7 @@ In this case, you have several options:
  1. [Increase the TemplateVM's disk image size](/doc/resize-disk-image/).
     This is the solution mentioned in the main instructions above.
  2. Delete files in order to free up space. One way to do this is by
-    uninstalling packages. You may then reinstalling them again after you
+    uninstalling packages. You may then reinstall them again after you
     finish the upgrade process, if desired). However, you may end up having to
     increase the disk image size anyway (see previous option).
  3. Increase the `root.img` size with `qvm-grow-root`. It should be easy to

managing-os/templates/fedora/upgrade-23-to-24.md

@@ -215,7 +215,7 @@ In this case, you have several options:
  1. [Increase the TemplateVM's disk image size][resize-disk-image].
     This is the solution mentioned in the main instructions above.
  2. Delete files in order to free up space. One way to do this is by
-    uninstalling packages. You may then reinstalling them again after you
+    uninstalling packages. You may then reinstall them again after you
     finish the upgrade process, if desired). However, you may end up having to
     increase the disk image size anyway (see previous option).
  3. Increase the `root.img` size with `qvm-grow-root`.

managing-os/windows/windows-appvms.md

@@ -102,7 +102,7 @@ Also, the inter-VM services work as usual -- e.g. to request opening a document
 [user@work ~]$ qvm-open-in-vm work-win7 https://invisiblethingslab.com
 ~~~
 
-... just like in case of Linux AppVMs. Of course all those operations are governed by central policy engine running in Dom0 -- if the policy doesn't contain explicit rules for the source and/or target AppVM, the user will be asked for decision whether to allow or deny the operation.
+... just like in the case of Linux AppVMs. Of course all those operations are governed by central policy engine running in Dom0 -- if the policy doesn't contain explicit rules for the source and/or target AppVM, the user will be asked whether to allow or deny the operation.
 
 Inter-VM file copy and clipboard works for Windows AppVMs the same way as for Linux AppVM (except that we don't provide a command line wrapper, `qvm-copy-to-vm` in Windows VMs) -- to copy files from Windows AppVMs just right-click on the file in Explorer, and choose: Send To-\> Other AppVM.
 
@@ -124,14 +124,14 @@ Qubes allows HVM VMs to share a common root filesystem from a select Template VM
 qvm-create --hvm-template win7-x64-template -l green
 ~~~
 
-... and install Windows OS (or other OS) into this template the same way as you would install it into a normal HVM -- please see [this page](/doc/hvm-create/) instructions. However, it would make lots of sense to store the `C:\Users` directory on the 2nd disk which is automatically exposed by Qubes to all HVMs. This 2nd disk is backed by the `private.img` file in the AppVMs' and is not reset upon AppVMs reboot, so the user's directories and profiles would survive the AppVMs reboot, unlike the "root" filesystem which will be reverted to the "golden image" from the Template VM automatically. To facilitate such separation of user profiles, Qubes Windows Tools provide an option to automatically move `C:\Users` directory to the 2nd disk backed by `private.img`. It's a selectable feature of the installer, enabled by default. If that feature is selected during installation, completion of the process requires two reboots:
+... and install Windows OS (or other OS) into this template the same way as you would install it into a normal HVM -- please see instructions on [this page](/doc/hvm-create/). However, it would make lots of sense to store the `C:\Users` directory on the 2nd disk which is automatically exposed by Qubes to all HVMs. This 2nd disk is backed by the `private.img` file in the AppVMs' and is not reset upon AppVMs reboot, so the user's directories and profiles would survive the AppVMs reboot, unlike the "root" filesystem which will be reverted to the "golden image" from the Template VM automatically. To facilitate such separation of user profiles, Qubes Windows Tools provide an option to automatically move `C:\Users` directory to the 2nd disk backed by `private.img`. It's a selectable feature of the installer, enabled by default. If that feature is selected during installation, completion of the process requires two reboots:
 
 -   The private disk is initialized and formatted on the first reboot after tools installation. It can't be done **during** the installation because Xen mass storage drivers are not yet active.
 -   User profiles are moved to the private disk on the next reboot after the private disk is initialized. Reboot is required because the "mover utility" runs very early in the boot process so OS can't yet lock any files in there. This can take some time depending on the profiles' size and because the GUI agent is not yet active dom0/Qubes Manager may complain that the AppVM failed to boot. That's a false alarm (you can increase AppVM's default boot timeout using `qvm-prefs`), the VM should appear "green" in Qubes Manager shortly after.
 
-It also makes sense to disable Automatic Updates for all the template-based AppVMs -- of course this should be done in the Template VM, not in individual AppVMs, because the system-wide setting are stored in the root filesystem (which holds the system-wide registry hives). Then, periodically check for updates in the Template VM and the changes will be carried over to any child AppVMs.
+It also makes sense to disable Automatic Updates for all the template-based AppVMs -- of course this should be done in the Template VM, not in individual AppVMs, because the system-wide settings are stored in the root filesystem (which holds the system-wide registry hives). Then, periodically check for updates in the Template VM and the changes will be carried over to any child AppVMs.
 
-Once the template has been created and installed it is easy to create AppVMs based on:
+Once the template has been created and installed it is easy to create AppVMs based on it:
 
 ~~~
 qvm-create --hvm <new windows appvm name> --template <name of template vm> --label <label color>

privacy/anonymizing-your-mac-address.md

@@ -150,7 +150,7 @@ macspoof-enp0s0  meminfo-writer   updates-proxy-setup
 ~~~
 
 Now, also within the TemplateVM, type the following commands for each hardware device that you want to randomize a MAC 
-addresses for
+address for
 
 ~~~
 sudo systemctl enable macspoof@wlp0s1

privacy/whonix-install.md

@@ -19,7 +19,7 @@ Using privacy and anonymization tools like Whonix is not a magical solution that
 * Do you think nobody can eavesdrop on your communications because you are using Tor?
 * Do you know how Whonix works?
 
-If you answered no, have a look at the [about](https://www.whonix.org/wiki/About), [warning](https://www.whonix.org/wiki/Warning) and [do not](https://www.whonix.org/wiki/DoNot) pages (on the Whonix website) to make sure Whonix is the right tool for you and you understand  it's limitations.
+If you answered no, have a look at the [about](https://www.whonix.org/wiki/About), [warning](https://www.whonix.org/wiki/Warning) and [do not](https://www.whonix.org/wiki/DoNot) pages (on the Whonix website) to make sure Whonix is the right tool for you and you understand its limitations.
 
 ---
 
@@ -37,7 +37,7 @@ After doing this, you should see two new TemplateVMs in the VM Manager called `w
 
 ### Enabling AppArmor
 
-This is an optional security enhancement (for testers-only). If you’re technical & interested, see [Enabling AppArmor](/doc/privacy/customizing-whonix/).
+This is an optional security enhancement (for testers-only). If you’re technical and interested, see [Enabling AppArmor](/doc/privacy/customizing-whonix/).
 
 ### Running Applications
 

reference/tools/3.2/dom0.md

@@ -13,17 +13,20 @@ Dom0 Command-Line Tools for Qubes 3.2
 =====================================
 
  * [qubes-dom0-update](/doc/tools/3.2/dom0/qubes-dom0-update/)
+ * [qubes-guid](/doc/tools/3.2/dom0/qubes_guid/)
  * [qubes-prefs](/doc/tools/3.2/dom0/qubes-prefs/)
  * [qvm-add-appvm](/doc/tools/3.2/dom0/qvm-add-appvm/)
  * [qvm-add-template](/doc/tools/3.2/dom0/qvm-add-template/)
  * [qvm-backup-restore](/doc/tools/3.2/dom0/qvm-backup-restore/)
  * [qvm-backup](/doc/tools/3.2/dom0/qvm-backup/)
  * [qvm-block](/doc/tools/3.2/dom0/qvm-block/)
+ * [qvm-check](/doc/tools/3.2/dom0/qvm-check/)
  * [qvm-clone](/doc/tools/3.2/dom0/qvm-clone/)
  * [qvm-create-default-dvm](/doc/tools/3.2/dom0/qvm-create-default-dvm/)
  * [qvm-create](/doc/tools/3.2/dom0/qvm-create/)
  * [qvm-firewall](/doc/tools/3.2/dom0/qvm-firewall/)
  * [qvm-grow-private](/doc/tools/3.2/dom0/qvm-grow-private/)
+ * [qvm-grow-root](/doc/tools/3.2/dom0/qvm-grow-root/)
  * [qvm-ls](/doc/tools/3.2/dom0/qvm-ls/)
  * [qvm-kill](/doc/tools/3.2/dom0/qvm-kill/)
  * [qvm-pci](/doc/tools/3.2/dom0/qvm-pci/)
@@ -36,4 +39,5 @@ Dom0 Command-Line Tools for Qubes 3.2
  * [qvm-start](/doc/tools/3.2/dom0/qvm-start/)
  * [qvm-sync-appmenus](/doc/tools/3.2/dom0/qvm-sync-appmenus/)
  * [qvm-template-commit](/doc/tools/3.2/dom0/qvm-template-commit/)
+ * [qvm-usb](/doc/tools/3.2/dom0/qvm-usb/)
 

reference/tools/3.2/dom0/qubes-prefs.md

@@ -9,32 +9,43 @@ redirect_from:
 - /wiki/Dom0Tools/QubesPrefs/
 ---
 
+```
+===========
 qubes-prefs
 ===========
 
 NAME
-----
+====
-
 qubes-prefs - display system-wide Qubes settings, such as:
 
--   clock VM
+- clock VM
--   update VM
+- update VM
--   default template
+- default template
--   default firewallVM
+- default firewallVM
--   default kernel
+- default kernel
--   default netVM
+- default netVM
-
-Date  
-2012-04-13
 
 SYNOPSIS
---------
+========
-
+| qubes-prefs
-qubes-prefs
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qubes-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qubes-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/dom0/qubes_guid.md

@@ -0,0 +1,55 @@
+---
+layout: doc
+title: qubes_guid
+permalink: /doc/tools/3.2/dom0/qubes_guid/
+redirect_from:
+- /doc/dom0-tools/qubes_guid/
+- /en/doc/dom0-tools/qubes_guid/
+---
+
+```
+==========
+qubes_guid
+==========
+
+NAME
+====
+qubes_guid
+
+SYNOPSIS
+========
+| qubes_guid -d domain_id [-c color] [-l label_index] [-i icon name, no suffix] [-v] [-q]
+
+OPTIONS
+=======
+-v
+    Increase log verbosity
+-q
+    Decrease log verbosity
+
+Log levels:
+    0. only errors
+    1. some basic messages (default)
+    2. debug
+
+
+AUTHORS
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qubes-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qubes-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
+

reference/tools/3.2/dom0/qvm-add-appvm.md

@@ -9,39 +9,49 @@ redirect_from:
 - /wiki/Dom0Tools/QvmAddAppvm/
 ---
 
+```
+=============
 qvm-add-appvm
 =============
 
 NAME
-----
+====
-
 qvm-add-appvm - add an already installed appvm to the Qubes DB
 
 WARNING: Normally you should not need this command, and you should use qvm-create instead!
 
-Date  
-2012-04-10
-
 SYNOPSIS
---------
+========
-
+| qvm-add-appvm [options] <appvm-name> <vm-template-name>
-qvm-add-appvm [options] \<appvm-name\> \<vm-template-name\>
 
 OPTIONS
--------
+=======
-
+-h, --help
--h, --help  
+    Show this help message and exit
-Show this help message and exit
+-p DIR_PATH, --path=DIR_PATH
-
+    Specify path to the template directory
--p DIR\_PATH, --path=DIR\_PATH  
+-c CONF_FILE, --conf=CONF_FILE
-Specify path to the template directory
+    Specify the Xen VM .conf file to use(relative to the template dir path)
-
+--force-root
--c CONF\_FILE, --conf=CONF\_FILE  
+    Force to run, even with root privileges
-Specify the Xen VM .conf file to use(relative to the template dir path)
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/dom0/qvm-add-template.md

@@ -9,40 +9,47 @@ redirect_from:
 - /wiki/Dom0Tools/QvmAddTemplate/
 ---
 
+```
+================
 qvm-add-template
 ================
 
 NAME
-----
+====
-
 qvm-add-template - adds an already installed template to the Qubes DB
 
-Date  
-2012-04-10
-
 SYNOPSIS
---------
+========
-
+| qvm-add-template [options] <vm-template-name>
-qvm-add-template [options] \<vm-template-name\>
 
 OPTIONS
--------
+=======
-
+-h, --help
--h, --help  
+    Show this help message and exit
-Show this help message and exit
+-p DIR_PATH, --path=DIR_PATH
-
+    Specify path to the template directory
--p DIR\_PATH, --path=DIR\_PATH  
+-c CONF_FILE, --conf=CONF_FILE
-Specify path to the template directory
+    Specify the Xen VM .conf file to use(relative to the template dir path)
-
+--rpm
--c CONF\_FILE, --conf=CONF\_FILE  
+    Template files have been installed by RPM
-Specify the Xen VM .conf file to use(relative to the template dir path)
-
---rpm  
-Template files have been installed by RPM
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/dom0/qvm-backup-restore.md

@@ -9,70 +9,80 @@ redirect_from:
 - /wiki/Dom0Tools/QvmBackupRestore/
 ---
 
+```
+==================
 qvm-backup-restore
 ==================
 
 NAME
-----
+====
-
 qvm-backup-restore - restores Qubes VMs from backup
 
-Date  
-2012-04-10
-
 SYNOPSIS
---------
+========
-
+| qvm-backup-restore [options] <backup-dir>
-qvm-backup-restore [options] \<backup-dir\>
 
 OPTIONS
--------
+=======
-
+-h, --help
--h, --help  
+    Show this help message and exit
-Show this help message and exit
+--verify-only
-
+    Do not restore the data, only verify backup integrity
---verify-only  
+--skip-broken
-Do not restore the data, only verify backup integrity
+    Do not restore VMs that have missing templates or netvms
-
+--ignore-missing
---skip-broken  
+    Ignore missing templates and netvms, and restore the VMs anyway
-Do not restore VMs that have missing templates or netvms
+--skip-conflicting
-
+    Do not restore VMs that are already present on the host
---ignore-missing  
+--force-root
-Ignore missing templates and netvms, and restore the VMs anyway
+    Force to run with root privileges
-
+--replace-template=REPLACE_TEMPLATE
---skip-conflicting  
+    Restore VMs using another template, syntax: old-template-name:new-template-name (can be repeated)
-Do not restore VMs that are already present on the host
+-x EXCLUDE, --exclude=EXCLUDE
-
+    Skip restore of specified VM (can be repeated)
---force-root  
+--skip-dom0-home
-Force to run with root privileges
+    Do not restore dom0's user home directory
-
+--ignore-username-mismatch
---replace-template=REPLACE\_TEMPLATE  
+    Ignore dom0 username mismatch when restoring dom0's user home directory
-Restore VMs using another template, syntax: old-template-name:new-template-name (can be repeated)
+-d APPVM, --dest-vm=APPVM
-
+    Restore from a backup located in a specific AppVM
--x EXCLUDE, --exclude=EXCLUDE  
+-e, --encrypted
-Skip restore of specified VM (can be repeated)
+    The backup is encrypted
-
+-p, --passphrase-file
---skip-dom0-home  
+    Read passphrase from file, or use '-' to read from stdin
-Do not restore dom0's user home directory
+-z, --compressed
-
+    The backup is compressed
---ignore-username-mismatch  
+--paranoid-mode, --plan-b
-Ignore dom0 username mismatch when restoring dom0's user home directory
+    Treat the backup as untrusted, disable restoring things potentially
-
+    compromising security of dom0/other VMs, even when such data is properly
--d APPVM, --dest-vm=APPVM  
+    authenticated. This may be used to restore a backup made on compromissed
-Restore from a backup located in a specific AppVM
+    system. Things currently affected by this option:
-
+      - disable dom0 home restore
--e, --encrypted  
+      - reject compressed backups
-The backup is encrypted
+      - reject old backup formats (Qubes R2 and older)
-
+      - more strict validation of VM names (for example don't allow '..' in it)
--z, --compressed  
+      - do not restore firewall rules, attached PCI devices, attached block
-The backup is compressed
+        devices, menu entries
-
+--debug
---debug  
+    Enable (a lot of) debug output
-Enable (a lot of) debug output
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/dom0/qvm-backup.md

@@ -9,34 +9,65 @@ redirect_from:
 - /wiki/Dom0Tools/QvmBackup/
 ---
 
+```
+==========
 qvm-backup
 ==========
 
 NAME
-----
+====
-
 qvm-backup
 
-Date  
-2012-04-10
-
 SYNOPSIS
---------
+========
-
+| qvm-backup [options] <backup-dir-path> [vms-to-be-included ...]
-qvm-backup [options] \<backup-dir-path\>
 
 OPTIONS
--------
+=======
-
+-h, --help
--h, --help  
+    Show this help message and exit
-Show this help message and exit
+-x EXCLUDE_LIST, --exclude=EXCLUDE_LIST
-
+    Exclude the specified VM from backup (might be repeated)
--x EXCLUDE\_LIST, --exclude=EXCLUDE\_LIST  
+--force-root
-Exclude the specified VM from backup (might be repeated)
+    Force to run with root privileges
+-d, --dest-vm
+    Specify the destination VM to which the backup will be set (implies -e)
+-e, --encrypt
+    Encrypt the backup
+--no-encrypt
+    Skip encryption even if sending the backup to a VM
+-p, --passphrase-file
+    Read passphrase from a file, or use '-' to read from stdin
+-E, --enc-algo
+    Specify a non-default encryption algorithm. For a list of supported algorithms, execute 'openssl list-cipher-algorithms' (implies -e)
+-H, --hmac-algo
+    Specify a non-default HMAC algorithm. For a list of supported algorithms, execute 'openssl list-message-digest-algorithms'
+-z, --compress
+    Compress the backup
+-Z, --compress-filter
+	Specify a non-default compression filter program (default: gzip)
+--tmpdir
+    Specify a temporary directory (if you have at least 1GB free RAM in dom0, use of /tmp is advised) (default: /var/tmp)
+--debug
+    Enable (a lot of) debug output
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/dom0/qvm-block.md

@@ -10,52 +10,63 @@ redirect_from:
 - /wiki/Dom0Tools/QvmBlock/
 ---
 
+```
+=========
 qvm-block
 =========
 
 NAME
-----
+====
-
 qvm-block - list/set VM PCI devices.
 
-Date  
-2012-04-10
-
 SYNOPSIS
---------
+========
-
+| qvm-block -l [options]
-qvm-block -l [options]
+| qvm-block -a [options] <vm-name> <device-vm-name>:<device>
-qvm-block -a [options] \<device\> \<vm-name\>
+| qvm-block -A [options] <vm-name> <file-vm-name>:<file>
-qvm-block -d [options] \<device\>
+| qvm-block -d [options] <device-vm-name>:<device>
-qvm-block -d [options] \<vm-name\>
+| qvm-block -d [options] <vm-name>
 
 OPTIONS
--------
+=======
-
+-h, --help
--h, --help  
+    Show this help message and exit
-Show this help message and exit
+-l, --list
-
+    List block devices            
--l, --list  
+-A, --attach-file
-List block devices
+    Attach specified file instead of physical device
-
+-a, --attach
--a, --attach  
+    Attach block device to specified VM
-Attach block device to specified VM
+-d, --detach          
-
+    Detach block device
--d, --detach  
+-f FRONTEND, --frontend=FRONTEND
-Detach block device
+    Specify device name at destination VM [default: xvdi]
-
+--ro
--f FRONTEND, --frontend=FRONTEND  
+    Force read-only mode
-Specify device name at destination VM [default: xvdi]
+--no-auto-detach
-
+    Fail when device already connected to other VM
---ro  
+--show-system-disks
-Force read-only mode
+    List also system disks
-
+--force-root
---no-auto-detach  
+    Force to run, even with root privileges
-Fail when device already connected to other VM
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/dom0/qvm-check.md

@@ -0,0 +1,55 @@
+---
+layout: doc
+title: qvm-check
+permalink: /doc/tools/3.2/dom0/qvm-check/
+redirect_from:
+- /doc/dom0-tools/qvm-check/
+- /en/doc/dom0-tools/qvm-check/
+---
+
+```
+=========
+qvm-check
+=========
+
+NAME
+====
+qvm-check - Specify no state options to check if VM exists
+
+SYNOPSIS
+========
+| qvm-check [options] <vm-name>
+
+OPTIONS
+=======
+-h, --help
+    Show this help message and exit
+-q, --quiet
+    Be quiet
+--running
+    Determine if VM is running
+--paused
+    Determine if VM is paused
+--template
+    Determine if VM is a template
+
+AUTHORS
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
+

reference/tools/3.2/dom0/qvm-clone.md

@@ -9,37 +9,50 @@ redirect_from:
 - /wiki/Dom0Tools/QvmClone/
 ---
 
+```
+=========
 qvm-clone
 =========
 
 NAME
-----
+====
-
 qvm-clone - clones an existing VM by copying all its disk files
 
-Date  
-2012-04-10
-
 SYNOPSIS
---------
+========
-
+| qvm-clone [options] <src-name> <new-name>
-qvm-clone [options] \<src-name\> \<new-name\>
 
 OPTIONS
--------
+=======
-
+-h, --help
--h, --help  
+    Show this help message and exit
-Show this help message and exit
+-q, --quiet
-
+    Be quiet           
--q, --quiet  
+-p DIR_PATH, --path=DIR_PATH
-Be quiet
+    Specify path to the template directory
-
+--force-root
--p DIR\_PATH, --path=DIR\_PATH  
+    Force to run, even with root privileges
-Specify path to the template directory
+-P, --pool
+    Specify in to which storage pool to clone
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/dom0/qvm-create-default-dvm.md

@@ -9,40 +9,54 @@ redirect_from:
 - /wiki/Dom0Tools/QvmCreateDefaultDvm/
 ---
 
+```
+======================
 qvm-create-default-dvm
 ======================
 
 NAME
-----
+====
-
 qvm-create-default-dvm - creates a default disposable VM
 
-Date  
-2012-04-10
-
 SYNOPSIS
---------
+========
-
+| qvm-create-default-dvm templatename|--default-template|--used-template [script-name|--default-script]
-qvm-create-default-dvm templatename|--default-template|--used-template [script-name|--default-script]
 
 OPTIONS
--------
+=======
+templatename
+    Base DispVM on given template. The command will create AppVM named after
+    template with "-dvm" suffix. This VM will be used to create DispVM
+    savefile. If you want to customize DispVM, use this VM - take a look at
+    https://wiki.qubes-os.org/wiki/UserDoc/DispVMCustomization
 
-templatename  
+--default-template
-Base DispVM on given template. The command will create AppVM named after template with "-dvm" suffix. This VM will be used to create DispVM savefile. If you want to customize DispVM, use this VM - take a look at <https://wiki.qubes-os.org/wiki/UserDoc/DispVMCustomization>
+    Use default template for the DispVM
 
---default-template  
+--used-template
-Use default template for the DispVM
+    Use the same template as earlier
 
---used-template  
+--default-script
-Use the same template as earlier
+    Use default script for seeding DispVM home.
 
---default-script  
-Use default script for seeding DispVM home.
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/dom0/qvm-create.md

@@ -9,73 +9,72 @@ redirect_from:
 - /wiki/Dom0Tools/QvmCreate/
 ---
 
+```
+==========
 qvm-create
 ==========
 
 NAME
-----
+====
-
 qvm-create - creates a new VM
 
-Date  
-2012-04-10
-
 SYNOPSIS
---------
+========
-
+| qvm-create [options] <vm-name>
-qvm-create [options] \<vm-name\>
 
 OPTIONS
--------
+=======
-
+-h, --help
--h, --help  
+    Show this help message and exit
-Show this help message and exit
+-t TEMPLATE, --template=TEMPLATE
-
+    Specify the TemplateVM to use
--t TEMPLATE, --template=TEMPLATE  
+-l LABEL, --label=LABEL
-Specify the TemplateVM to use
+    Specify the label to use for the new VM (e.g. red, yellow, green, ...)
-
+-p, --proxy
--l LABEL, --label=LABEL  
+    Create ProxyVM
-Specify the label to use for the new VM (e.g. red, yellow, green, ...)
+-n, --net
-
+    Create NetVM
--p, --proxy  
+-H, --hvm
-Create ProxyVM
+    Create HVM (standalone, unless --template option used)
-
+--hvm-template
--n, --net  
+    Create HVM template
-Create NetVM
+-R ROOT_MOVE, --root-move-from=ROOT_MOVE
-
+    Use provided root.img instead of default/empty one
--H, --hvm  
+    (file will be MOVED)
-Create HVM (standalone, unless --template option used)
+-r ROOT_COPY, --root-copy-from=ROOT_COPY
-
+    Use provided root.img instead of default/empty one
---hvm-template  
+    (file will be COPIED)
-Create HVM template
+-s, --standalone
-
+    Create standalone VM - independent of template
--R ROOT\_MOVE, --root-move-from=ROOT\_MOVE  
+-m MEM, --mem=MEM
-Use provided root.img instead of default/empty one (file will be MOVED)
+    Initial memory size (in MB)
-
+-c VCPUS, --vcpus=VCPUS
--r ROOT\_COPY, --root-copy-from=ROOT\_COPY  
+    VCPUs count
-Use provided root.img instead of default/empty one (file will be COPIED)
+-i, --internal
-
+    Create VM for internal use only (hidden in qubes-manager, no appmenus)
--s, --standalone  
+--force-root
-Create standalone VM - independent of template
+    Force to run, even with root privileges
-
+-q, --quiet
--m MEM, --mem=MEM  
+    Be quiet
-Initial memory size (in MB)
+           
-
--c VCPUS, --vcpus=VCPUS  
-VCPUs count
-
--i, --internal  
-Create VM for internal use only (hidden in qubes-manager, no appmenus)
-
---force-root  
-Force to run, even with root privileges
-
--q, --quiet  
-Be quiet
-
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/dom0/qvm-firewall.md

@@ -9,60 +9,67 @@ redirect_from:
 - /wiki/Dom0Tools/QvmFirewall/
 ---
 
+```
+============
 qvm-firewall
 ============
 
 NAME
-----
+====
-
+qvm-firewall - manage VM's firewall rules
-qvm-firewall
-
-Date  
-2012-04-10
 
 SYNOPSIS
---------
+========
+| qvm-firewall [-n] <vm-name> [action] [rule spec]
 
-qvm-firewall [-n] \<vm-name\> [action] [rule spec]
+Rule specification can be one of:
-
+    1. address|hostname[/netmask] tcp|udp port[-port]
-Rule specification can be one of:  
+    2. address|hostname[/netmask] tcp|udp service_name
-1.  address|hostname[/netmask] tcp|udp port[-port]
+    3. address|hostname[/netmask] any
-2.  address|hostname[/netmask] tcp|udp service\_name
-3.  address|hostname[/netmask] any
 
 OPTIONS
--------
+=======
-
+-h, --help
--h, --help  
+    Show this help message and exit
-Show this help message and exit
+-l, --list
-
+    List firewall settings (default action)
--l, --list  
+-a, --add
-List firewall settings (default action)
+    Add rule
-
+-d, --del
--a, --add  
+    Remove rule (given by number or by rule spec)
-Add rule
+-P SET_POLICY, --policy=SET_POLICY
-
+    Set firewall policy (allow/deny)
--d, --del  
+-i SET_ICMP, --icmp=SET_ICMP
-Remove rule (given by number or by rule spec)
+    Set ICMP access (allow/deny)
-
+-D SET_DNS, --dns=SET_DNS
--P SET\_POLICY, --policy=SET\_POLICY  
+    Set DNS access (allow/deny)
-Set firewall policy (allow/deny)
+-Y SET_YUM_PROXY, --yum-proxy=SET_YUM_PROXY
-
+    Set access to Qubes yum proxy (allow/deny).
--i SET\_ICMP, --icmp=SET\_ICMP  
+    *Note:* if set to "deny", access will be rejected even if policy set to "allow"
-Set ICMP access (allow/deny)
+-r, --reload
-
+    Reload firewall (implied by any change action)
--D SET\_DNS, --dns=SET\_DNS  
+-n, --numeric
-Set DNS access (allow/deny)
+    Display port numbers instead of services (makes sense only with --list)
-
+--force-root
--Y SET\_YUM\_PROXY, --yum-proxy=SET\_YUM\_PROXY  
+    Force to run, even with root privileges
-Set access to Qubes yum proxy (allow/deny). *Note:* if set to "deny", access will be rejected even if policy set to "allow"
-
--n, --numeric  
-Display port numbers instead of services (makes sense only with --list)
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/dom0/qvm-grow-private.md

@@ -9,31 +9,41 @@ redirect_from:
 - /wiki/Dom0Tools/QvmGrowPrivate/
 ---
 
+```
+================
 qvm-grow-private
 ================
 
 NAME
-----
+====
-
 qvm-grow-private - increase private storage capacity of a specified VM
 
-Date  
-2012-04-10
-
 SYNOPSIS
---------
+========
-
+| qvm-grow-private <vm-name> <size>
-qvm-grow-private \<vm-name\> \<size\>
 
 OPTIONS
--------
+=======
-
+-h, --help
--h, --help  
+    Show this help message and exit
-Show this help message and exit
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/dom0/qvm-grow-root.md

@@ -0,0 +1,49 @@
+---
+layout: doc
+title: qvm-grow-root
+permalink: /doc/tools/3.2/dom0/qvm-grow-root/
+redirect_from:
+- /doc/dom0-tools/qvm-grow-root/
+- /en/doc/dom0-tools/qvm-grow-root/
+---
+
+```
+=============
+qvm-grow-root
+=============
+
+NAME
+====
+qvm-grow-root - increase root storage capacity of a specified VM
+
+SYNOPSIS
+========
+| qvm-grow-root <vm-name> <size>
+
+OPTIONS
+=======
+-h, --help
+    Show this help message and exit
+--allow-start
+    Allow VM to be started to complete the operation
+
+AUTHORS
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
+

reference/tools/3.2/dom0/qvm-kill.md

@@ -9,31 +9,42 @@ redirect_from:
 - /wiki/Dom0Tools/QvmKill/
 ---
 
+```
+========
 qvm-kill
 ========
 
 NAME
-----
+====
-
 qvm-kill - kills the specified VM
 
-Date  
-2012-04-10
-
 SYNOPSIS
---------
+========
+| qvm-kill [options] <vm-name>
 
-qvm-kill [options] \<vm-name\>
 
 OPTIONS
--------
+=======
-
+-h, --help
--h, --help  
+    Show this help message and exit
-Show this help message and exit
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/dom0/qvm-ls.md

@@ -9,55 +9,61 @@ redirect_from:
 - /wiki/Dom0Tools/QvmLs/
 ---
 
+```
+======
 qvm-ls
 ======
 
 NAME
-----
+====
-
 qvm-ls - list VMs and various information about their state
 
-Date  
-2012-04-03
-
 SYNOPSIS
---------
+========
-
+| qvm-ls [options] <vm-name>
-qvm-ls [options] \<vm-name\>
 
 OPTIONS
--------
+=======
-
+-h, --help
--h, --help  
+    Show help message and exit
-Show help message and exit
+-n, --network
-
+    Show network addresses assigned to VMs
--n, --network  
+-c, --cpu
-Show network addresses assigned to VMs
+    Show CPU load
-
+-m, --mem
--c, --cpu  
+    Show memory usage
-Show CPU load
+-d, --disk
-
+    Show VM disk utilization statistics
--m, --mem  
+-i, --ids
-Show memory usage
+    Show Qubes and Xen id
-
+-k, --kernel
--d, --disk  
+    Show VM kernel options
-Show VM disk utilization statistics
+-b, --last-backup
-
+    Show date of last VM backup
--i, --ids  
+--raw-list
-Show Qubes and Xen id
+    List only VM names one per line
-
+--raw-data
--k, --kernel  
+    Display specify data of specified VMs. Intended for bash-parsing.
-Show VM kernel options
+--list-fields
-
+    List field names valid for --raw-data
--b, --last-backup  
-Show date of last VM backup
-
---raw-list  
-List only VM names one per line
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/dom0/qvm-pci.md

@@ -9,46 +9,55 @@ redirect_from:
 - /wiki/Dom0Tools/QvmPci/
 ---
 
+```
+=======
 qvm-pci
 =======
 
 NAME
-----
+====
-
 qvm-pci - list/set VM PCI devices
 
-Date  
-2012-04-11
-
 SYNOPSIS
---------
+========
-
+| qvm-pci -l [options] <vm-name>
-qvm-pci -l [options] \<vm-name\>
+| qvm-pci -a [options] <vm-name> <device>
-qvm-pci -a [options] \<vm-name\> \<device\>
+| qvm-pci -d [options] <vm-name> <device>
-qvm-pci -d [options] \<vm-name\> \<device\>
+ 
-
 OPTIONS
--------
+=======
-
+-h, --help
--h, --help  
+    Show this help message and exit
-Show this help message and exit
+-l, --list
-
+    List VM PCI devices    
--l, --list  
+-a, --add
-List VM PCI devices
+    Add a PCI device to specified VM
-
+-C, --add-class
--a, --add  
+    Add all devices of given class:
-Add a PCI device to specified VM
+        net - network interfaces,
-
+        usb - USB controllers
--C, --add-class  
+-d, --delete
-Add all devices of given class:  
+    Remove a PCI device from specified VM
-net - network interfaces, usb - USB controllers
+--offline-mode
-
+    Offline mode
--d, --delete  
-Remove a PCI device from specified VM
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/dom0/qvm-prefs.md

@@ -9,150 +9,234 @@ redirect_from:
 - /wiki/Dom0Tools/QvmPrefs/
 ---
 
+```
+=========
 qvm-prefs
 =========
 
 NAME
-----
+====
-
 qvm-prefs - list/set various per-VM properties
 
-Date  
-2012-04-11
-
 SYNOPSIS
---------
+========
+| qvm-prefs -l [options] <vm-name>
+| qvm-prefs -g [options] <vm-name> <property>
+| qvm-prefs -s [options] <vm-name> <property> [...]
 
-qvm-prefs -l [options] \<vm-name\>
-qvm-prefs -g [options] \<vm-name\> \<property\>
-qvm-prefs -s [options] \<vm-name\> \<property\> [...]
 
 OPTIONS
--------
+=======
-
+-h, --help
--h, --help  
+    Show this help message and exit
-Show this help message and exit
+-l, --list
-
+    List properties of a specified VM
--l, --list  
+-g, --get
-List properties of a specified VM
+    Get a single property of a specified VM
-
+-s, --set
--g, --get  
+    Set properties of a specified VM
-Get a single property of a specified VM
+--force-root
-
+    Force to run, even with root privileges
--s, --set  
+--offline-mode
-Set properties of a specified VM
+    Offline mode
 
 PROPERTIES
-----------
+==========
 
-include\_in\_backups  
+include_in_backups
-Accepted values: `True`, `False`
+    Accepted values: ``True``, ``False``
 
-Control whenever this VM will be included in backups by default (for now works only in qubes-manager). You can always manually select or deselect any VM for backup.
+    Control whenever this VM will be included in backups by default (for now
+    works only in qubes-manager). You can always manually select or
+    deselect any VM for backup.
 
-pcidevs  
+pcidevs
-PCI devices assigned to the VM. Should be edited using qvm-pci tool.
+    PCI devices assigned to the VM. Should be edited using qvm-pci tool.
 
-pci\_strictreset  
+pci_strictreset
-Accepted values: `True`, `False`
+    Accepted values: ``True``, ``False``
 
-Control whether prevent assigning to VM a device which does not support any reset method. Generally such devices should not be assigned to any VM, because there will be no way to reset device state after VM shutdown, so the device could attack next VM to which it will be assigned. But in some cases it could make sense - for example when the VM to which it is assigned is trusted one, or is running all the time.
+    Control whether prevent assigning to VM a device which does not support any
+    reset method. Generally such devices should not be assigned to any VM,
+    because there will be no way to reset device state after VM shutdown, so
+    the device could attack next VM to which it will be assigned. But in some
+    cases it could make sense - for example when the VM to which it is assigned
+    is trusted one, or is running all the time.
 
-label  
+pci_e820_host
-Accepted values: `red`, `orange`, `yellow`, `green`, `gray`, `blue`, `purple`, `black`
+    Accepted values: ``True``, ``False``
 
-Color of VM label (icon, appmenus, windows border). If VM is running, change will be applied at first VM restart.
+    Give VM with PCI devices a memory map (e820) of the host. This is
+    required for some devices to properly resolve conflicts in address space.
+    This option is enabled by default for VMs with PCI devices and have no
+    effect for VMs without devices.
 
-netvm  
+label
-Accepted values: netvm name, `default`, `none`
+    Accepted values: ``red``, ``orange``, ``yellow``, ``green``, ``gray``,
+    ``blue``, ``purple``, ``black``
 
-To which NetVM connect. Setting to `default` will follow system-global default NetVM (managed by qubes-prefs). Setting to `none` will disable networking in this VM.
+    Color of VM label (icon, appmenus, windows border). If VM is running,
+    change will be applied at first VM restart.
 
-dispvm\_netvm  
+netvm
-Accepted values: netvm name, `default`, `none`
+    Accepted values: netvm name, ``default``, ``none``
 
-Which NetVM should be used for Disposable VMs started by this one. `default` is to use the same NetVM as the VM itself.
+    To which NetVM connect. Setting to ``default`` will follow system-global
+    default NetVM (managed by qubes-prefs). Setting to ``none`` will disable
+    networking in this VM.
 
-maxmem  
+dispvm_netvm
-Accepted values: memory size in MB
+    Accepted values: netvm name, ``default``, ``none``
 
-Maximum memory size available for this VM. Dynamic memory management (aka qmemman) will not be able to balloon over this limit. For VMs with qmemman disabled, this will be overridden by *memory* property (at VM startup).
+    Which NetVM should be used for Disposable VMs started by this one.
+    ``default`` is to use the same NetVM as the VM itself.
 
-memory  
+maxmem
-Accepted values: memory size in MB
+    Accepted values: memory size in MB
 
-Initial memory size for VM. This should be large enough to allow VM startup - before qmemman starts managing memory for this VM. For VM with qmemman disabled, this is static memory size.
+    Maximum memory size available for this VM. Dynamic memory management (aka
+    qmemman) will not be able to balloon over this limit. For VMs with
+    qmemman disabled, this will be overridden by *memory* property (at VM
+    startup).
 
-kernel  
+memory
-Accepted values: kernel version, `default`, `none`
+    Accepted values: memory size in MB
 
-Kernel version to use (only for PV VMs). Available kernel versions will be listed when no value given (there are in /var/lib/qubes/vm-kernels). Setting to `default` will follow system-global default kernel (managed via qubes-prefs). Setting to `none` will use "kernels" subdir in VM directory - this allows having VM-specific kernel; also this the only case when /lib/modules is writable from within VM.
+    Initial memory size for VM. This should be large enough to allow VM startup
+    - before qmemman starts managing memory for this VM. For VM with qmemman
+    disabled, this is static memory size.
 
-template  
+kernel
-Accepted values: TemplateVM name
+    Accepted values: kernel version, ``default``, ``none``
 
-TemplateVM on which VM base. It can be changed only when VM isn't running.
+    Kernel version to use (only for PV VMs). Available kernel versions will be
+    listed when no value given (there are in /var/lib/qubes/vm-kernels).
+    Setting to ``default`` will follow system-global default kernel (managed
+    via qubes-prefs). Setting to ``none`` will use "kernels" subdir in
+    VM directory - this allows having VM-specific kernel; also this the only
+    case when /lib/modules is writable from within VM.
 
-vcpus  
+template
-Accepted values: no of CPUs
+    Accepted values: TemplateVM name
 
-Number of CPU (cores) available to VM. Some VM types (eg DispVM) will not work properly with more than one CPU.
+    TemplateVM on which VM base. It can be changed only when VM isn't running.
 
-kernelopts  
+vcpus
-Accepted values: string, `default`
+    Accepted values: no of CPUs
 
-VM kernel parameters (available only for PV VMs). This can be used to workaround some hardware specific problems (eg for NetVM). Setting to `default` will use some reasonable defaults (currently different for VMs with PCI devices and without). For VM without PCI devices `default` option means inherit this value from the VM template (if any). Some helpful options (for debugging purposes): `earlyprintk=xen`, `init=/bin/bash`
+    Number of CPU (cores) available to VM. Some VM types (eg DispVM) will not
+    work properly with more than one CPU.
 
-name  
+kernelopts
-Accepted values: alphanumerical name
+    Accepted values: string, ``default``
 
-Name of the VM. Can be only changed when VM isn't running.
+    VM kernel parameters (available only for PV VMs). This can be used to
+    workaround some hardware specific problems (eg for NetVM). Setting to
+    ``default`` will use some reasonable defaults (currently different for VMs
+    with PCI devices and without). For VM without PCI devices
+    ``default`` option means inherit this value from the VM template (if any).
+    Some helpful options (for debugging purposes): ``earlyprintk=xen``,
+    ``init=/bin/bash``
 
-drive  
+name
-Accepted values: [hd:|cdrom:][backend-vm:]path
+    Accepted values: alphanumerical name
 
-Additional drive for the VM (available only for HVMs). This can be used to attach installation image. `path` can be file or physical device (eg. /dev/sr0). The same syntax can be used in qvm-start --drive - to attach drive only temporarily.
+    Name of the VM. Can be only changed when VM isn't running.
 
-mac  
+drive
-Accepted values: MAC address, `auto`
+    Accepted values: [hd:\|cdrom:][backend-vm:]path
 
-Can be used to force specific of virtual ethernet card in the VM. Setting to `auto` will use automatic-generated MAC - based on VM id. Especially useful when licensing requires a static MAC address. For template-based HVM `auto` mode means to clone template MAC.
+    Additional drive for the VM (available only for HVMs). This can be used to
+    attach installation image. ``path`` can be file or physical device (eg.
+    /dev/sr0). The same syntax can be used in qvm-start --drive - to
+    attach drive only temporarily.
 
-default\_user  
+mac
-Accepted values: username
+    Accepted values: MAC address, ``auto``
 
-Default user used by qvm-run. Note that it make sense only on non-standard template, as the standard one always have "user" account.
+    Can be used to force specific of virtual ethernet card in the VM. Setting
+    to ``auto`` will use automatic-generated MAC - based on VM id. Especially
+    useful when licensing requires a static MAC address.
+    For template-based HVM ``auto`` mode means to clone template MAC.
 
-debug  
+default_user
-Accepted values: `on`, `off`
+    Accepted values: username
 
-Enables debug mode for VM. This can be used to turn on/off verbose logging in many Qubes components at once (gui virtualization, VM kernel, some other services). For template-based HVM, enabling debug mode also disables automatic reset root.img (actually volatile.img) before each VM startup, so changes made to root filesystem stays intact. To force reset root.img when debug mode enabled, either change something in the template (simple start+stop will do, even touch its root.img is enough), or remove VM's volatile.img (check the path with qvm-prefs).
+    Default user used by qvm-run. Note that it make sense only on non-standard
+    template, as the standard one always have "user" account.
 
-qrexec\_installed  
+debug
-Accepted values: `True`, `False`
+    Accepted values: ``on``, ``off``
 
-This HVM have qrexec agent installed. When VM have qrexec agent installed, one can use qvm-run to start VM process, VM will benefit from Qubes RPC services (like file copy, or inter-vm clipboard). This option will be automatically turned on during Qubes Windows Tools installation, but if you install qrexec agent in some other OS, you need to turn this option on manually.
+    Enables debug mode for VM. This can be used to turn on/off verbose logging
+    in many Qubes components at once (gui virtualization, VM kernel, some other
+    services).
+    For template-based HVM, enabling debug mode also disables automatic reset
+    root.img (actually volatile.img) before each VM startup, so changes made to
+    root filesystem stays intact. To force reset root.img when debug mode
+    enabled, either change something in the template (simple start+stop will
+    do, even touch its root.img is enough), or remove VM's volatile.img
+    (check the path with qvm-prefs).
 
-guiagent\_installed  
+qrexec_installed
-Accepted values: `True`, `False`
+    Accepted values: ``True``, ``False``
 
-This HVM have gui agent installed. This option disables full screen GUI virtualization and enables per-window seemless GUI mode. This option will be automatically turned on during Qubes Windows Tools installation, but if you install Qubes gui agent in some other OS, you need to turn this option on manually. You can turn this option off to troubleshoot some early HVM OS boot problems (enter safe mode etc), but the option will be automatically enabled at first VM normal startup (and will take effect from the next startup).
+    This HVM have qrexec agent installed. When VM have qrexec agent installed,
+    one can use qvm-run to start VM process, VM will benefit from Qubes RPC
+    services (like file copy, or inter-vm clipboard). This option will be
+    automatically turned on during Qubes Windows Tools installation, but if you
+    install qrexec agent in some other OS, you need to turn this option on
+    manually.
 
-*Notice:* when Windows GUI agent is installed in the VM, SVGA device (used to full screen video) is disabled, so even if you disable this option, you will not get functional full desktop access (on normal VM startup). Use some other means for that (VNC, RDP or so).
+guiagent_installed
+    Accepted values: ``True``, ``False``
 
-autostart  
+    This HVM have gui agent installed. This option disables full screen GUI
-Accepted values: `True`, `False`
+    virtualization and enables per-window seemless GUI mode. This option will
+    be automatically turned on during Qubes Windows Tools installation, but if
+    you install Qubes gui agent in some other OS, you need to turn this option
+    on manually. You can turn this option off to troubleshoot some early HVM OS
+    boot problems (enter safe mode etc), but the option will be automatically
+    enabled at first VM normal startup (and will take effect from the next
+    startup).
 
-Start the VM during system startup. The default netvm is autostarted regardless of this setting.
+    *Notice:* when Windows GUI agent is installed in the VM, SVGA device (used
+    to full screen video) is disabled, so even if you disable this
+    option, you will not get functional full desktop access (on normal VM
+    startup). Use some other means for that (VNC, RDP or so).
 
-timezone  
+autostart
-Accepted values: `localtime`, time offset in seconds
+    Accepted values: ``True``, ``False``
 
-Set emulated HVM clock timezone. Use `localtime` (the default) to use the same time as dom0 have. Note that HVM will get only clock value, not the timezone itself, so if you use `localtime` setting, OS inside of HVM should also be configured to treat hardware clock as local time (and have proper timezone set).
+    Start the VM during system startup. The default netvm is autostarted
+    regardless of this setting.
+
+timezone
+    Accepted values: ``localtime``, time offset in seconds
+
+    Set emulated HVM clock timezone. Use ``localtime`` (the default) to use the
+    same time as dom0 have. Note that HVM will get only clock value, not the
+    timezone itself, so if you use ``localtime`` setting, OS inside of HVM
+    should also be configured to treat hardware clock as local time (and have
+    proper timezone set).
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/dom0/qvm-remove.md

@@ -9,40 +9,47 @@ redirect_from:
 - /wiki/Dom0Tools/QvmRemove/
 ---
 
+```
+==========
 qvm-remove
 ==========
 
 NAME
-----
+====
-
 qvm-remove - remove a VM
 
-Date  
-2012-04-11
-
 SYNOPSIS
---------
+========
-
+| qvm-remove [options] <vm-name>
-qvm-remove [options] \<vm-name\>
 
 OPTIONS
--------
+=======
-
+-h, --help
--h, --help  
+    Show this help message and exit
-Show this help message and exit
+-q, --quiet
-
+    Be quiet   
--q, --quiet  
+--just-db
-Be quiet
+    Remove only from qubes.xml; do not remove any files
-
+--force-root
---just-db  
+    Force to run, even with root privileges
-Remove only from the Qubes Xen DB, do not remove any files
-
---force-root  
-Force to run, even with root privileges
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/dom0/qvm-revert-template-changes.md

@@ -9,34 +9,43 @@ redirect_from:
 - /wiki/Dom0Tools/QvmRevertTemplateChanges/
 ---
 
+```
+===========================
 qvm-revert-template-changes
 ===========================
 
 NAME
-----
+====
-
 qvm-revert-template-changes
 
-Date  
-2012-04-11
-
 SYNOPSIS
---------
+========
-
+| qvm-revert-template-changes [options] <template-name>
-qvm-revert-template-changes [options] \<template-name\>
 
 OPTIONS
--------
+=======
-
+-h, --help
--h, --help  
+    Show this help message and exit
-Show this help message and exit
+--force
-
+    Do not prompt for confirmation
---force  
-Do not prompt for confirmation
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/dom0/qvm-run.md

@@ -9,70 +9,81 @@ redirect_from:
 - /wiki/Dom0Tools/QvmRun/
 ---
 
+```
+=======
 qvm-run
 =======
 
 NAME
-----
+====
-
 qvm-run - run a command on a specified VM
 
-Date  
-2012-04-11
-
 SYNOPSIS
---------
+========
-
+| qvm-run [options] [<vm-name>] [<cmd>]
-qvm-run [options] [\<vm-name\>] [\<cmd\>]
 
 OPTIONS
--------
+=======
-
+-h, --help
--h, --help  
+    Show this help message and exit
-Show this help message and exit
+-q, --quiet
-
+    Be quiet           
--q, --quiet  
+-a, --auto
-Be quiet
+    Auto start the VM if not running
-
+-u USER, --user=USER
--a, --auto  
+    Run command in a VM as a specified user
-Auto start the VM if not running
+--tray
-
+    Use tray notifications instead of stdout
--u USER, --user=USER  
+--all
-Run command in a VM as a specified user
+    Run command on all currently running VMs (or all paused, in case of --unpause)
-
+--exclude=EXCLUDE_LIST
---tray  
+    When --all is used: exclude this VM name (might be repeated)
-Use tray notifications instead of stdout
+--wait
-
+    Wait for the VM(s) to shutdown
---all  
+--shutdown
-Run command on all currently running VMs (or all paused, in case of --unpause)
+    (deprecated) Do 'xl shutdown' for the VM(s) (can be combined this with --all and --wait)
-
+--pause
---exclude=EXCLUDE\_LIST  
+    Do 'xl pause' for the VM(s) (can be combined this with --all and --wait)
-When --all is used: exclude this VM name (might be repeated)
+--unpause
-
+    Do 'xl unpause' for the VM(s) (can be combined this with --all and --wait)
---wait  
+-p, --pass-io
-Wait for the VM(s) to shutdown
+    Pass stdin/stdout/stderr from remote program
-
+--localcmd=LOCALCMD
---shutdown  
+    With --pass-io, pass stdin/stdout/stderr to the given program
-(deprecated) Do 'xl shutdown' for the VM(s) (can be combined this with --all and --wait)
+--nogui
-
+    Run command without gui
---pause  
+--filter-escape-chars
-Do 'xl pause' for the VM(s) (can be combined this with --all and --wait)
+    Filter terminal escape sequences (default if output is terminal)
-
+--no-filter-escape-chars
---unpause  
+    Do not filter terminal escape sequences - overrides --filter-escape-chars, DANGEROUS when output is terminal
-Do 'xl unpause' for the VM(s) (can be combined this with --all and --wait)
+--no-color-output
-
+    Disable marking VM output with red color
--p, --pass-io  
+--no-color-stderr
-Pass stdin/stdout/stderr from remote program
+    Disable marking VM stderr with red color
-
+--color-output
---localcmd=LOCALCMD  
+    Force marking VM output with given ANSI style (use 31 for red)
-With --pass-io, pass stdin/stdout/stderr to the given program
+--color-stderr
-
+    Force marking VM stderr with given ANSI style (use 31 for red)
---force  
+--force
-Force operation, even if may damage other VMs (eg. shutdown of NetVM)
+    Force operation, even if may damage other VMs (eg. shutdown of NetVM)
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/dom0/qvm-service.md

@@ -9,129 +9,152 @@ redirect_from:
 - /wiki/Dom0Tools/QvmService/
 ---
 
+```
+===========
 qvm-service
 ===========
 
 NAME
-----
+====
-
 qvm-service - manage (Qubes-specific) services started in VM
 
-Date  
-2012-05-30
-
 SYNOPSIS
---------
+========
-
+| qvm-service [-l] <vmname>
-qvm-service [-l] \<vmname\>
+| qvm-service [-e|-d|-D] <vmname> <service>
-qvm-service [-e|-d|-D] \<vmname\> \<service\>
 
 OPTIONS
--------
+=======
-
+-h, --help
--h, --help  
+    Show this help message and exit
-Show this help message and exit
+-l, --list
-
+    List services (default action)
--l, --list  
+-e, --enable
-List services (default action)
+    Enable service
-
+-d, --disable
--e, --enable  
+    Disable service
-Enable service
+-D, --default
-
+    Reset service to its default state (remove from the list). Default state
--d, --disable  
+    means "lets VM choose" and can depend on VM type (NetVM, AppVM etc).
-Disable service
-
--D, --default  
-Reset service to its default state (remove from the list). Default state means "lets VM choose" and can depend on VM type (NetVM, AppVM etc).
 
 SUPPORTED SERVICES
-------------------
+==================
 
 This list can be incomplete as VM can implement any additional service without knowledge of qubes-core code.
 
-meminfo-writer  
+meminfo-writer
-Default: enabled everywhere excluding NetVM
+    Default: enabled everywhere excluding NetVM
 
-This service reports VM memory usage to dom0, which effectively enables dynamic memory management for the VM.
+    This service reports VM memory usage to dom0, which effectively enables dynamic memory management for the VM.
 
-*Note:* this service is enforced to be set by dom0 code. If you try to remove it (reset to default state), will be recreated with the rule: enabled if VM have no PCI devices assigned, otherwise disabled.
+    *Note:* this service is enforced to be set by dom0 code. If you try to
+    remove it (reset to default state), will be recreated with the rule: enabled
+    if VM have no PCI devices assigned, otherwise disabled.
 
-qubes-dvm  
+qubes-dvm
-Default: disabled
+    Default: disabled
 
-Used internally when creating DispVM savefile.
+    Used internally when creating DispVM savefile.
 
-qubes-firewall  
+qubes-firewall
-Default: enabled only in ProxyVM
+    Default: enabled only in ProxyVM
 
-Dynamic firewall manager, based on settings in dom0 (qvm-firewall, firewall tab in qubes-manager). This service is not supported in netvms.
+    Dynamic firewall manager, based on settings in dom0 (qvm-firewall, firewall tab in qubes-manager).
+    This service is not supported in netvms.
+    
+qubes-network
+    Default: enabled only in NetVM and ProxyVM
 
-qubes-network  
+    Expose network for other VMs. This includes enabling network forwarding, MASQUERADE, DNS redirection and basic firewall.
-Default: enabled only in NetVM and ProxyVM
 
-Expose network for other VMs. This includes enabling network forwarding, MASQUERADE, DNS redirection and basic firewall.
+qubes-netwatcher
+    Default: enabled only in ProxyVM
 
-qubes-netwatcher  
+    Monitor IP change notification from NetVM. When received, reload qubes-firewall service (to force DNS resolution).
-Default: enabled only in ProxyVM
+    This service makes sense only with qubes-firewall enabled.
 
-Monitor IP change notification from NetVM. When received, reload qubes-firewall service (to force DNS resolution). This service makes sense only with qubes-firewall enabled.
+qubes-update-check
+    Default: enabled
 
-qubes-update-check  
+    Notify dom0 about updates available for this VM. This is shown in qubes-manager as 'update-pending' flag.
-Default: enabled
 
-Notify dom0 about updates available for this VM. This is shown in qubes-manager as 'update-pending' flag.
+cups
+    Default: enabled only in AppVM
 
-cups  
+    Enable CUPS service. The user can disable cups in VM which do not need printing to speed up booting.
-Default: enabled only in AppVM
 
-Enable CUPS service. The user can disable cups in VM which do not need printing to speed up booting.
+crond
+    Default: disabled
 
-crond  
+    Enable CRON service.
-Default: disabled
 
-Enable CRON service.  To have cron jobs persist across reboots, /var/spool/cron is bind-mounted from /rw/bind-dirs. To override this see [Bind-Dir Instructions](/doc/bind-dirs/) )
+network-manager
+    Default: enabled in NetVM
 
-network-manager  
+    Enable NetworkManager. Only VM with direct access to network device needs
-Default: enabled in NetVM
+    this service, but can be useful in ProxyVM to ease VPN setup.
 
-Enable NetworkManager. Only VM with direct access to network device needs this service, but can be useful in ProxyVM to ease VPN setup.
+ntpd
+    Default: disabled
 
-ntpd  
+    Enable NTPD service. By default Qubes calls ntpdate every 6 minutes in
-Default: disabled
+    selected VM (aka ClockVM), then propagate the result using qrexec calls.
+    Enabling ntpd *do not* disable this behaviour.
 
-Enable NTPD service. By default Qubes calls ntpdate every 6 minutes in selected VM (aka ClockVM), then propagate the result using qrexec calls. Enabling ntpd *do not* disable this behaviour.
+qubes-yum-proxy
+    Deprecated name for qubes-updates-proxy.
 
-qubes-yum-proxy  
+qubes-updates-proxy
-Deprecated name for qubes-updates-proxy.
+    Default: enabled in NetVM
 
-qubes-updates-proxy  
+    Provide proxy service, which allow access only to yum repos. Filtering is
-Default: enabled in NetVM
+    done based on URLs, so it shouldn't be used as leak control (pretty easy to
+    bypass), but is enough to prevent some erroneous user actions.
 
-Provide proxy service, which allow access only to yum repos. Filtering is done based on URLs, so it shouldn't be used as leak control (pretty easy to bypass), but is enough to prevent some erroneous user actions.
+yum-proxy-setup
+    Deprecated name for updates-proxy-setup.
 
-yum-proxy-setup  
+updates-proxy-setup
-Deprecated name for updates-proxy-setup.
+    Default: enabled in AppVM (also in templates)
 
-updates-proxy-setup  
+    Setup yum at startup to use qubes-yum-proxy service.
-Default: enabled in AppVM (also in templates)
 
-Setup yum at startup to use qubes-yum-proxy service.
+    *Note:* this service is automatically enabled when you allow VM to access
+    yum proxy (in firewall settings) and disabled when you deny access to yum
+    proxy.
 
-*Note:* this service is automatically enabled when you allow VM to access yum proxy (in firewall settings) and disabled when you deny access to yum proxy.
+disable-default-route
+    Default: disabled
 
-disable-default-route  
+    Disables the default route for networking.  Enabling  this  service
-Default: disabled
+    will  prevent the creation of the default route, but the VM will
+    still be able to reach it's direct neighbors.  The functionality
+    is implemented in /usr/lib/qubes/setup-ip.
 
-Disables the default route for networking. Enabling this service will prevent the creation of the default route, but the VM will still be able to reach it's direct neighbors. The functionality is implemented in /usr/lib/qubes/setup-ip.
+disable-dns-server
+    Default: disabled
 
-disable-dns-server  
+    Enabling this service will result in an empty /etc/resolv.conf.
-Default: disabled
+    The functionality is implemented in /usr/lib/qubes/setup-ip.
 
-Enabling this service will result in an empty /etc/resolv.conf. The functionality is implemented in /usr/lib/qubes/setup-ip.
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/dom0/qvm-shutdown.md

@@ -9,46 +9,53 @@ redirect_from:
 - /wiki/Dom0Tools/QvmShutdown/
 ---
 
+```
+============
 qvm-shutdown
 ============
 
 NAME
-----
+====
-
 qvm-shutdown
 
-Date  
-2012-04-11
-
 SYNOPSIS
---------
+========
-
+| qvm-shutdown [options] <vm-name> [vm-name ...]
-qvm-shutdown [options] \<vm-name\>
 
 OPTIONS
--------
+=======
-
+-h, --help
--h, --help  
+    Show this help message and exit
-Show this help message and exit
+-q, --quiet
-
+    Be quiet           
--q, --quiet  
+--force
-Be quiet
+    Force operation, even if may damage other VMs (eg. shutdown of NetVM)
-
+--wait
---force  
+    Wait for the VM(s) to shutdown
-Force operation, even if may damage other VMs (eg. shutdown of NetVM)
+--wait-time
-
+    Timeout after which VM will be killed when --wait is used
---wait  
+--all
-Wait for the VM(s) to shutdown
+    Shutdown all running VMs
-
+--exclude=EXCLUDE_LIST
---all  
+    When --all is used: exclude this VM name (might be repeated)
-Shutdown all running VMs
-
---exclude=EXCLUDE\_LIST  
-When --all is used: exclude this VM name (might be repeated)
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/dom0/qvm-start.md

@@ -9,46 +9,63 @@ redirect_from:
 - /wiki/Dom0Tools/QvmStart/
 ---
 
+```
+=========
 qvm-start
 =========
 
 NAME
-----
+====
-
 qvm-start - start a specified VM
 
-Date  
-2012-04-11
-
 SYNOPSIS
---------
+========
-
+| qvm-start [options] <vm-name>
-qvm-start [options] \<vm-name\>
 
 OPTIONS
--------
+=======
-
+-h, --help
--h, --help  
+    Show this help message and exit
-Show this help message and exit
+-q, --quiet
-
+    Be quiet           
--q, --quiet  
+--tray
-Be quiet
+    Use tray notifications instead of stdout
-
+--no-guid
---no-guid  
+    Do not start the GUId (ignored)
-Do not start the GUId (ignored)
+--drive
-
+    Temporarily attach specified drive as CD/DVD or hard disk (can be specified with prefix 'hd' or 'cdrom:', default is cdrom)
---console  
+--hddisk
-Attach debugging console to the newly started VM
+    Temporarily attach specified drive as hard disk
-
+--cdrom
---dvm  
+    Temporarily attach specified drive as CD/DVD
-Do actions necessary when preparing DVM image
+--install-windows-tools
-
+    Attach Windows tools CDROM to the VM
---custom-config=CUSTOM\_CONFIG  
+--dvm
-Use custom Xen config instead of Qubes-generated one
+    Do actions necessary when preparing DVM image
+--custom-config=CUSTOM_CONFIG
+    Use custom Xen config instead of Qubes-generated one
+--skip-if-running
+    Do no fail if the VM is already running
+--debug
+    Enable debug mode for this VM (until its shutdown)
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/dom0/qvm-template-commit.md

@@ -9,31 +9,43 @@ redirect_from:
 - /wiki/Dom0Tools/QvmTemplateCommit/
 ---
 
+```
+===================
 qvm-template-commit
 ===================
 
 NAME
-----
+====
-
 qvm-template-commit
 
-Date  
-2012-04-11
-
 SYNOPSIS
---------
+========
-
+| qvm-template-commit [options] <vm-name>
-qvm-template-commit [options] \<vm-name\>
 
 OPTIONS
--------
+=======
-
+-h, --help
--h, --help  
+    Show this help message and exit
-Show this help message and exit
+--offline-mode
+    Offline mode
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/dom0/qvm-usb.md

@@ -0,0 +1,59 @@
+---
+layout: doc
+title: qvm-usb
+permalink: /doc/tools/3.2/dom0/qvm-usb/
+redirect_from:
+- /doc/dom0-tools/qvm-usb/
+- /en/doc/dom0-tools/qvm-usb/
+---
+
+```
+=======
+qvm-usb
+=======
+
+NAME
+====
+qvm-usb - List/set VM USB devices
+
+SYNOPSIS
+========
+| qvm-usb -l [options]
+| qvm-usb -a [options] <vm-name> <device-vm-name>:<device>
+| qvm-usb -d [options] <device-vm-name>:<device>
+
+OPTIONS
+=======
+-h, --help
+    Show this help message and exit
+-l, -list
+    List devices
+-a, --attach
+    Attach specified device to specified VM
+-d, --detach
+    Detach specified device
+--no-auto-detach
+    Fail when device already connected to other VM
+--force-root
+    Force to run, even with root privileges
+
+AUTHORS
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-admin/doc/qvm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-admin/doc/qvm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
+

reference/tools/3.2/domU.md

@@ -12,6 +12,7 @@ redirect_from:
 DomU Command-Line Tools for Qubes 3.2
 =====================================
 
+ * [qrexec-client-vm](/doc/tools/3.2/domU/qrexec-client-vm/)
  * [qvm-copy-to-vm](/doc/tools/3.2/domU/qvm-copy-to-vm/)
  * [qvm-open-in-dvm](/doc/tools/3.2/domU/qvm-open-in-dvm/)
  * [qvm-open-in-vm](/doc/tools/3.2/domU/qvm-open-in-vm/)

reference/tools/3.2/domU/qrexec-client-vm.md

@@ -0,0 +1,100 @@
+---
+layout: doc
+title: qrexec-client-vm
+permalink: /doc/tools/3.2/domU/qrexec-client-vm/
+redirect_from:
+- /doc/domU-tools/qrexec-client-vm/
+- /en/doc/domU-tools/qrexec-client-vm/
+---
+
+```
+================
+qrexec-client-vm
+================
+
+NAME
+====
+qrexec-client-vm - call Qubes RPC service
+
+SYNOPSIS
+========
+| qrexec-client-vm *target_vmname* *service* [*local_program* [*local program arguments*]]
+
+DESCRIPTION
+===========
+
+Call Qubes RPC (aka qrexec) service to a different VM. The service call request
+is sent to dom0, where Qubes RPC policy is evaluated and when it allows the
+call, it is forwarded to appropriate target VM (which may be different than
+requested, if policy says so). Local program (if given) is started only
+when service call is allowed by the policy.
+
+Remote service can communicate with the caller (``qrexec-client-vm``) using
+stdin/stdout.  When *local_program* is given, its stdin/stdout is connected to
+service stdin/stdout (stderr is not redirected), otherwise - service
+stdin/stdout is connected to those of ``qrexec-client-vm``.
+
+OPTIONS
+=======
+
+*target_vmname*
+
+    Name of target VM to which service is requested. Qubes RPC policy may
+    ignore this value and redirect call somewhere else.
+
+    This argument, can contain VM name, or one of special values:
+
+    * ``$dispvm`` - new Disposable VM
+
+    This field is limited to 31 characters (alphanumeric, plus ``-_.$``).
+
+*service*
+
+    Requested service. Besides service name, it can contain a service argument
+    after ``+`` character. For example ``some.service+argument``.
+
+    This field is limited to 63 characters (alphanumeric, plus ``-_.$+``).
+
+*local_program*
+
+    Full path to local program to be connected with remote service. Optional.
+
+*local program arguments*
+
+    Arguments to *local_program*. Optional.
+
+EXIT STATUS
+===========
+
+If service call is allowed by dom0 and ``qrexec-client-vm`` is started without
+*local_program* argument, it reports remote service exit code.
+
+If service call is allowed by dom0 and ``qrexec-client-vm`` is started with
+*local_program* argument, it reports the local program exit code. There is no
+way to learn exit code of remote service in this case.
+
+In both cases, if process (local or remote) was terminated by a signal, exit
+status is 128+signal number.
+
+If service call is denied by dom0, ``qrexec-client-vm`` exit with status 126.
+
+AUTHORS
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski-Górecki <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-agent-linux/doc/vm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-agent-linux/doc/vm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
+

reference/tools/3.2/domU/qvm-copy-to-vm.md

@@ -9,31 +9,41 @@ redirect_from:
 - /wiki/VmTools/QvmCopyToVm/
 ---
 
+```
+==============
 qvm-copy-to-vm
 ==============
 
 NAME
-----
+====
-
 qvm-copy-to-vm - copy specified files to specified destination VM
 
-Date  
-2012-05-30
-
 SYNOPSIS
---------
+========
-
+| qvm-copy-to-vm [--without-progress] dest_vmname file [file]+
-qvm-copy-to-vm [--without-progress] dest\_vmname file [file]+
 
 OPTIONS
--------
+=======
-
+--without-progress
---without-progress  
+    Don't display progress info
-Don't display progress info
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-agent-linux/doc/vm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-agent-linux/doc/vm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/domU/qvm-open-in-dvm.md

@@ -9,28 +9,39 @@ redirect_from:
 - /wiki/VmTools/QvmOpenInDvm/
 ---
 
+```
+===============
 qvm-open-in-dvm
 ===============
 
 NAME
-----
+====
-
 qvm-open-in-dvm - open a specified file in disposable VM
 
-Date  
-2012-05-30
-
 SYNOPSIS
---------
+========
-
+| qvm-open-in-dvm filename
-qvm-open-in-dvm filename
 
 OPTIONS
--------
+=======
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-agent-linux/doc/vm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-agent-linux/doc/vm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/domU/qvm-open-in-vm.md

@@ -9,28 +9,39 @@ redirect_from:
 - /wiki/VmTools/QvmOpenInVm/
 ---
 
+```
+==============
 qvm-open-in-vm
 ==============
 
 NAME
-----
+====
-
 qvm-open-in-vm - open a specified file in other VM
 
-Date  
-2012-05-30
-
 SYNOPSIS
---------
+========
-
+| qvm-open-in-vm vmname filename
-qvm-open-in-vm vmname filename
 
 OPTIONS
--------
+=======
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-agent-linux/doc/vm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-agent-linux/doc/vm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

reference/tools/3.2/domU/qvm-run.md

@@ -9,31 +9,41 @@ redirect_from:
 - /wiki/VmTools/QvmRun/
 ---
 
+```
+=======
 qvm-run
 =======
 
 NAME
-----
+====
-
 qvm-run - run a specified command in a specified VM
 
-Date  
-2012-05-30
-
 SYNOPSIS
---------
+========
-
+| qvm-run vmname command [aguments]
-qvm-run vmname command [arguments]
 
 OPTIONS
--------
+=======
-
+--dispvm
---dispvm  
+    Pass this option instead of vmname to start new DisposableVM
-Pass this option instead of vmname to start new DisposableVM
 
 AUTHORS
--------
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski <marmarek at invisiblethingslab dot com>
+```
+
+-----
+
+**Note:** The Markdown source of this page in [`qubes-doc`] was generated by
+running the [`update-manpages`] script on `qubes-core-agent-linux/doc/vm-tools/`.
+If you wish to update the contents of this page as it appears on the Qubes OS
+website, please submit a pull request to change the appropriate file in
+`qubes-core-agent-linux/doc/vm-tools/`. Do not attempt to change the Markdown source
+of this page in [`qubes-doc`] directly. All direct changes to the Markdown file will be
+overwritten the next time this page is regenerated.
+
+[`qubes-doc`]: https://github.com/QubesOS/qubes-doc/
+[`update-manpages`]: https://github.com/QubesOS/qubesos.github.io/blob/master/_utils/update-manpages
 
-Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
-Rafal Wojtczuk \<rafal at invisiblethingslab dot com\>
-Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

releases/1.0/release-notes.md

@@ -16,7 +16,7 @@ Known issues
 
 -   Installer might not support some USB keyboards (\#230). This seems to include all the Mac Book keyboards (most PC laptops have PS2 keyboards and are not affected).
 
--   If you don't enable Composition (System Setting -\> Desktop -\> Enable desktop effects), which you really should do, then the KDE task bar might get somehow ugly (e.g. half of it might be black). This is some KDE bug that we don't plan to fix.
+-   If you don't enable Composition (System Setting -\> Desktop -\> Enable desktop effects), which you really should do, then the KDE task bar might get ugly (e.g. half of it might be black). This is some KDE bug that we don't plan to fix.
 
 -   Some keyboard layout set by KDE System Settings can cause [keyboard not working at all](https://groups.google.com/group/qubes-devel/browse_thread/thread/77d076b65dda7226). If you hit this issue, you can switch to console (by console login option) and manually edit `/etc/X11/xorg.conf.d/00-system-setup-keyboard.conf` (and `/etc/sysconfig/keyboard`) and place correct keyboard layout settings (details in linked thread). You can check if specific keyboard layout settings are proper using `setxkbmap` tool.
 

releases/3.1/release-notes.md

@@ -32,7 +32,7 @@ Known issues
 
 * Some icons in the Qubes Manager application might not be drawn correctly when using the Xfce4 environment in Dom0. If this bothers you, please use the KDE environment instead.
 
-* USB mouse (in case of USB VM) does not work at first system startup (just after completing firstboot). Workaround: restart the system.
+* USB mouse (in the case of USB VM) does not work at first system startup (just after completing firstboot). Workaround: restart the system.
 
 * For other known issues take a look at [our tickets](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22Release+3.1%22+label%3Abug)
 

releases/3.2/release-notes.md

@@ -24,7 +24,7 @@ You can get detailed description in [completed github issues][github-release-not
 Known issues
 ------------
 
-* [Fedora 23 reached EOL in December 2016](https://fedoraproject.org/wiki/End_of_life). There is a [manual procedure to upgrade your VMs](/news/2016/11/15/fedora-24-template-available/).
+* [Fedora 23 reached EOL in December 2016](https://fedoraproject.org/wiki/End_of_life). There is a [manual procedure to upgrade your VMs](/news/2018/01/06/fedora-26-upgrade/).
 
 * Windows Tools: `qvm-block` does not work
 
@@ -43,7 +43,7 @@ Installation instructions
 -------------------------
 
 See [Installation Guide](/doc/installation-guide/).
-After installation, [manually upgrade to Fedora 24](/news/2016/11/15/fedora-24-template-available/).
+After installation, [manually upgrade to Fedora 26](/news/2018/01/06/fedora-26-upgrade/).
 
 Upgrading
 ---------

releases/4.0/release-notes.md

@@ -31,6 +31,13 @@ New features since 3.2
 
 You can get detailed description in [completed github issues][github-release-notes]
 
+Security Notes
+--------------
+
+* PV VMs migrated from 3.2 to 4.0-rc4 or later are automatically set to PVH mode in order to protect against Meltdown (see [QSB #37][qsb-37]).
+  However, PV VMs migrated from any earlier 4.0 release candidate (RC1, RC2, or RC3) are not automatically set to PVH mode.
+  These must be set manually.
+
 Known issues
 ------------
 
@@ -76,6 +83,7 @@ We also provide [detailed instruction][upgrade-to-r4.0] for this procedure.
 [vm-interface]: /doc/vm-interface/
 [admin-api]: /news/2017/06/27/qubes-admin-api/
 [qsb-24]: https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-024-2016.txt
+[qsb-37]: https://www.qubes-os.org/news/2018/01/24/qsb-37-update/
 [backup-format]: /doc/backup-emergency-restore-v4/
 [api-doc]: https://dev.qubes-os.org/projects/qubes-core-admin/en/latest/
 [upgrade-to-r4.0]: /doc/upgrade-to-r4.0/

releases/4.0/schedule.md

@@ -22,4 +22,7 @@ This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule
 | 11 Dec 2017 | decide whether 4.0-rc3 is the final 4.0 |
 |  1 Jan 2018 | current-testing freeze before 4.0-rc4 |
 | <strike>8 Jan 2018</strike><br/>31 Jan 2018 | 4.0-rc4 release |
-| <strike>22 Jan 2018</strike><br/>TBD | decide whether 4.0-rc4 is the final 4.0 |
+| <strike>22 Jan 2018</strike><br/>14 Feb 2018 | decide whether 4.0-rc4 is the final 4.0 |
+| 27 Feb 2018 | current-testing freeze before 4.0-rc5 |
+|  6 Mar 2018 | 4.0-rc5 release |
+| 20 Mar 2018 | decide whether 4.0-rc5 is the final 4.0 |

security-info/security-bulletins.md

@@ -88,4 +88,5 @@ Qubes Security Bulletins are published through the [Qubes Security Pack](/securi
 ----
 
 -   [Qubes Security Bulletin \#37](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-037-2018.txt) (Information leaks due to processor speculative execution bugs)
+-   [Qubes Security Bulletin \#38](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-038-2018.txt) (Qrexec policy bypass and possible information leak)