Markdown formatting fixes

- mark all code blocks with ```
- unify empty lines between sections
- adjust list syntax (no space before dash)
- adjust headers to use Atx-style syntax
- remove trailing spaces

developer/building/development-workflow.md

@@ -8,16 +8,14 @@ redirect_from:
 - /wiki/DevelopmentWorkflow/
 ---
 
-Development Workflow
+# Development Workflow
-====================
 
 A workflow for developing Qubes OS+
 
 First things first, setup [QubesBuilder](/doc/qubes-builder/). This guide
 assumes you're using qubes-builder to build Qubes.
 
-Repositories and committing Code
+# Repositories and committing Code
---------------------------------
 
 Qubes is split into a bunch of git repos. This are all contained in the
 `qubes-src` directory under qubes-builder. Subdirectories there are separate
@@ -149,21 +147,20 @@ RPMS will appear in qubes-src/linux-kernel/pkgs/fc20/x86\_64:
 
 ### Useful [QubesBuilder](/doc/qubes-builder/) commands
 
-1.  `make check` - will check if all the code was committed into repository and
+1. `make check` - will check if all the code was committed into repository and
 if all repository are tagged with signed tag.
-2.  `make show-vtags` - show version of each component (based on git tags) -
+2. `make show-vtags` - show version of each component (based on git tags) -
 mostly useful just before building ISO. **Note:** this will not show version
 for components containing changes since last version tag
-3.  `make push` - push change from **all** repositories to git server. You must
+3. `make push` - push change from **all** repositories to git server. You must
 set proper remotes (see above) for all repositories first.
-4.  `make prepare-merge` - fetch changes from remote repositories (can be
+4. `make prepare-merge` - fetch changes from remote repositories (can be
 specified on commandline via GIT\_SUBDIR or GIT\_REMOTE vars), (optionally)
 verify tags and show the changes. This do not merge the changes - there are
 left for review as FETCH\_HEAD ref. You can merge them using `git merge
 FETCH_HEAD` (in each repo directory). Or `make do-merge` to merge all of them.
 
-Copying Code to dom0
+## Copying Code to dom0
---------------------
 
 When developing it is convenient to be able to rapidly test changes. Assuming
 you're developing Qubes on Qubes, you should be working in a special VM for
@@ -309,7 +306,6 @@ to `testbuilder` VM. Otherwise it creates remote pointing at github account of
 the same name. In any case it points at repository matching current directory
 name.
 
-
 ## Sending packages to different VM
 
 Other useful script(s) can be used to setup local package repository hosted in
@@ -421,10 +417,10 @@ Remember to also import gpg public key using `rpm --import`.
 
 Steps are mostly the same as in the case of yum repo. The only details that differ:
 
- - use [linux-deb] instead of [linux-yum] as a base - both in source and target VM
+- 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)
+- use different `update_repo.sh` script in source VM (below)
- - use `local.UpdateApt` qrexec service in target VM (code below)
+- use `local.UpdateApt` qrexec service in target VM (code below)
- - in target VM additionally place `update-local-repo.sh` script in repository dir (code below)
+- in target VM additionally place `update-local-repo.sh` script in repository dir (code below)
 
 `update_repo.sh` script:
 

developer/building/qubes-builder-details.md

@@ -18,28 +18,28 @@ Components Makefile.builder file
 
 Variables for Linux build:
 
--   `RPM_SPEC_FILES` List (space separated) of spec files for RPM package build. Path should be relative to component root directory. [QubesBuilder](/doc/qubes-builder/) will install all BuildRequires (in chroot environment) before the build. In most Qubes components all spec files are kept in *rpm\_spec* directory. This is mainly used for Fedora packages build.
+- `RPM_SPEC_FILES` List (space separated) of spec files for RPM package build. Path should be relative to component root directory. [QubesBuilder](/doc/qubes-builder/) will install all BuildRequires (in chroot environment) before the build. In most Qubes components all spec files are kept in *rpm\_spec* directory. This is mainly used for Fedora packages build.
--   `ARCH_BUILD_DIRS` List (space separated) of directories with PKGBUILD files for Archlinux package build. Similar to RPM build, [QubesBuilder](/doc/qubes-builder/) will install all makedepends, then build the package.
+- `ARCH_BUILD_DIRS` List (space separated) of directories with PKGBUILD files for Archlinux package build. Similar to RPM build, [QubesBuilder](/doc/qubes-builder/) will install all makedepends, then build the package.
 
 Most components uses *archlinux* directory for this purpose, so its good to keep this style.
 
 Variables for Windows build:
 
--   `WIN_COMPILER` Choose which compiler should be used for this component, thus which build scripts. Currently two options available:
+- `WIN_COMPILER` Choose which compiler should be used for this component, thus which build scripts. Currently two options available:
-    -   `WDK` - Windows Driver Kit (default). Command used to build: *build -cZg*.
+  - `WDK` - Windows Driver Kit (default). Command used to build: *build -cZg*.
-    -   `mingw` - MinGW (Windows gcc port). Command used to build: *make all*
+  - `mingw` - MinGW (Windows gcc port). Command used to build: *make all*
--   `WIN_SOURCE_SUBDIRS` List of directories in which above command should be run. In most cases it will be only one entry: current directory (*.*).
+- `WIN_SOURCE_SUBDIRS` List of directories in which above command should be run. In most cases it will be only one entry: current directory (*.*).
--   `WIN_PREBUILD_CMD` Command to run before build, mostly useful for WDK build (in mingw case, you can use makefile for this purpose). Can be used to set some variables, preprocess some files etc.
+- `WIN_PREBUILD_CMD` Command to run before build, mostly useful for WDK build (in mingw case, you can use makefile for this purpose). Can be used to set some variables, preprocess some files etc.
--   `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:
+- `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_FILENAME` Path to key file (pfx format)
-    -   `CERT_PASSWORD` Key password
+  - `CERT_PASSWORD` Key password
-    -   `CERT_PUBLIC_FILENAME` Certificate path in the case of self-signed cert
+  - `CERT_PUBLIC_FILENAME` Certificate path in the case of self-signed cert
-    -   `CERT_CROSS_CERT_FILENAME` Certificate path in the case of correct autheticode cert
+  - `CERT_CROSS_CERT_FILENAME` Certificate path in the case of correct autheticode cert
-    -   `SIGNTOOL` Path to signtool
+  - `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_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.
+- `WIN_OUTPUT_HEADERS` Directory (relative to `WIN_SOURCE_SUBDIRS` element) with public headers of the package - for use in other components.
--   `WIN_OUTPUT_LIBS` Directory (relative to `WIN_SOURCE_SUBDIRS` element) with libraries (both DLL and implib) of the package - for use in other components. Note that [QubesBuilder](/doc/qubes-builder/) will copy files specified as *\$(WIN\_OUTPUT\_LIBS)/\*/\** to match WDK directory layout (*\<specified directory\>/\<arch directory\>/\<actual libraries\>*), so you in mingw build you need to place libraries in some additional subdirectory.
+- `WIN_OUTPUT_LIBS` Directory (relative to `WIN_SOURCE_SUBDIRS` element) with libraries (both DLL and implib) of the package - for use in other components. Note that [QubesBuilder](/doc/qubes-builder/) will copy files specified as *\$(WIN\_OUTPUT\_LIBS)/\*/\** to match WDK directory layout (*\<specified directory\>/\<arch directory\>/\<actual libraries\>*), so you in mingw build you need to place libraries in some additional subdirectory.
--   `WIN_BUILD_DEPS` List of components required to build this one. [QubesBuilder](/doc/qubes-builder/) will copy files specified with `WIN_OUTPUT_HEADERS` and `WIN_OUTPUT_LIBS` of those components to some directory and provide its path with `QUBES_INCLUDES` and `QUBES_LIBS` variables. Use those variables in your build scripts (*sources* or *Makefile* - depending on selected compiler). You can assume that the variables are always set and directories always exists, even if empty.
+- `WIN_BUILD_DEPS` List of components required to build this one. [QubesBuilder](/doc/qubes-builder/) will copy files specified with `WIN_OUTPUT_HEADERS` and `WIN_OUTPUT_LIBS` of those components to some directory and provide its path with `QUBES_INCLUDES` and `QUBES_LIBS` variables. Use those variables in your build scripts (*sources* or *Makefile* - depending on selected compiler). You can assume that the variables are always set and directories always exists, even if empty.
 
 builder.conf settings
 ---------------------

developer/building/qubes-builder.md

@@ -10,8 +10,7 @@ redirect_from:
 
 **Note: See [ISO building instructions](/doc/qubes-iso-building/) for a streamlined overview on how to use the build system.**
 
-Building Qubes from scratch
+# Building Qubes from scratch
-===========================
 
 We have a fully automated build system for Qubes, that downloads, builds and
 packages all the Qubes components, and finally should spit out a ready-to-use
@@ -19,27 +18,29 @@ installation ISO, all in a [secure](/news/2016/05/30/build-security/) way.
 
 In order to use it, you should use an rpm-based distro, like Fedora :), and should ensure the following packages are installed:
 
--   sudo
+- sudo
--   gnupg
+- gnupg
--   git
+- git
--   createrepo
+- createrepo
--   rpm-build
+- rpm-build
--   make
+- make
--   wget
+- wget
--   rpmdevtools
+- rpmdevtools
--   python3-sh
+- python3-sh
--   dialog
+- dialog
--   rpm-sign
+- rpm-sign
--   dpkg-dev
+- dpkg-dev
--   debootstrap
+- debootstrap
--   python3-pyyaml
+- python3-pyyaml
--   devscripts
+- devscripts
--   perl-Digest-MD5
+- perl-Digest-MD5
--   perl-Digest-SHA
+- perl-Digest-SHA
 
 Usually you can install those packages by just issuing:
 
-    sudo dnf install gnupg git createrepo rpm-build make wget rpmdevtools python3-sh dialog rpm-sign dpkg-dev debootstrap python3-pyyaml devscripts perl-Digest-MD5 perl-Digest-SHA
+```shell
+sudo dnf install gnupg git createrepo rpm-build make wget rpmdevtools python3-sh dialog rpm-sign dpkg-dev debootstrap python3-pyyaml devscripts perl-Digest-MD5 perl-Digest-SHA
+```
 
 The build system creates build environments in chroots and so no other packages are needed on the host.
 All files created by the build system are contained within the qubes-builder directory.
@@ -49,83 +50,91 @@ The build system is configured via builder.conf file.
 You can use the setup.sh script to create and modify this file.
 Alternatively, you can copy the provided default builder.conf, and modify it as needed, e.g.:
 
-    cp example-configs/qubes-os-master.conf builder.conf 
+```shell
-    # edit the builder.conf file and set the following variables: 
+cp example-configs/qubes-os-master.conf builder.conf
-    NO_SIGN=1
+# edit the builder.conf file and set the following variables:
+NO_SIGN=1
+```
 
 One additional useful requirement is that 'sudo root' must work without any prompt, which is default on most distros (e.g. 'sudo bash' brings you the root shell without asking for any password).
 This is important as the builder needs to switch to root and then back to user several times during the build process.
 
 Additionally, if building with signing enabled (NO\_SIGN is not set), you must adjust \~/.rpmmacro file so that it points to the GPG key used for package signing, e.g.:
 
-    %_signature gpg
+```bash
-    %_gpg_path /home/user/.gnupg
+%_signature gpg
-    %_gpg_name AC1BF9B3  # <-- Key ID used for signing
+%_gpg_path /home/user/.gnupg
+%_gpg_name AC1BF9B3  # <-- Key ID used for signing
+```
 
 It is also recommended that you use an empty passphrase for the private key used for signing.
 Contrary to a popular belief, this doesn't affect your key or sources security -- if somebody compromised your system, then the game is over anyway, whether you have used an additional passphrase for the key or not.
 
 So, to build Qubes you would do:
 
-    # Import the Qubes master key 
+```shell
-    gpg --recv-keys 0xDDFA1A3E36879494
+# Import the Qubes master key
+gpg --recv-keys 0xDDFA1A3E36879494
 
-    # Verify its fingerprint, set as 'trusted'. 
+# Verify its fingerprint, set as 'trusted'.
-    # This is described here: 
+# This is described here:
-    # https://www.qubes-os.org/doc/VerifyingSignatures
+# https://www.qubes-os.org/doc/VerifyingSignatures
 
-    wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc
+wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc
-    gpg --import qubes-developers-keys.asc 
+gpg --import qubes-developers-keys.asc
 
-    git clone git://github.com/QubesOS/qubes-builder.git qubes-builder 
+git clone git://github.com/QubesOS/qubes-builder.git qubes-builder
-    cd qubes-builder 
+cd qubes-builder
 
-    # Verify its integrity:
+# Verify its integrity:
-    git tag -v `git describe`
+git tag -v `git describe`
 
-    cp example-configs/qubes-os-master.conf builder.conf 
+cp example-configs/qubes-os-master.conf builder.conf
-    # edit the builder.conf file and set the following variables: 
+# edit the builder.conf file and set the following variables:
-    # NO_SIGN="1"
+# NO_SIGN="1"
 
-    # Download all components:
+# Download all components:
 
-    make get-sources
+make get-sources
 
-    # And now to build all Qubes rpms (this will take a few hours): 
+# And now to build all Qubes rpms (this will take a few hours):
 
-    make qubes 
+make qubes
 
-    # ... and then to build the ISO 
+# ... and then to build the ISO
 
-    make iso 
+make iso
+```
 
 And this should produce a shiny new ISO.
 
 You can also build selected component separately. Eg. to compile only gui virtualization agent/daemon:
 
+```shell
     make gui-daemon
+```
 
 You can get a full list from make help.
 
-Making customized build
+## Making customized build
------------------------
 
 ### Manual source modification
 
 You can also modify sources somehow if you wish.
 Here are some basic steps:
 
-1.  Download qubes-builder as described above (if you want to use marmarek's branches, you should also download qubes-builder from his repo - replace 'QubesOS' with 'marmarek' in above git clone command)
+1. Download qubes-builder as described above (if you want to use marmarek's branches, you should also download qubes-builder from his repo - replace 'QubesOS' with 'marmarek' in above git clone command)
-2.  Edit builder.conf (still the same as above), some useful additions:
+2. Edit builder.conf (still the same as above), some useful additions:
-    -   You can also set GIT\_PREFIX="marmarek/qubes-" to use marmarek's repo instead of "mainstream" - it contains newer (but less tested) versions
+  - You can also set GIT\_PREFIX="marmarek/qubes-" to use marmarek's repo instead of "mainstream" - it contains newer (but less tested) versions
+3. Download unmodified sources
 
-3.  Download unmodified sources
+    ```shell
+    make get-sources
+    ```
 
-        make get-sources
+4. **Make your modifications here**
 
-4.  **Make your modifications here**
+5. Build the Qubes
-
-5.  Build the Qubes
      `make qubes` actually is just meta target which builds all required
      components in correct order. The list of components is configured in
      builder.conf. You can also check the current value at the end of `make
@@ -133,11 +142,15 @@ Here are some basic steps:
 
 6. `get-sources` is already done, so continue with the next one. You can skip `sign-all` if you've disabled signing
 
-        make vmm-xen core-admin linux-kernel gui-daemon template desktop-linux-kde installer-qubes-os manager linux-dom0-updates
+    ```shell
+    make vmm-xen core-admin linux-kernel gui-daemon template desktop-linux-kde installer-qubes-os manager linux-dom0-updates
+    ```
 
-1.  build iso installation image
+7. build iso installation image
 
-        make iso
+    ```shell
+    make iso
+    ```
 
 ### Use pre-built Qubes packages
 
@@ -146,19 +159,25 @@ This is especially true for `gcc`, which takes several hours to build.
 
 Before creating the `chroot`, add this to your `builder.conf`:
 
-    USE_QUBES_REPO_VERSION = $(RELEASE)
+```
+USE_QUBES_REPO_VERSION = $(RELEASE)
+```
 
 It will add the 'current' Qubes repository to your `chroot` environment.
 Next, specify which components (`gcc`, for example) you want to download instead of compiling:
 
-    COMPONENTS := $(filter-out gcc,$(COMPONENTS))
+```
+COMPONENTS := $(filter-out gcc,$(COMPONENTS))
+```
 
 Alternatively, edit the actual COMPONENTS list which is defined in the included version-dependent config from example-configs (see series of include directives near the beginning of `builder.conf`).
 This way, you can build only the packages in which you are interested.
 
 If you also want to use the 'current-testing' repository, add this to your configuration:
 
-    USE_QUBES_REPO_TESTING = 1
+```
+USE_QUBES_REPO_TESTING = 1
+```
 
 In the case of an existing `chroot`, for mock-enabled builds, this works immediately because `chroot` is constructed each time separately.
 For legacy builds, it will not add the necessary configuration into the build environment unless a specific builder change or configuration would force rebuilding chroot.
@@ -170,22 +189,22 @@ And even if it did, there could be some leftover packages installed from those r
 If you are building Ubuntu templates, you cannot use this option.
 This is because Qubes does not provide official packages for Ubuntu templates.
 
-Code verification keys management
+## Code verification keys management
----------------------------------
 
 [QubesBuilder](/doc/qubes-builder/) by default verifies signed tags on every downloaded code.
 Public keys used for that are stored in `keyrings/git`.
 By default Qubes developers' keys are imported automatically, but if you need some additional keys (for example your own), you can add them using:
 
-    GNUPGHOME=$PWD/keyrings/git gpg --import /path/to/key.asc
+```shell
-    GNUPGHOME=$PWD/keyrings/git gpg --edit-key ID_OF_JUST_IMPORTED_KEY
+GNUPGHOME=$PWD/keyrings/git gpg --import /path/to/key.asc
-    # here use "trust" command to set key fully or ultimately trusted - only those keys are accepted by QubesBuilder
+GNUPGHOME=$PWD/keyrings/git gpg --edit-key ID_OF_JUST_IMPORTED_KEY
+# here use "trust" command to set key fully or ultimately trusted - only those keys are accepted by QubesBuilder
+```
 
 All Qubes developers' keys are signed by the Qubes Master Signing Key (which is set as ultimately trusted key), so are trusted automatically.
 
 If you are the owner of Master key and want to revoke such signature, use the `revsig` gpg key edit command and update the key in qubes-developers-keys.asc - now the key will be no longer trusted (unless manually set as such).
 
-Further information
+## Further information
--------------------
 
 For advanced [QubesBuilder](/doc/qubes-builder/) use, and preparing sources, take a look at [QubesBuilderDetails](/doc/qubes-builder-details/) page, or [QubesBuilder's doc directory](https://github.com/marmarek/qubes-builder/tree/master/doc).

developer/building/qubes-iso-building.md

@@ -68,7 +68,6 @@ git tag -v `git describe`
 Assuming the verification went fine, we're good to go with all the rest without ever thinking more about verifying digital signatures on all the rest of the components, apart from an additional step if doing a non-scripted build.
 The builder will do that for us for each component, every time we build, even for all auxiliary files (e.g. Xen or Linux kernel sources).
 
-
 Build using setup script
 -----------------
 
@@ -128,7 +127,6 @@ make iso
 
 Enjoy your new ISO!
 
-
 Build using manual steps
 -----------------
 

developer/code/code-signing.md

@@ -4,14 +4,11 @@ title: Code Signing
 permalink: /doc/code-signing/
 ---
 
-Code Signing
+# Code Signing
-============
 
 All contributions to the Qubes OS [source code] must be cryptographically signed by the author's PGP key.
 
-
+## Generating a Key
-Generating a Key
-----------------
 
 (Note: If you already have a PGP key, you may skip this step.)
 
@@ -78,8 +75,7 @@ uid                  Bilbo Baggins <bilbo@shire.org>
 sub   4096R/69B0EA85 2013-03-13
 ~~~
 
-Upload the Key
+## Upload the Key
---------------
 
 For others to find the public key, please upload it to a server.
 
@@ -88,8 +84,7 @@ $ gpg --send-keys --keyserver pool.sks-keyservers.net 69B0EA85
 gpg: sending key 488BA441 to hkp server pool.sks-keyservers.net
 ```
 
-Using PGP with Git
+## Using PGP with Git
-------------------
 
 If you're submitting a patch via GitHub (or a similar Git server), please sign
 your Git commits.
@@ -141,8 +136,7 @@ your Git commits.
    vtag = !git tag -v `git describe`
    ~~~
 
-GitHub Signature Verification (optional)
+## GitHub Signature Verification (optional)
-----------------------------------------
 
 GitHub shows a green `Verified` label indicating that the GPG signature could be
 verified using any of the contributor’s GPG keys uploaded to GitHub. You can
@@ -150,8 +144,7 @@ upload your public key on GitHub by adding your public GPG key on the [New GPG
 key][GitHub New GPG key] under the [SSH GPG keys page][GitHub SSH GPG keys
 page].
 
-Code Signature Checks
+## Code Signature Checks
----------------------
 
 The [signature-checker] checks if code contributions are signed.
 Although GitHub adds a little green `Verified` button next to the commit, the [signature-checker] uses this algorithm to check if a commit is correctly signed:
@@ -171,21 +164,27 @@ In this case, you have several options to sign the commit:
 
 1. Amend the commit and replace it with a signed commit.
    You can use this command to create a new signed commit:
+
    ```
    git commit --amend -S
    ```
+
    This also rewrites the commit so you need to push it forcefully:
+
    ```
    git push -f
    ```
+
 2. Create a signed tag for the unsigned commit.
    If the commit is back in history and you do not want to change it,
    you can create a signed tag for this commit and push the signature.
    You can use the alias from above:
+
    ```
    git checkout <commit>
    git spush
    ```
+
    Now, the signature checker needs to re-check the signature.
    Please comment on the pull request that you would like to have the signatures checked again.
 
@@ -198,15 +197,12 @@ but is not able to verify it using the any key available.
 This might be that you forgot to upload the key to a key server.
 Please upload it.
 
-
+## Using PGP with Email
-Using PGP with Email
---------------------
 
 If you're submitting a patch by emailing the [developer mailing list], simply sign your email with your PGP key.
 One good way to do this is with a program like [Enigmail].
 Enigmail is a security addon for the Mozilla Thunderbird email client that allows you to easily digitally encrypt and sign your emails.
 
-
 [guide]: https://alexcabal.com/creating-the-perfect-gpg-keypair/
 [source code]: /doc/source-code/
 [developer mailing list]: /support/#qubes-devel
@@ -214,4 +210,3 @@ Enigmail is a security addon for the Mozilla Thunderbird email client that allow
 [signature-checker]: https://github.com/marmarek/signature-checker
 [GitHub New GPG key]: https://github.com/settings/gpg/new
 [GitHub SSH GPG keys page]: https://github.com/settings/keys
-

developer/code/coding-style.md

@@ -17,10 +17,10 @@ Rationale
 
 Maintaining proper coding style is very important for any large software project, such as Qubes. Here's why:
 
--   It eases maintenance tasks, such as adding new functionality or generalizing code later,
+- It eases maintenance tasks, such as adding new functionality or generalizing code later,
--   It allows others (as well as the future you!) to easily understand fragments of code and what they were supposed to do, and thus makes it easier to later extend them with newer functionality or bug fixes,
+- It allows others (as well as the future you!) to easily understand fragments of code and what they were supposed to do, and thus makes it easier to later extend them with newer functionality or bug fixes,
--   It allows others to easily review the code and catch various bugs,
+- It allows others to easily review the code and catch various bugs,
--   It provides for an aesthetically pleasing experience when one reads the code...
+- It provides for an aesthetically pleasing experience when one reads the code...
 
 Often, developers, usually smart ones, undersell the value of proper coding style, thinking that it's much more important how their code works. These developers expect that if their code solves some problem using a nice and neat trick, then that's all that is really required. Such thinking shows, however, immaturity and is a signal that the developer, no matter how bright and smart, might not be a good fit for larger projects. Writing a clever exploit for a Black Hat show is one thing - writing useful software supposed to be used and maintained for years is quite a different story. If you want to show off what a smart programmer you are, then you should become a researcher and write exploits. If, on the other hand, you want to be part of a team that makes real, useful software, you should ensure your coding style is impeccable. At Qubes project, we often took shortcuts and wrote nasty code, and this has always back fired at us, sometime months, sometime years later, the net result being we had to spend time fixing code, rather than implementing new functionality.
 
@@ -29,25 +29,25 @@ And here's a [link to the real case](https://groups.google.com/forum/#!msg/qubes
 General typographic conventions
 -------------------------------
 
--   **Use space-expanded tabs that equal 4 spaces.** Yes, we know, there are many arguments for using "real" tabs instead of space-expanded tabs, but we need to pick one convention to make the project consistent. One argument for using space-expanded tabs is that this way the programmer is in control of how the code will look like, despite how other users have configured their editors to visualize the tabs (of course, we assume any sane person uses a fixed-width font for viewing the source code). If it makes you feel any better, assume this is just an arbitrary choice made to enforce a unified style.
+- **Use space-expanded tabs that equal 4 spaces.** Yes, we know, there are many arguments for using "real" tabs instead of space-expanded tabs, but we need to pick one convention to make the project consistent. One argument for using space-expanded tabs is that this way the programmer is in control of how the code will look like, despite how other users have configured their editors to visualize the tabs (of course, we assume any sane person uses a fixed-width font for viewing the source code). If it makes you feel any better, assume this is just an arbitrary choice made to enforce a unified style.
 
--   **Maintain max. line length of 80 characters**. Even though today's monitors often are very wide and it's often not a problem to have 120 characters displayed in an editor, maintaining shorter line lengths improves readability. It also allows others to have two parallel windows open, side by side, each with different parts of the source code.
+- **Maintain max. line length of 80 characters**. Even though today's monitors often are very wide and it's often not a problem to have 120 characters displayed in an editor, maintaining shorter line lengths improves readability. It also allows others to have two parallel windows open, side by side, each with different parts of the source code.
 
--   **Naming conventions for any OS *other than Windows***:
+- **Naming conventions for any OS *other than Windows***:
-    -   `ClassName`
+  - `ClassName`
-    -   `some_variable`, `some_function`, `some_argument`
+  - `some_variable`, `some_function`, `some_argument`
 
--   **Naming convention *for Windows OS*** -- exceptionally to preserve Windows conventions please use the following:
+- **Naming convention *for Windows OS*** -- exceptionally to preserve Windows conventions please use the following:
-    -   `ClassName`, `FunctionName`
+  - `ClassName`, `FunctionName`
-    -   `pszArgumentOne`, `hPipe` -- use Hungarian notation for argument and variables
+  - `pszArgumentOne`, `hPipe` -- use Hungarian notation for argument and variables
 
--   **Maintain a decent amount of horizontal spacing**, e.g. add a space after `if` or before `{` in C, and similar in other languages. Whether and where to also use spaces within expressions, such as (x\*2+5) vs. (x \* 2 + 5) is left to the developer's judgment. Do not put spaces immediately after or before the brackets in expressions, so avoid constructs like this: `if ( condition )` and use ones like this: `if (condition)` instead.
+- **Maintain a decent amount of horizontal spacing**, e.g. add a space after `if` or before `{` in C, and similar in other languages. Whether and where to also use spaces within expressions, such as (x\*2+5) vs. (x \* 2 + 5) is left to the developer's judgment. Do not put spaces immediately after or before the brackets in expressions, so avoid constructs like this: `if ( condition )` and use ones like this: `if (condition)` instead.
 
--   **Use single new lines** ('\\n' aka LF) in any non-Windows source code. On Windows, exceptionally, use the CRLF line endings (--). This will allow the source code to be easily viewable in various Windows-based programs.
+- **Use single new lines** ('\\n' aka LF) in any non-Windows source code. On Windows, exceptionally, use the CRLF line endings (--). This will allow the source code to be easily viewable in various Windows-based programs.
 
--   **Use descriptive names for variables and functions**! Really, at a time when most editors have auto-completion features, there is no excuse for using short variable names.
+- **Use descriptive names for variables and functions**! Really, at a time when most editors have auto-completion features, there is no excuse for using short variable names.
 
--   **Comments should be indented together with the code**, e.g. like this:
+- **Comments should be indented together with the code**, e.g. like this:
 
     ~~~
     for (...) {
@@ -61,33 +61,33 @@ General typographic conventions
 File naming conventions
 -----------------------
 
--   All file names written with small letters, use dash to separate words, rather than underscores, e.g. `qubes-dom0-update`. Never use spaces!
+- All file names written with small letters, use dash to separate words, rather than underscores, e.g. `qubes-dom0-update`. Never use spaces!
 
 **File naming in Linux/Unix-like systems:**
 
--   User commands that operate on particular VMs (also those accessible in VMs): `/usr/bin/qvm-*`
+- User commands that operate on particular VMs (also those accessible in VMs): `/usr/bin/qvm-*`
--   User commands that apply to the whole system (Dom0 only): `/usr/bin/qubes-*`
+- User commands that apply to the whole system (Dom0 only): `/usr/bin/qubes-*`
--   Auxiliary executables and scripts in `/usr/libexec/qubes/` (Note: previously we used `/usr/lib/qubes` but decided to change that)
+- Auxiliary executables and scripts in `/usr/libexec/qubes/` (Note: previously we used `/usr/lib/qubes` but decided to change that)
--   Helper, non-executable files in `/usr/share/qubes/`
+- Helper, non-executable files in `/usr/share/qubes/`
--   Various config files in `/etc/qubes`
+- Various config files in `/etc/qubes`
--   Qubes RPC services in `/etc/qubes-rpc`. Qubes RPC Policy definitions (only in Dom0) in `/etc/qubes-rpc/policy/`
+- Qubes RPC services in `/etc/qubes-rpc`. Qubes RPC Policy definitions (only in Dom0) in `/etc/qubes-rpc/policy/`
--   All VM-related configs, images, and other files in `/var/lib/qubes/`
+- All VM-related configs, images, and other files in `/var/lib/qubes/`
--   System-wide temporary files which reflect the current state of system in `/var/run/qubes`
+- System-wide temporary files which reflect the current state of system in `/var/run/qubes`
--   Logs: either log to the system-wide messages, or to `/var/log/qubes/`
+- Logs: either log to the system-wide messages, or to `/var/log/qubes/`
 
 **File naming in Windows systems:**
 
--   All base qubes-related files in `C:\Program Files\Invisible Things Lab\Qubes\` (Exceptionally spaces are allowed here to adhere to Windows naming conventions)
+- All base qubes-related files in `C:\Program Files\Invisible Things Lab\Qubes\` (Exceptionally spaces are allowed here to adhere to Windows naming conventions)
--   Other, third-party files, not Qubes-specific, such as e.g. Xen PV drivers might be in different vendor subdirs, e.g. `C:\Program Files\Xen PV Drivers`
+- Other, third-party files, not Qubes-specific, such as e.g. Xen PV drivers might be in different vendor subdirs, e.g. `C:\Program Files\Xen PV Drivers`
 
 General programming style guidelines
 ------------------------------------
 
--   Do not try to impress with your coding kung-fu, do not use tricks to save 2 lines of code, always prefer readability over trickiness!
+- Do not try to impress with your coding kung-fu, do not use tricks to save 2 lines of code, always prefer readability over trickiness!
--   Make sure your code compiles and builds without warnings.
+- Make sure your code compiles and builds without warnings.
--   Always think first about interfaces (e.g. function arguments, or class methods) and data structures before you start writing the actual code.
+- Always think first about interfaces (e.g. function arguments, or class methods) and data structures before you start writing the actual code.
--   Use comments to explain non-trivial code fragments, or expected behavior of more complex functions, if it is not clear from their name.
+- Use comments to explain non-trivial code fragments, or expected behavior of more complex functions, if it is not clear from their name.
--   Do **not** use comments for code fragments where it is immediately clear what the code does. E.g. avoid constructs like this:
+- Do **not** use comments for code fragments where it is immediately clear what the code does. E.g. avoid constructs like this:
 
     ~~~
     // Return window id
@@ -97,7 +97,7 @@ General programming style guidelines
     }
     ~~~
 
--   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.:
+- 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
@@ -117,42 +117,42 @@ General programming style guidelines
 
 > But generally, there is little excuse to keep old, unused code fragments in the code. One should really use the functionality provided by the source code management system, such as git, instead. E.g. create a special branch for storing the old, unused code -- this way you will always be able to merge this code into upstream in the future.
 
--   Do not hardcode values in the code! The only three numbers that are an exception here and for which it is acceptable to hardcode them are: `0`, `1` and `-1`, and frankly the last two are still controversial...
+- Do not hardcode values in the code! The only three numbers that are an exception here and for which it is acceptable to hardcode them are: `0`, `1` and `-1`, and frankly the last two are still controversial...
 
 Source Code management (Git) guidelines
 ---------------------------------------
 
--   Use git to maintain all code for Qubes project.
+- Use git to maintain all code for Qubes project.
 
--   Before you start using git, make sure you understand that git is a decentralized Source Code Management system, and that it doesn't behave like traditional, centralized source code management systems, such as SVN. Here's a good [introductory book on git](https://git-scm.com/book). Read it.
+- Before you start using git, make sure you understand that git is a decentralized Source Code Management system, and that it doesn't behave like traditional, centralized source code management systems, such as SVN. Here's a good [introductory book on git](http://git-scm.com/book). Read it.
 
--   Qubes code is divided into many git repositories. There are several reasons for that:
+- Qubes code is divided into many git repositories. There are several reasons for that:
-    -   This creates natural boundaries between different code blocks, enforcing proper interfaces, and easing independent development to be conducted on various code parts at the same time, without the fear of running into conflicts.
+  - 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.
+  - 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.
+  - 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 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).
+  - 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
 -------------------------
 
 Please attempt to follow these conventions when writing your Git commit messages:
 
- * Separate the subject line from the body with a blank line.
+- Separate the subject line from the body with a blank line.
- * Limit the subject line to approximately 50 characters.
+- Limit the subject line to approximately 50 characters.
- * Capitalize the subject line.
+- Capitalize the subject line.
- * Do not end the subject line with a period.
+- Do not end the subject line with a period.
- * Use the imperative mood in the subject line.
+- Use the imperative mood in the subject line.
- * Wrap the body at 72 characters.
+- Wrap the body at 72 characters.
- * Use the body to explain *what* and *why* rather than *how*.
+- Use the body to explain *what* and *why* rather than *how*.
 
 For details, examples, and the rationale behind each of these conventions, please see [this blog post](https://chris.beams.io/posts/git-commit/), which is the source of this list.
 
 Security coding guidelines
 --------------------------
 
--   As a general rule: **untrusted input** is our \#1 enemy!
+- As a general rule: **untrusted input** is our \#1 enemy!
--   Any input that comes from untrusted, or less trusted, or just differently-trusted, entity should always be considered as malicious and should always be sanitized and verified. So, if your software runs in Dom0 and processes some input from any of the VMs, this input should be considered to be malicious. Even if your software runs in a VM, and processes input from some other VM, you should also assume that the input is malicious and verify it.
+- Any input that comes from untrusted, or less trusted, or just differently-trusted, entity should always be considered as malicious and should always be sanitized and verified. So, if your software runs in Dom0 and processes some input from any of the VMs, this input should be considered to be malicious. Even if your software runs in a VM, and processes input from some other VM, you should also assume that the input is malicious and verify it.
--   Use `untrusted_` prefix for all variables that hold values read from untrusted party and which have not yet been verified to be decent, e.g.:
+- Use `untrusted_` prefix for all variables that hold values read from untrusted party and which have not yet been verified to be decent, e.g.:
 
     ~~~
        read_struct(untrusted_conf);
@@ -165,22 +165,22 @@ Security coding guidelines
        height = untrusted_conf.height;
     ~~~
 
--   Use others 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
 --------------------------
 
--   Please follow the guidelines [here](http://www.python.org/dev/peps/pep-0008/), unless they were in conflict with what is written on this page.
+- Please follow the guidelines [here](http://www.python.org/dev/peps/pep-0008/), unless they were in conflict with what is written on this page.
 
 C and C++ specific guidelines
 -----------------------------
 
--   Do not place code in `*.h` files.
+- Do not place code in `*.h` files.
--   Use `const` whenever possible, e.g. in function arguments passed via pointers.
+- 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.
+- Do not mix procedural and objective code together -- if you write in C++, use classes and objects.
--   Think about classes hierarchy, before starting to implement specific methods.
+- Think about classes hierarchy, before starting to implement specific methods.
 
 Bash-specific guidelines
 ------------------------
 
--   Avoid writing scripts in bash whenever possible. Use python instead. Bash-scripts are Unix-specific and will not work under Windows VMs, or in Windows admin domain, or Windows gui domain.
+- Avoid writing scripts in bash whenever possible. Use python instead. Bash-scripts are Unix-specific and will not work under Windows VMs, or in Windows admin domain, or Windows gui domain.

developer/code/source-code.md

@@ -14,11 +14,11 @@ Qubes Source Code Repositories
 All the Qubes code is kept in Git repositories. We have divided the project into
 several components, each of which has its own separate repository, for example:
 
- * `core-admin.git` -- The core Qubes infrastructure, responsible for VM
+* `core-admin.git` -- The core Qubes infrastructure, responsible for VM
    management, VM templates, fs sharing, etc.
- * `gui-daemon.git` -- GUI virtualization, Dom0 side.
+* `gui-daemon.git` -- GUI virtualization, Dom0 side.
- * `gui-agent-linux.git` -- GUI virtualization, Linux VM side.
+* `gui-agent-linux.git` -- GUI virtualization, Linux VM side.
- * `linux-template-builder.git` -- Scripts and other files used to create Qubes
+* `linux-template-builder.git` -- Scripts and other files used to create Qubes
    template images.
 
 All of our repositories are available under the [QubesOS GitHub account].
@@ -53,21 +53,20 @@ find . -mindepth 1 -maxdepth 1 -type d -exec git -C {} fetch --tags --recurse-su
 
 (Alternatively, you can pull instead of just fetching.)
 
-
 How to Send Patches
 -------------------
 
 If you want to [contribute code] to the project, there are two ways. Whichever
 method you choose, you must [sign your code] before it can be accepted.
 
-*  **Preferred**: Use GitHub's [fork & pull requests].
+* **Preferred**: Use GitHub's [fork & pull requests].
 
    Opening a pull request on GitHub greatly eases the code review and tracking
    process. In addition, especially for bigger changes, it's a good idea to send
    a message to the [qubes-devel mailing list] in order to notify people who
    do not receive GitHub notifications.
 
-*  Send a patch to the [qubes-devel mailing list] (`git format-patch`).
+* Send a patch to the [qubes-devel mailing list] (`git format-patch`).
 
    1. Make all the changes in your working directory, i.e. edit files, move them
       around (you can use 'git mv' for this), etc.

developer/debugging/automated-tests.md

@@ -7,11 +7,9 @@ redirect_from:
 - /doc/AutomatedTests/
 ---
 
-Automated Tests
+# Automated Tests
-===============
 
-Unit and Integration 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).
@@ -46,6 +44,7 @@ Our test runner runs mostly the same as the standard one, but it has some nice a
 
 You can use `python3 -m qubes.tests.run -h` to get usage information:
 
+```
     [user@dom0 ~]$ python3 -m qubes.tests.run -h
     usage: run.py [-h] [--verbose] [--quiet] [--list] [--failfast] [--no-failfast]
                   [--do-not-clean] [--do-clean] [--loglevel LEVEL]
@@ -83,9 +82,11 @@ You can use `python3 -m qubes.tests.run -h` to get usage information:
     When running only specific tests, write their names like in log, in format:
     MODULE+"/"+CLASS+"/"+FUNCTION. MODULE should omit initial "qubes.tests.".
     Example: basic/TC_00_Basic/test_000_create
+```
 
 For instance, to run only the tests for the fedora-21 template, you can use the `-l` option, then filter the list:
 
+```
     [user@dom0 ~]$ python3 -m qubes.tests.run -l | grep fedora-21
     network/VmNetworking_fedora-21/test_000_simple_networking
     network/VmNetworking_fedora-21/test_010_simple_proxyvm
@@ -108,6 +109,7 @@ For instance, to run only the tests for the fedora-21 template, you can use the
     vm_qrexec_gui/TC_20_DispVM_fedora-21/test_020_gui_app
     vm_qrexec_gui/TC_20_DispVM_fedora-21/test_030_edit_file
     [user@dom0 ~]$ sudo -E python3 -m qubes.tests.run -v `python3 -m qubes.tests.run -l | grep fedora-21`
+```
 
 Example test run:
 
@@ -115,11 +117,12 @@ Example test run:
 
 Tests are also compatible with nose2 test runner, so you can use this instead:
 
+```bash
     sudo systemctl stop qubesd; sudo -E nose2 -v --plugin nose2.plugins.loader.loadtests qubes.tests; sudo systemctl start qubesd
+```
 
 This may be especially useful together with various nose2 plugins to store tests results (for example `nose2.plugins.junitxml`), to ease presenting results. This is what we use on [OpenQA].
 
-
 ### Unit testing inside a VM
 
 Many unit tests will also work inside a VM. However all of the tests requiring a dedicated VM to be run (mostly the integration tests) will be skipped.
@@ -132,6 +135,7 @@ its dependency [qubes-core-qrexec](https://github.com/QubesOS/qubes-core-qrexec)
 The below example however will assume that you set up a build environment as described in the [Qubes Builder documentation](/doc/qubes-builder/).
 
 Assuming you cloned the `qubes-builder` repository to your home directory inside a fedora VM, you can use the following commands to run the unit tests:
+
 ```{.bash}
 cd ~
 sudo dnf install python3-pip lvm2 python35 python3-virtualenv
@@ -158,16 +162,17 @@ the current stable branch.
 
 Test runs can be altered using environment variables:
 
- - `DEFAULT_LVM_POOL` - LVM thin pool to use for tests, in `VolumeGroup/ThinPool` format
+- `DEFAULT_LVM_POOL` - LVM thin pool to use for tests, in `VolumeGroup/ThinPool` format
- - `QUBES_TEST_PCIDEV` - PCI device to be used in PCI passthrough tests (for example sound card)
+- `QUBES_TEST_PCIDEV` - PCI device to be used in PCI passthrough tests (for example sound card)
- - `QUBES_TEST_TEMPLATES` - space separated list of templates to run tests on; if not set, all installed templates are tested
+- `QUBES_TEST_TEMPLATES` - space separated list of templates to run tests on; if not set, all installed templates are tested
- - `QUBES_TEST_LOAD_ALL` - load all tests (including tests for all templates) when relevant test modules are imported; this needs to be set for test runners not supporting [load_tests protocol](https://docs.python.org/3/library/unittest.html#load-tests-protocol)
+- `QUBES_TEST_LOAD_ALL` - load all tests (including tests for all templates) when relevant test modules are imported; this needs to be set for test runners not supporting [load_tests protocol](https://docs.python.org/3/library/unittest.html#load-tests-protocol)
 
 ### Adding a new test to core-admin
+
 After adding a new unit test to [core-admin/qubes/tests](https://github.com/QubesOS/qubes-core-admin/tree/master/qubes/tests) you'll have to include it in [core-admin/qubes/tests/\_\_init\_\_.py](https://github.com/QubesOS/qubes-core-admin/tree/master/qubes/tests/__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`.
 Again, given the hypothetical `example.py` test:
 
@@ -237,11 +242,10 @@ class SomeTestCase(unittest.TestCase):
         gc.collect()
 ~~~
 
-
+## Installation Tests with openQA
-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.
@@ -258,4 +262,3 @@ Thanks to an anonymous donor, our openQA system is hosted in a datacenter on har
 
 [unittest]: https://docs.python.org/3/library/unittest.html
 [OpenQA]: http://open.qa/
-

developer/debugging/mount-lvm-image.md

@@ -26,6 +26,7 @@ From dom0 terminal:
 3: Attach the device to your newly created disp VM
 
 From the GUI, or from the command line:
+
 ```bash
 [user@dom0]$ qvm-block attach NEWLY_CREATED_DISPVM dom0:$dev
 ```
@@ -37,15 +38,19 @@ From the GUI, or from the command line:
 ```
 
 5: Umount and kill the VM
-```
+
+```bash
 [user@dispXXXX]$ umount /mnt/
 ```
 
 6: Remove the image from qubesdb
-```
+
+```bash
 [user@dom0]$ qubesdb-rm /qubes-block-devices/$dev/
 ```
 
 # References
 
-https://github.com/QubesOS/qubes-issues/issues/4687#issuecomment-451626625
+Please consult this issue's [comment].
+
+[comment]: https://github.com/QubesOS/qubes-issues/issues/4687#issuecomment-451626625

developer/debugging/profiling.md

@@ -8,15 +8,13 @@ redirect_from:
 - /wiki/Profiling/
 ---
 
-Profiling
+# Profiling
-=========
 
 This is a python profiling primer.
 
 For the purpose of this document, `qubes-dev` is name of the domain used for postprocessing profiling stats.
 
-Requirements
+## Requirements
-------------
 
 ~~~
 yum install gprof2dot graphviz
@@ -30,10 +28,9 @@ mkdir -p ~/profiling
 qvm-run -p qubes-dev 'cat ~/profiling/Upload.sh' > ~/profiling/Upload.sh
 ~~~
 
--   WARNING: this will obviously be running third-party code which is not signed by ITL nor Fedora. You have been warned.
+- WARNING: this will obviously be running third-party code which is not signed by ITL nor Fedora. You have been warned.
 
-Workflow
+## Workflow
---------
 
 ### Identify function responsible for some slow action
 
@@ -43,17 +40,21 @@ You have to select the area in which you suspect less than optimal performance.
 
 Replace
 
+```python
     def foo(self, bar):
         # function content
+```
 
 with
 
+```python
     def foo(self, *args, **kwargs):
         profile.runctx('self.real_foo(*args, **kwargs)', globals(), locals(),
             time.strftime('/home/user/profiling/foo-%Y%m%d-%H%M%S.pstats'))
 
     def real_foo(self, bar):
         # function content
+```
 
 ### Run application
 
@@ -88,8 +89,7 @@ This creates `index.html` with all SVG graphics linked to TXT files, ready for u
 make REMOTE=example.com:public_html/qubes/profiling/ upload
 ~~~
 
-Example
+## Example
--------
 
 This example is from `qubes-manager` (`qubesmanager/main.py`).
 

developer/debugging/test-bench.md

@@ -8,20 +8,19 @@ redirect_from:
 - /wiki/TestBench/
 ---
 
-Test bench for Dom0
+# Test bench for Dom0
-===================
 
 This guide shows how to set up simple test bench that automatically test your code you're about to push. It is written especially for `core3` branch of `core-admin.git` repo, but some ideas are universal.
 
 We will set up a spare machine (bare metal, not a virtual) that will be hosting our experimental Dom0. We will communicate with it via Ethernet and SSH. This tutorial assumes you are familiar with [QubesBuilder](/doc/qubes-builder/) and you have it set up and running flawlessly.
 
-Setting up the machine
+## Setting up the machine
-----------------------
 
 First, do a clean install from ISO you built or grabbed elsewhere.
 
 You have to fix network, because it is intentionally broken. This script should reenable your network card without depending on anything else.
 
+```bash
     #!/bin/sh
 
     # adjust this for your NIC (run lspci)
@@ -53,6 +52,7 @@ You have to fix network, because it is intentionally broken. This script should
     pcibind ${BDF} e1000e
 
     dhclient
+```
 
 TODO: describe how to run this at every startup
 
@@ -66,8 +66,7 @@ yum install openssh-server
 
 Ensure that sudo works without password from your user account (it should by default).
 
-Development VM
+## Development VM
---------------
 
 ### SSH
 
@@ -95,12 +94,15 @@ This step is optional, but very helpful. Put these scripts somewhere in your `${
 
 `qtb-runtests`:
 
+```bash
     #!/bin/sh
 
     ssh testbench python -m qubes.tests.run
+```
 
 `qtb-install`:
 
+```bash
     #!/bin/sh
 
     TMPDIR=/tmp/qtb-rpms
@@ -119,9 +121,11 @@ This step is optional, but very helpful. Put these scripts somewhere in your `${
             ssh testbench sudo rpm -i --replacepkgs --replacefiles "${TMPDIR}/$(basename ${1})"
             shift
     done
+```
 
 `qtb-iterate`:
 
+```bash
     #!/bin/sh
 
     set -e
@@ -136,6 +140,7 @@ This step is optional, but very helpful. Put these scripts somewhere in your `${
     make core-admin
     qtb-install qubes-src/core-admin/rpm/x86_64/qubes-core-dom0-*.rpm
     qtb-runtests
+```
 
 ### Hooking git
 
@@ -143,14 +148,18 @@ I (woju) have those two git hooks. They ensure tests are passing (or are marked
 
 `core-admin/.git/hooks/pre-commit`: (you may retain also the default hook, here omitted for readability)
 
+```bash
     #!/bin/sh
 
     set -e
 
     python -c "import sys, qubes.tests.run; sys.exit(not qubes.tests.run.main())"
+```
 
 `core-admin/.git/hooks/pre-push`:
 
+```bash
     #!/bin/sh
 
     exec qtb-iterate
+```

developer/debugging/vm-interface.md

@@ -9,45 +9,43 @@ redirect_from:
 - /wiki/SystemDoc/VMInterface/
 ---
 
-VM Configuration Interface
+# VM Configuration Interface
-==========================
 
 Qubes VM have some settings set by dom0 based on VM settings. There are multiple configuration channels, which includes:
 
--   QubesDB
+- QubesDB
--   XenStore (in Qubes 2, data the same as in QubesDB, keys without leading `/`)
+- XenStore (in Qubes 2, data the same as in QubesDB, keys without leading `/`)
--   Qubes RPC (called at VM startup, or when configuration changed)
+- Qubes RPC (called at VM startup, or when configuration changed)
--   GUI protocol
+- GUI protocol
 
-QubesDB
+## QubesDB
---------------------
 
-### Keys exposed by dom0 to VM ###
+### Keys exposed by dom0 to VM
 
--   `/qubes-vm-type` - VM type, the same as `type` field in `qvm-prefs`. One of `AppVM`, `ProxyVM`, `NetVM`, `TemplateVM`, `HVM`, `TemplateHVM`
+- `/qubes-vm-type` - VM type, the same as `type` field in `qvm-prefs`. One of `AppVM`, `ProxyVM`, `NetVM`, `TemplateVM`, `HVM`, `TemplateHVM`
--   `/qubes-vm-updatable` - flag whether VM is updatable (whether changes in root.img will survive VM restart). One of `True`, `False`
+- `/qubes-vm-updatable` - flag whether VM is updatable (whether changes in root.img will survive VM restart). One of `True`, `False`
--   `/qubes-vm-persistence` - what data do persist between VM restarts:
+- `/qubes-vm-persistence` - what data do persist between VM restarts:
-     - `full` - all disks
+  - `full` - all disks
-     - `rw-only` - only `/rw` disk
+  - `rw-only` - only `/rw` disk
-     - `none` - none
+  - `none` - none
--   `/qubes-timezone - name of timezone based on dom0 timezone. For example `Europe/Warsaw`
+- `/qubes-timezone - name of timezone based on dom0 timezone. For example `Europe/Warsaw`
--   `/qubes-keyboard` (deprecated in R4.1) - keyboard layout based on dom0 layout. Its syntax is suitable for `xkbcomp` command (after expanding escape sequences like `\n` or `\t`). This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). This entry is created as part of gui-daemon initialization (so not available when gui-daemon disabled, or not started yet).
+- `/qubes-keyboard` (deprecated in R4.1) - keyboard layout based on dom0 layout. Its syntax is suitable for `xkbcomp` command (after expanding escape sequences like `\n` or `\t`). This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). This entry is created as part of gui-daemon initialization (so not available when gui-daemon disabled, or not started yet).
--   `/keyboard-layout` - keyboard layout based on GuiVM layout. Its syntax can be `layout+variant+options`, `layout+variant`, `layout++options` or simply `layout`. For example, `fr+oss`, `pl++compose:caps` or `fr`. This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does).
+- `/keyboard-layout` - keyboard layout based on GuiVM layout. Its syntax can be `layout+variant+options`, `layout+variant`, `layout++options` or simply `layout`. For example, `fr+oss`, `pl++compose:caps` or `fr`. This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does).
--   `/qubes-debug-mode` - flag whether VM has debug mode enabled (qvm-prefs setting). One of `1`, `0`
+- `/qubes-debug-mode` - flag whether VM has debug mode enabled (qvm-prefs setting). One of `1`, `0`
--   `/qubes-service/SERVICE_NAME` - subtree for VM services controlled from dom0 (using the `qvm-service` command or Qubes Manager). One of `1`, `0`. Note that not every service will be listed here, if entry is missing, it means "use VM default". A list of currently supported services is in the `qvm-service` man page.
+- `/qubes-service/SERVICE_NAME` - subtree for VM services controlled from dom0 (using the `qvm-service` command or Qubes Manager). One of `1`, `0`. Note that not every service will be listed here, if entry is missing, it means "use VM default". A list of currently supported services is in the `qvm-service` man page.
--   `/qubes-netmask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0"
+- `/qubes-netmask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0"
--   `/qubes-ip - IP address for this VM (only when VM has netvm set)
+- `/qubes-ip - IP address for this VM (only when VM has netvm set)
--   `/qubes-gateway` - default gateway IP (only when VM has netvm set); VM should add host route to this address directly via eth0 (or whatever default interface name is)
+- `/qubes-gateway` - default gateway IP (only when VM has netvm set); VM should add host route to this address directly via eth0 (or whatever default interface name is)
--   `/qubes-primary-dns` - primary DNS address (only when VM has netvm set)
+- `/qubes-primary-dns` - primary DNS address (only when VM has netvm set)
--   `/qubes-secondary-dns` - secondary DNS address (only when VM has netvm set)
+- `/qubes-secondary-dns` - secondary DNS address (only when VM has netvm set)
--   `/qubes-netvm-gateway` - same as `qubes-gateway` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM)
+- `/qubes-netvm-gateway` - same as `qubes-gateway` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM)
--   `/qubes-netvm-netmask` - same as `qubes-netmask` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM)
+- `/qubes-netvm-netmask` - same as `qubes-netmask` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM)
--   `/qubes-netvm-network` - network address (only when VM serves as network backend - ProxyVM and NetVM); can be also calculated from qubes-netvm-gateway and qubes-netvm-netmask
+- `/qubes-netvm-network` - network address (only when VM serves as network backend - ProxyVM and NetVM); can be also calculated from qubes-netvm-gateway and qubes-netvm-netmask
--   `/qubes-netvm-primary-dns` - same as `qubes-primary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to primary DNS server
+- `/qubes-netvm-primary-dns` - same as `qubes-primary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to primary DNS server
--   `/qubes-netvm-secondary-dns` - same as `qubes-secondary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to secondary DNS server
+- `/qubes-netvm-secondary-dns` - same as `qubes-secondary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to secondary DNS server
--   `/guivm-windows-prefix` - title prefix for any window not originating from another qube. This means windows of applications running in GuiVM itself
+- `/guivm-windows-prefix` - title prefix for any window not originating from another qube. This means windows of applications running in GuiVM itself
 
-#### Firewall rules in 3.x ####
+#### Firewall rules in 3.x
 
 QubesDB is also used to configure firewall in ProxyVMs. Rules are stored in
 separate key for each target VM. Entries:
@@ -63,7 +61,7 @@ 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 problems - like a popup.
 
-#### Firewall rules in 4.x ####
+#### Firewall rules in 4.x
 
 QubesDB is also used to configure firewall in ProxyVMs. Each rule is stored as
 a separate entry, grouped on target VM:
@@ -85,19 +83,19 @@ Each rule is a single QubesDB entry, consisting of pairs `key=value` separated
 by space. QubesDB enforces limit on a single entry length - 3072 bytes.
 Possible options for a single rule:
 
- - `action`, values: `accept`, `drop`; this is present in 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`
+- `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`
+- `dst6`, value: destination IPv6 address with a mask; for example: `2000::/3`
- - `dsthost`, value: DNS hostname of destination host
+- `dsthost`, value: DNS hostname of destination host
- - `proto`, values: `tcp`, `udp`, `icmp`
+- `proto`, values: `tcp`, `udp`, `icmp`
- - `specialtarget`, value: One of predefined target, currently defined values:
+- `specialtarget`, value: One of predefined target, currently defined values:
-   - `dns` - such option should match DNS traffic to default DNS server (but
+  - `dns` - such option should match DNS traffic to default DNS server (but
       not any DNS server), on both TCP and UDP
- - `dstports`, value: destination ports range separated with `-`, valid only
+- `dstports`, value: destination ports range separated with `-`, valid only
  together with `proto=tcp` or `proto=udp`; for example `1-1024`, `80-80`
- - `icmptype`, value: numeric (decimal) icmp message type, for example `8` for
+- `icmptype`, value: numeric (decimal) icmp message type, for example `8` for
  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
+- `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.
@@ -117,48 +115,46 @@ Example valid rules:
 - `action=drop proto=tcp specialtarget=dns` - drop DNS queries sent using TCP
 - `action=drop`
 
-### Keys set by VM for passing info to dom0 ###
+### Keys set by VM for passing info to dom0
 
--   `memory/meminfo` (**xenstore**) - used memory (updated by qubes-meminfo-writer), input information for qmemman;
+- `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 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 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 these 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)
+  - `desc` - device description (ASCII text)
-    -   `size` - device size in bytes
+  - `size` - device size in bytes
-    -   `mode` - default connection mode; `r` for read-only, `w` for read-write
+  - `mode` - default connection mode; `r` for read-only, `w` for read-write
--   `/qubes-usb-devices` - list of USB devices exposed by this VM, each device (subdirectory) should contain:
+- `/qubes-usb-devices` - list of USB devices exposed by this VM, each device (subdirectory) should contain:
-    -   `desc` - device description (ASCII text)
+  - `desc` - device description (ASCII text)
-    -   `usb-ver` - USB version (1, 2 or 3)
+  - `usb-ver` - USB version (1, 2 or 3)
 
-Qubes RPC
+## Qubes RPC
----------
 
 Services called by dom0 to provide some VM configuration:
 
--   `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.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.WaitForSession` - called to wait for full VM startup
--   `qubes.GetAppmenus` - receive appmenus from given VM (template); TODO: describe format here
+- `qubes.GetAppmenus` - receive appmenus from given VM (template); TODO: describe format here
--   `qubes.GetImageRGBA` - receive image/application icon. Protocol:
+- `qubes.GetImageRGBA` - receive image/application icon. Protocol:
 
-     1. Caller sends name of requested icon. This can be one of:
+  1. Caller sends name of requested icon. This can be one of:
-         * `xdgicon:NAME` - search for NAME in standard icons theme
+    * `xdgicon:NAME` - search for NAME in standard icons theme
-         * `-` - get icon data from stdin (the caller), can be prefixed with format name, for example `png:-`
+    * `-` - get icon data from stdin (the caller), can be prefixed with format name, for example `png:-`
-         * file name
+    * file name
-     2. The service responds with image dimensions: width and height as
+  2. The service responds with image dimensions: width and height as
      decimal numbers, separated with space and with EOL marker at the and; then
      image data in RGBA format (32 bits per pixel)
--   `qubes.SetDateTime` - set VM time, called periodically by dom0 (can be
+- `qubes.SetDateTime` - set VM time, called periodically by dom0 (can be
     triggered manually from dom0 by calling `qvm-sync-clock`). The service
     receives one line at stdin - time in format of `date -u -Iseconds`, for
     example `2015-07-31T16:10:43+0000`.
--   `qubes.SetGuiMode` - called in HVM to switch between fullscreen and seamless
+- `qubes.SetGuiMode` - called in HVM to switch between fullscreen and seamless
     GUI mode. The service receives a single word on stdin - either `FULLSCREEN`
     or `SEAMLESS`
--   `qubes.ResizeDisk` - called to inform that underlying disk was resized.
+- `qubes.ResizeDisk` - called to inform that underlying disk was resized.
     Name of disk image is passed on standard input (`root`, `private`, `volatile`,
     or other). This is used starting with Qubes 4.0.
 
-
 Other Qrexec services installed by default:
 
 - `qubes.Backup` - store Qubes backup. The service receives location chosen by
@@ -193,15 +189,15 @@ Other Qrexec services installed by default:
   can send icon for the same window multiple times to replace previous one (for
   example for animated icons)
 - `qubes.VMShell` - call any command in the VM; the command(s) is passed one per line
-    - `qubes.VMShell+WaitForSession` waits for full VM startup first
+  - `qubes.VMShell+WaitForSession` waits for full VM startup first
 - `qubes.VMExec` - call any command in the VM, without using shell, the command
   needs to be passed as argument and encoded as follows:
-    - the executable name and arguments are separated by `+`
+  - the executable name and arguments are separated by `+`
-    - everything except alphanumeric characters, `.` and `_` needs to be
+  - everything except alphanumeric characters, `.` and `_` needs to be
       escaped
-    - bytes are escaped as `-HH` (where `HH` is hex code, capital letters only)
+  - bytes are escaped as `-HH` (where `HH` is hex code, capital letters only)
-    - `-` itself can be escaped as `--`
+  - `-` itself can be escaped as `--`
-    - example: to run `ls -a /home/user`, use
+  - example: to run `ls -a /home/user`, use
       `qubes.VMExec+ls+--a+-2Fhome-2Fuser`
 - `qubes.VMExecGUI` - a variant of `qubes.VMExec` that waits for full VM
   startup first
@@ -224,7 +220,6 @@ abstraction. This will change in the future. Those tools are:
 
 Additionally, automatic tests extensively run various commands directly in VMs. We do not plan to change that.
 
-GUI protocol
+## GUI protocol
-------------
 
 GUI initialization includes passing the whole screen dimensions from dom0 to VM. This will most likely be overwritten by qubes.SetMonitorLayout Qubes RPC call.

developer/debugging/windows-debugging.md

@@ -8,8 +8,7 @@ redirect_from:
 - /wiki/WindowsDebugging/
 ---
 
-Debugging Windows HVMs
+# Debugging Windows HVMs
-======================
 
 Debugging Windows code can be tricky in a virtualized environment. The guide below assumes Xen hypervisor and Windows 7 VMs.
 
@@ -17,22 +16,25 @@ User-mode debugging is usually straightforward if it can be done on one machine.
 
 Things get complicated if you need to perform kernel debugging or troubleshoot problems that only manifest on system boot, user logoff or similar. For that you need two Windows VMs: the *host* and the *target*. The *host* will contain [WinDbg](https://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) installation, your source code and private symbols. The *target* will run the code being debugged. Both will be linked by virtual serial ports.
 
--   First, you need to prepare separate copies of both *target* and *host* VM configuration files with some changes. Copy the files from **/var/lib/qubes/appvms/vmname/vmname.conf** to some convenient location, let's call them **host.conf** and **target.conf**.
+- First, you need to prepare separate copies of both *target* and *host* VM configuration files with some changes. Copy the files from **/var/lib/qubes/appvms/vmname/vmname.conf** to some convenient location, let's call them **host.conf** and **target.conf**.
--   In both copied files add the following line at the end: `serial = 'pty'`. This will make Xen connect VM's serial ports to dom0's ptys.
+- In both copied files add the following line at the end: `serial = 'pty'`. This will make Xen connect VM's serial ports to dom0's ptys.
--   From now on you need to start both VMs like this: `qvm-start --custom-config=/your/edited/host.conf host`
+- From now on you need to start both VMs like this: `qvm-start --custom-config=/your/edited/host.conf host`
--   To connect both VM serial ports together you will either need [socat](http://www.dest-unreach.org/socat/) or a custom utility described later.
+- To connect both VM serial ports together you will either need [socat](http://www.dest-unreach.org/socat/) or a custom utility described later.
--   To determine which dom0 pty corresponds to VM's serial port you need to read xenstore, example script below:
+- To determine which dom0 pty corresponds to VM's serial port you need to read xenstore, example script below:
 
+```bash
         #!/bin/sh
 
         id1=$(xl domid "$1-dm")
         tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty)
         echo $tty1
+```
 
-    Pass it a running VM name and it will output the corresponding pty name.
+Pass it a running VM name and it will output the corresponding pty name.
 
--   To connect both ptys you can use [socat](http://www.dest-unreach.org/socat/) like that:
+- To connect both ptys you can use [socat](http://www.dest-unreach.org/socat/) like that:
 
+```bash
         #!/bin/sh
 
         id1=$(xl domid "$1-dm")
@@ -40,14 +42,15 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
         tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty)
         tty2=$(xenstore-read /local/domain/${id2}/device/console/3/tty)
         socat $tty1,raw $tty2,raw
+```
 
-    ...but there is a catch. Xen seems to process the traffic that goes through serial ports and changes all **0x0a** bytes into **0x0d, 0x0a** pairs (newline conversion). I didn't find a way to turn that off (setting ptys to raw mode didn't change anything) and it's not mentioned anywhere on the Internet, so maybe it's something on my system. If the above script works for you then you don't need anything more in dom0.
+...but there is a catch. Xen seems to process the traffic that goes through serial ports and changes all **0x0a** bytes into **0x0d, 0x0a** pairs (newline conversion). I didn't find a way to turn that off (setting ptys to raw mode didn't change anything) and it's not mentioned anywhere on the Internet, so maybe it's something on my system. If the above script works for you then you don't need anything more in dom0.
 
--   On the *target* system, run `bcdedit /set debug on` on the console to turn on kernel debugging. It defaults to the first serial port.
+- On the *target* system, run `bcdedit /set debug on` on the console to turn on kernel debugging. It defaults to the first serial port.
--   On the *host* system, install [WinDbg](https://msdn.microsoft.com/en-us/library/windows/hardware/ff551063%28v=vs.85%29.aspx) and start the kernel debug (Ctrl-K), choose **com1** as the debug port.
+- On the *host* system, install [WinDbg](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) and start the kernel debug (Ctrl-K), choose **com1** as the debug port.
--   Reboot the *target* VM.
+- Reboot the *target* VM.
--   Run the above shell script in dom0.
+- Run the above shell script in dom0.
--   If everything is fine you should see the proper kernel debugging output in WinDbg. However, if you see something like that:
+- If everything is fine you should see the proper kernel debugging output in WinDbg. However, if you see something like that:
 
     ~~~
     Opened \\.\com1
@@ -73,6 +76,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
 
     ...then you're most likely a victim of the CRLF issue mentioned above. To get around it I wrote a small utility that basically does what socat would do and additionally corrects those replaced bytes in the stream. It's not pretty but it works:
 
+```c
         #include <errno.h>
         #include <stdio.h>
         #include <fcntl.h>
@@ -182,6 +186,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
             close(fd2);
             return 0;
         }
+```
 
 > This utility is a unidirectional relay so you need to run two instances to get duplex communication, like:
 >
@@ -214,7 +219,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
 
 There are two main issues to be adopted to get all things to work in the R4.0.
 
-## Add a virtual serial port ##
+## Add a virtual serial port
 
 Qemu in the stub domain with virtual serial port added in a recommended way (```<serial type="pty"/>```) fails to start (Could not open '/dev/hvc1': No such device). It seems like a lack of multiple xen consoles support/configuration. The only way that I have found is to attach serial port explicitly to the available console.
 
@@ -228,15 +233,17 @@ $ gunzip stubdom-linux-rootfs.gz
 $ cpio -i -d -H newc --no-absolute-filenames < stubdom-linux-rootfs
 $ rm stubdom-linux-rootfs
 ```
+
 2. Edit Init script to remove last loop and to add "-serial /dev/hvc0" to the qemu command line.
 
 3. Apply changes:
+
 ```shell_session
 $ find . -print0 | cpio --null -ov --format=newc | gzip -9 > ../stubdom-linux-rootfs
 $ sudo mv ../stubdom-linux-rootfs /usr/lib/xen/boot
 ```
 
-## Connect two consoles ##
+## Connect two consoles
 
 Run the following script:
 

developer/general/devel-books.md

@@ -11,19 +11,19 @@ redirect_from:
 Below is a list of various books that might be useful in learning some basics needed for Qubes development.
 
 - A must-read about Xen internals:
-  * _[The Definitive Guide to the Xen Hypervisor](https://www.amazon.com/Definitive-Guide-Xen-Hypervisor/dp/013234971X)_, by David Chisnall
+  - _[The Definitive Guide to the Xen Hypervisor](https://www.amazon.com/Definitive-Guide-Xen-Hypervisor/dp/013234971X)_, by David Chisnall
 
 - Some good books about the Linux kernel:
-  * _[Linux Kernel Development](https://www.amazon.com/Linux-Kernel-Development-Robert-Love/dp/0672329468)_, by Robert Love
+  - _[Linux Kernel Development](https://www.amazon.com/Linux-Kernel-Development-Robert-Love/dp/0672329468)_, by Robert Love
-  * _[Linux Device Drivers](https://www.amazon.com/Linux-Device-Drivers-Jonathan-Corbet/dp/0596005903)_, by Jonathan Corbet
+  - _[Linux Device Drivers](https://www.amazon.com/Linux-Device-Drivers-Jonathan-Corbet/dp/0596005903)_, by Jonathan Corbet
 
 - Solid intro into Trusted Computing:
-  * _[Dynamics of a Trusted Platform](https://www.amazon.com/Dynamics-Trusted-Platform-Buildin-Grawrock/dp/1934053082)_, by David Grawrock (original Intel architect for TXT)
+  - _[Dynamics of a Trusted Platform](https://www.amazon.com/Dynamics-Trusted-Platform-Buildin-Grawrock/dp/1934053082)_, by David Grawrock (original Intel architect for TXT)
 
 - Good book about GIT:
-  * _[Pro Git](https://git-scm.com/book/en/v2)_, by Scott Chacon and Ben Straub (complete book available free online)
+  - _[Pro Git](https://git-scm.com/book/en/v2)_, by Scott Chacon and Ben Straub (complete book available free online)
 
 - Useful books about Python:
-  * _[Programming in Python 3](http://www.qtrac.eu/py3book.html)_, by Mark Summerfield
+  - _[Programming in Python 3](http://www.qtrac.eu/py3book.html)_, by Mark Summerfield
-  * _[Rapid GUI Programming with Python and Qt](http://www.qtrac.eu/pyqtbook.html)_, by Mark Summerfield
+  - _[Rapid GUI Programming with Python and Qt](http://www.qtrac.eu/pyqtbook.html)_, by Mark Summerfield
     (Although note that [Qt is being replaced by GTK](/doc/usability-ux/#gnome-kde-and-xfce) in Qubes code.)

developer/general/doc-guidelines.md

@@ -16,7 +16,6 @@ By cloning and regularly pulling from this repo, users can maintain their own up
 The documentation is a community effort. Volunteers work hard trying to keep everything accurate and comprehensive.
 If you notice a problem or some way it can be improved, please [edit the documentation][contribute]!
 
-
 ## Security
 
 *Also see: [Should I trust this website?](/faq/#should-i-trust-this-website)*
@@ -33,7 +32,6 @@ The documentation maintainer then verifies that the pull request is mechanically
 If so, the documentation maintainer then merges the pull request, adds a PGP-signed tag to the latest commit (usually the merge commit), then pushes to the remote.
 In cases in which another reviewer is not required, the documentation maintainer may review the pull request (in which case no signed comment is necessary, since it would be redundant with the signed tag).
 
-
 ## Questions, problems, and improvements
 
 If you have a question about something you read in the documentation, please send it to the appropriate [mailing list][support].
@@ -41,18 +39,17 @@ If you see that something in the documentation should be fixed or improved, plea
 To report an issue with the documentation, please follow our standard [issue reporting guidelines][issue].
 (If you report an issue with the documentation, you will likely be asked to address it, unless there is a clear indication in your report that you are not willing or able to do so.)
 
-
 ## How to contribute
 
 Editing the documentation is easy, so if you see that a change should be made, please contribute it!
 
 A few notes before we get started:
 
- * Since Qubes is a security-oriented project, every documentation change will be reviewed before it's accepted.
+* Since Qubes is a security-oriented project, every documentation change will be reviewed before it's accepted.
    This allows us to maintain quality control and protect our users.
- * We don't want you to spend time and effort on a contribution that we can't accept.
+* We don't want you to spend time and effort on a contribution that we can't accept.
    If your contribution would take a lot of time, please [file an issue][issue] for it first so that we can make sure we're on the same page before significant works begins.
- * Alternatively, you may already have written content that doesn't conform to these guidelines, but you'd be willing to modify it so that it does.
+* Alternatively, you may already have written content that doesn't conform to these guidelines, but you'd be willing to modify it so that it does.
    In this case, you can still submit it by following the instructions below.
    Just make a note in your pull request that you're aware of the changes that need to be made and that you're just asking for the content to be reviewed before you spend time making those changes.
 
@@ -113,8 +110,7 @@ If, for some reason, we can't accept your pull request, we'll post a comment exp
 
 [![done](/attachment/wiki/doc-edit/10-done.png)](/attachment/wiki/doc-edit/10-done.png)
 
-
+## How to add images
-### How to add images
 
 To add an image to a page, use the following syntax in the main document.
 This will make the image a hyperlink to the image file, allowing the reader to click on the image in order to view the image by itself.
@@ -127,7 +123,6 @@ Then, submit your image(s) in a separate pull request to the [qubes-attachment]
 This is the only permitted way to include images.
 Do not link to images on other websites.
 
-
 ## Organizational guidelines
 
 ### Do not duplicate documentation
@@ -231,7 +226,6 @@ To foo:
 
 Once you foo, make sure to close the baz before fooing the next bar.
 
-
 ## Qubes 4.0 ##
 
 ### How to Foo ###
@@ -251,7 +245,7 @@ Once you foo, make sure to close the baz before fooing the next bar.
 
 Subdividing the page into clearly-labeled sections for each version has several benefits:
 
- * It preserves good content for older (but still supported) versions.
+* It preserves good content for older (but still supported) versions.
    Many documentation contributors are also people who prefer to use the latest version.
    Many of them are tempted to *replace* existing content that applies to an older, supported version with content that applies only to the latest version.
    This is somewhat understandable.
@@ -261,15 +255,15 @@ Subdividing the page into clearly-labeled sections for each version has several
    With the older, supported version, there has been more time to fix bugs and make improvements in both the software and the documentation.
    Consequently, much of the documentation content for this version may have gone through several rounds of editing, review, and revision.
    It would be a tragedy for this content to vanish while the very set of users who most prize stability and reliability are depending on it.
- * It's easy for readers to quickly find the information they're looking for, since they can go directly to the section that applies to their version.
+* It's easy for readers to quickly find the information they're looking for, since they can go directly to the section that applies to their version.
- * It's hard for readers to miss information they need, since it's all in one place.
+* It's hard for readers to miss information they need, since it's all in one place.
    In the incorrect example, information that the reader needs could be in any paragraph in the entire document, and there's no way to tell without reading the entire page.
    In the correct example, the reader can simply skim the headings in order to know which parts of the page need to be read and which can be safely ignored.
    The fact that some content is repeated in the two version-specific sections is not a problem, since no reader has to read the same thing twice.
    Moreover, as one version gets updated, it's likely that the documentation for that version will also be updated.
    Therefore, content that is initially duplicated between version-specific sections will not necessarily stay that way, and this is a good thing:
    We want the documentation for a version that *doesn't* change to stay the same, and we want the documentation for a version that *does* change to change along with the software.
- * It's easy for documentation contributors and maintainers to know which file to edit and update, since there's only one page for all Qubes OS versions.
+* It's easy for documentation contributors and maintainers to know which file to edit and update, since there's only one page for all Qubes OS versions.
    Initially creating the new headings and duplicating content that applies to both is only a one-time cost for each page, and many pages don't even require this treatment, since they apply to all currently-supported Qubes OS versions.
 
 By contrast, an alternative approach, such as segregating the documentation into two different branches, would mean that contributions that apply to both Qubes versions would only end up in one branch, unless someone remembered to manually submit the same thing to the other branch and actually made the effort to do so.
@@ -281,10 +275,9 @@ Good general content that was submitted only to one branch would effectively dis
 
 For further discussion about version-specific documentation in Qubes, see [here][version-thread].
 
-
 ## Style guidelines
 
- * Familiarize yourself with the terms defined in the [glossary]. Use these
+* Familiarize yourself with the terms defined in the [glossary]. Use these
    terms consistently and accurately throughout your writing.
  * Syntactically distinguish variables in commands.
    For example, this is ambiguous:
@@ -300,7 +293,6 @@ For further discussion about version-specific documentation in Qubes, see [here]
    2. Using underscores (`_`) between words
    3. Using all capital letters
 
-
 ## Markdown conventions
 
 All the documentation is written in Markdown for maximum accessibility.
@@ -320,14 +312,15 @@ When making contributions, please try to observe the following style conventions
  * Insert a newline at, and only at, the end of each sentence, except when the text will be reproduced outside of the Qubes website repo (see previous item for examples).
    * Rationale: This practice results in one sentence per line, which is most appropriate for source that consists primarily of natural language text.
      It results in the most useful diffs and facilitates translation into other languages while mostly preserving source readability.
- * If appropriate, make numerals in numbered lists match between Markdown source and HTML output.
+* If appropriate, make numerals in numbered lists match between Markdown source and HTML output.
-   * Rationale: In the event that a user is required to read the Markdown source directly, this will make it easier to follow, e.g., numbered steps in a set of instructions.
+  * Rationale: In the event that a user is required to read the Markdown source directly, this will make it easier to follow, e.g., numbered steps in a set of instructions.
- * Use hanging indentations  
+* Use hanging indentations
    where appropriate.
- * Use Atx-style headings: `# h1`, `##h 2`, `### h3`, etc.
+* Use Atx-style headings: `# h1`, `##h 2`, `### h3`, etc.
- * When writing code blocks, use [syntax highlighting](https://github.github.com/gfm/#info-string) where [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers) and use `[...]` for anything omitted.
+* When writing code blocks, use [syntax highlighting](https://github.github.com/gfm/#info-string) where [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers) and use `[...]` for anything omitted.
- * When providing command line examples:
+* When providing command line examples:
-   * Tell the reader where to open a terminal (dom0 or a specific domU), and show the command along with its output (if any) in a code block, e.g.:
+  * Tell the reader where to open a terminal (dom0 or a specific domU), and show the command along with its output (if any) in a code block, e.g.:
+
      ~~~markdown
      Open a terminal in dom0 and run:
      ```shell_session
@@ -336,10 +329,12 @@ When making contributions, please try to observe the following style conventions
      Hello
      ```
      ~~~
-   * Precede each command with the appropriate command prompt:
+
+  * Precede each command with the appropriate command prompt:
      At a minimum, the prompt should contain a trailing `#` (for the user `root`) or `$` (for other users) on Linux systems and `>` on Windows systems, respectively.
-   * Don't try to add comments inside the code block.
+  * Don't try to add comments inside the code block.
      For example, *don't* do this:
+
      ~~~markdown
      Open a terminal in dom0 and run:
      ```shell_session
@@ -350,18 +345,17 @@ When making contributions, please try to observe the following style conventions
      Hello
      ```
      ~~~
+
      The `#` symbol preceding each comment is ambiguous with a root command prompt.
      Instead, put your comments *outside* of the code block in normal prose.
 
 ([This][md] is a great source for learning about Markdown.)
 
-
 ## Git conventions
 
 Please try to write good commit messages, according to the
 [instructions in our coding style guidelines][git-commit].
 
-
 [qubes-doc]: https://github.com/QubesOS/qubes-doc
 [glossary]: /doc/glossary/
 [issue]: /doc/reporting-bugs/

developer/general/gsoc.md

@@ -98,17 +98,17 @@ If applicable, links to more information or discussions
 
 **Expected results**:
 
- - Design how Vagrant Qubes provider should look like, including:
+- Design how Vagrant Qubes provider should look like, including:
-   - [box format](https://www.vagrantup.com/docs/plugins/providers.html#box-format)
+  - [box format](https://www.vagrantup.com/docs/plugins/providers.html#box-format)
-   - method for running commands inside (ssh vs qvm-run)
+  - method for running commands inside (ssh vs qvm-run)
- - Write a Vagrant provider able to create/start/stop/etc a VM
+- Write a Vagrant provider able to create/start/stop/etc a VM
- - Document how to configure and use the provider, including required qrexec policy changes and possibly firewall rules
+- Document how to configure and use the provider, including required qrexec policy changes and possibly firewall rules
- - Write integration tests
+- Write integration tests
 
 **Knowledge prerequisite**:
 
- - Ruby
+- Ruby
- - Vagrant concepts
+- Vagrant concepts
 
 **Mentor**: [Wojtek Porczyk](/team/), [Marek Marczykowski-Górecki](/team/)
 
@@ -124,7 +124,6 @@ If applicable, links to more information or discussions
 - Implementation of the above mechanism.
 - Documentation how to configure it securely.
 
-
 **Knowledge prerequisite**:
 
 - shell and/or python scripting
@@ -151,10 +150,11 @@ Choose either of GUI agent, GUI daemon. Both are of similar complexity and each
 - implement tests for new GUI handling, similar to existing tests for X11 based GUI
 
 Relevant links:
- - [Low level GUI documentation](/doc/gui/)
+
- - [qubes-gui-agent-linux](https://github.com/qubesos/qubes-gui-agent-linux)
+- [Low level GUI documentation](/doc/gui/)
- - [qubes-gui-daemon](https://github.com/qubesos/qubes-gui-daemon)
+- [qubes-gui-agent-linux](https://github.com/qubesos/qubes-gui-agent-linux)
- - [Use Wayland instead of X11 to increase performance](https://github.com/qubesos/qubes-issues/issues/3366)
+- [qubes-gui-daemon](https://github.com/qubesos/qubes-gui-daemon)
+- [Use Wayland instead of X11 to increase performance](https://github.com/qubesos/qubes-issues/issues/3366)
 
 **Knowledge prerequisite**:
 
@@ -181,21 +181,21 @@ details: [#1552](https://github.com/QubesOS/qubes-issues/issues/1552),
 
 **Expected results**:
 
- - Adjust set of VMs and templates included in live edition.
+- Adjust set of VMs and templates included in live edition.
- - Update and fix build scripts for recent Qubes OS version.
+- Update and fix build scripts for recent Qubes OS version.
- - Update startup script to mount appropriate directories as either
+- Update startup script to mount appropriate directories as either
-   copy-on-write (device-mapper snapshot), or tmpfs.
+  copy-on-write (device-mapper snapshot), or tmpfs.
- - Optimize memory usage: should be possible to run sys-net, sys-firewall, and
+- Optimize memory usage: should be possible to run sys-net, sys-firewall, and
-   at least two more VMs on 4GB machine. This include minimizing writes to
+  at least two more VMs on 4GB machine. This include minimizing writes to
-   copy-on-write layer and tmpfs (disable logging etc).
+  copy-on-write layer and tmpfs (disable logging etc).
- - Research option to install the system from live image. If feasible add
+- Research option to install the system from live image. If feasible add
-   this option.
+  this option.
 
 **Knowledge prerequisite**:
 
- - System startup sequence: bootloaders (isolinux, syslinux, grub, UEFI), initramfs, systemd.
+- System startup sequence: bootloaders (isolinux, syslinux, grub, UEFI), initramfs, systemd.
- - Python and Bash scripting
+- Python and Bash scripting
- - Filesystems and block devices: loop devices, device-mapper, tmpfs, overlayfs, sparse files.
+- Filesystems and block devices: loop devices, device-mapper, tmpfs, overlayfs, sparse files.
 
 **Mentor**: [Frédéric Pierret](/team/)
 
@@ -219,7 +219,6 @@ REMOVED as of January 2020: work is being done on this
 **Mentor**: [Thomas Leonard](mailto:talex5@gmail.com), [Marek Marczykowski-Górecki](/team/)
 -->
 
-
 ### LogVM(s)
 
 **Project**: LogVM(s)
@@ -232,35 +231,36 @@ immune to altering past entries. See
 
 **Expected results**:
 
- - Design a _simple_ protocol for transferring logs. The less metadata (parsed
+- Design a _simple_ protocol for transferring logs. The less metadata (parsed
-   in log-collecting VM) the better.
+  in log-collecting VM) the better.
- - Implement log collecting service. Besides logs itself, should save
+- Implement log collecting service. Besides logs itself, should save
-   information about logs origin (VM name) and timestamp. The service should
+  information about logs origin (VM name) and timestamp. The service should
-   _not_ trust sending VM in any of those.
+  _not_ trust sending VM in any of those.
- - Implement log forwarder compatible with systemd-journald and rsyslog. A
+- Implement log forwarder compatible with systemd-journald and rsyslog. A
-   mechanism (service/plugin) fetching logs in real time from those and sending
+  mechanism (service/plugin) fetching logs in real time from those and sending
-   to log-collecting VM over qrexec service.
+  to log-collecting VM over qrexec service.
- - Document the protocol.
+- Document the protocol.
- - Write unit tests and integration tests.
+- Write unit tests and integration tests.
 
 **Knowledge prerequisite**:
 
- - syslog
+- syslog
- - systemd
+- systemd
- - Python/Bash scripting
+- Python/Bash scripting
 
 **Mentor**: [Frédéric Pierret](/team/)
 
 
 ### Whonix IPv6 and nftables support
+
 **Project**: Whonix IPv6 and nftables support
 
 **Brief explanation**: [T509](https://phabricator.whonix.org/T509)
 
 **Expected results**:
 
-- Work at upstream Tor: An older version of https://trac.torproject.org/projects/tor/wiki/doc/TransparentProxy page was the origin of Whonix. Update that page for nftables / IPv6 support without mentioning Whonix. Then discuss that on the tor-talk mailing list for wider input. - https://trac.torproject.org/projects/tor/ticket/21397
+- Work at upstream Tor: An older version of [TransparentProxy](https://trac.torproject.org/projects/tor/wiki/doc/TransparentProxy) page was the origin of Whonix. Update that page for nftables / IPv6 support without mentioning Whonix. Then discuss that on the tor-talk mailing list for wider input. [here](https://trac.torproject.org/projects/tor/ticket/21397)
-- implement corridor feature request add IPv6 support / port to nftables - https://github.com/rustybird/corridor/issues/39
+- implement corridor feature request add IPv6 support / port to nftables - [issue](https://github.com/rustybird/corridor/issues/39)
 - port [whonix-firewall](https://github.com/Whonix/whonix-firewall) to nftables
 - make connections to IPv6 Tor relays work
 - make connections to IPv6 destinations work
@@ -293,19 +293,19 @@ immune to altering past entries. See
 
 **Expected results**:
 
- - A template for `autounattended.xml` file for Windows installer - the template should have placeholders for settings that need to be provided by the user.
+- A template for `autounattended.xml` file for Windows installer - the template should have placeholders for settings that need to be provided by the user.
- - A tool for generating actual `autounattended.xml` file based on the template and user settings.
+- A tool for generating actual `autounattended.xml` file based on the template and user settings.
- - A tool for launching Windows installation, given installation image and `autounattended.xml` file (can be the same as in the above point).
+- A tool for launching Windows installation, given installation image and `autounattended.xml` file (can be the same as in the above point).
- - (Optional) Unattended installation should also include Qubes Windows Tools.
+- (Optional) Unattended installation should also include Qubes Windows Tools.
- - (Optional) A tool should be able to use Windows license embedded in ACPI tables - [related discussion](https://groups.google.com/d/msgid/qubes-devel/0b7fabae-f843-e7ce-40cf-193326cecdb0%40zrubi.hu)
+- (Optional) A tool should be able to use Windows license embedded in ACPI tables - [related discussion](https://groups.google.com/d/msgid/qubes-devel/0b7fabae-f843-e7ce-40cf-193326cecdb0%40zrubi.hu)
- - User documentation
+- User documentation
- - Automated tests (unit tests, integration tests)
+- Automated tests (unit tests, integration tests)
 
 **Knowledge prerequisite**:
 
- - Python scripting
+- Python scripting
- - Linux administration, including handling loop devices, partition tables, filesystems etc
+- Linux administration, including handling loop devices, partition tables, filesystems etc
- - For optional features, C language and x86 architecture (ACPI tables)
+- For optional features, C language and x86 architecture (ACPI tables)
 
 **Mentor**: [Rafał Wojdyła](/team/), [Marek Marczykowski-Górecki](/team/)
 
@@ -315,33 +315,33 @@ immune to altering past entries. See
 
 **Brief explanation**: Integrating GNOME into Qubes dom0. This include:
 
- - patching window manager to add colorful borders
+- patching window manager to add colorful borders
- - removing stuff not needed in dom0 (file manager(s), indexing services etc)
+- removing stuff not needed in dom0 (file manager(s), indexing services etc)
- - adjusting menu for easy navigation (same applications in different VMs and such problems, dom0-related entries in one place)
+- adjusting menu for easy navigation (same applications in different VMs and such problems, dom0-related entries in one place)
- - More info: [#1806](https://github.com/QubesOS/qubes-issues/issues/1806)
+- More info: [#1806](https://github.com/QubesOS/qubes-issues/issues/1806)
 
 **Expected results**:
 
- - Review existing support for other desktop environments (KDE, Xfce4, i3, awesome).
+- Review existing support for other desktop environments (KDE, Xfce4, i3, awesome).
- - Patch window manager to draw colorful borders (we use only server-side
+- Patch window manager to draw colorful borders (we use only server-side
-   decorations), there is already very similar patch in
+  decorations), there is already very similar patch in
-   [Cappsule project](https://github.com/cappsule/cappsule-gui).
+  [Cappsule project](https://github.com/cappsule/cappsule-gui).
- - Configure GNOME to not make use of dom0 user home in visible way (no search
+- Configure GNOME to not make use of dom0 user home in visible way (no search
-   in files there, no file manager, etc).
+  in files there, no file manager, etc).
- - Configure GNOME to not look into external devices plugged in (no auto
+- Configure GNOME to not look into external devices plugged in (no auto
-   mounting, device notifications etc).
+  mounting, device notifications etc).
- - Package above modifications as rpms, preferably as extra configuration files
+- Package above modifications as rpms, preferably as extra configuration files
-   and/or plugins than overwriting existing files. Exceptions to this rule may
+  and/or plugins than overwriting existing files. Exceptions to this rule may
-   apply if no other option.
+  apply if no other option.
- - Adjust comps.xml (in installer-qubes-os repo) to define package group with
+- Adjust comps.xml (in installer-qubes-os repo) to define package group with
-   all required packages.
+  all required packages.
- - Document installation procedure.
+- Document installation procedure.
 
 **Knowledge prerequisite**:
 
- - GNOME architecture
+- GNOME architecture
- - C language (patching metacity)
+- C language (patching metacity)
- - Probably also javascript - for modifying GNOME shell extensions
+- Probably also javascript - for modifying GNOME shell extensions
 
 **Mentor**: [Frédéric Pierret](/team/), [Marek Marczykowski-Górecki](/team/)
 
@@ -358,6 +358,7 @@ immune to altering past entries. See
 **Mentors**: Andrew Clausen and Jean-Philippe Ouellet
 
 ### Progress towards reproducible builds
+
 **Project**: Progress towards reproducible builds
 
 **Brief explanation**: A long-term goal is to be able to build the entire OS and installation media in a completely bit-wise deterministic manner, but there are many baby steps to be taken along that path. See:
@@ -384,21 +385,21 @@ Qubes currently only supports the x86_64 CPU architecture. Xen currently has add
 
 Some related discussion:
 
- - [#4318](https://github.com/QubesOS/qubes-issues/issues/4318) on porting to ppc64.
+- [#4318](https://github.com/QubesOS/qubes-issues/issues/4318) on porting to ppc64.
- - [#3894](https://github.com/QubesOS/qubes-issues/issues/3894) on porting to L4 microkernel.
+- [#3894](https://github.com/QubesOS/qubes-issues/issues/3894) on porting to L4 microkernel.
 
 **Expected results**:
 
- - Add cross-compilation support to qubes-builder and related components.
+- Add cross-compilation support to qubes-builder and related components.
- - Make aarch64 specific adjustments to Qubes toolstacks/manager (including passthrough of devices from device tree to guest domains).
+- Make aarch64 specific adjustments to Qubes toolstacks/manager (including passthrough of devices from device tree to guest domains).
- - Aarch64 specific integration and unit tests.
+- Aarch64 specific integration and unit tests.
- - Production of generic u-boot or uefi capable image/iso for target hardware.
+- Production of generic u-boot or uefi capable image/iso for target hardware.
 
 **Knowledge prerequisite**:
 
- - Libvirt and Qubes toolstacks (C and python languages).
+- Libvirt and Qubes toolstacks (C and python languages).
- - Xen debugging.
+- Xen debugging.
- - General ARM architecture knowledge.
+- General ARM architecture knowledge.
 
 **Mentor**: [Marek Marczykowski-Górecki](/team/)
 
@@ -426,16 +427,16 @@ More information and further links can be found in the related issue:
 
 **Expected results**:
 
- - Add cross-compilation support to qubes-builder and related components.
+- Add cross-compilation support to qubes-builder and related components.
- - Make ppc64 specific adjustments to Qubes toolstacks/manager (including passthrough of devices from device tree to guest domains).
+- Make ppc64 specific adjustments to Qubes toolstacks/manager (including passthrough of devices from device tree to guest domains).
- - ppc64 specific integration and unit tests.
+- ppc64 specific integration and unit tests.
- - Production of generic u-boot or uefi capable image/iso for target hardware.
+- Production of generic u-boot or uefi capable image/iso for target hardware.
 
 **Knowledge prerequisite**:
 
- - Libvirt and Qubes toolstacks (C and python languages).
+- Libvirt and Qubes toolstacks (C and python languages).
- - KVM or XEN internals
+- KVM or XEN internals
- - General ppc64 architecture knowledge.
+- General ppc64 architecture knowledge.
 
 **Mentor**: [Marek Marczykowski-Górecki](/team/)
 
@@ -451,11 +452,12 @@ Since it's software emulation it's rather slow.
 Details, reference: [#2233](https://github.com/QubesOS/qubes-issues/issues/2233)
 
 **Expected results**:
-  - a simple way of setting up Android qubes with hardware emulation
+
+- a simple way of setting up Android qubes with hardware emulation
   (distributed as a template or as a salt, handling various modern Android versions)
-  - figuring out and implementing an easy and secure way to connect an Android 
+- figuring out and implementing an easy and secure way to connect an Android
   qube to a development qube with Android studio
-  - documentation and tests
+- documentation and tests
 
 **Knowledge prerequisite**:
 

developer/general/gsod.md

@@ -29,6 +29,7 @@ Here's a suggested template for adding project ideas:
 
 **Mentor**: Name and email address.
 ```
+
 ### Offline documentation
 
 **Project**: Offline documentation
@@ -37,13 +38,13 @@ Here's a suggested template for adding project ideas:
 
 **Expected results**:
 
- - Review [past discussions on the issue](https://github.com/QubesOS/qubes-issues/issues/1019)
+- Review [past discussions on the issue](https://github.com/QubesOS/qubes-issues/issues/1019)
- - Recommend workflow and platform for displaying offline documentation
+- Recommend workflow and platform for displaying offline documentation
- - Test workflow and platform to ensure usability and functionality
+- Test workflow and platform to ensure usability and functionality
 
 **Knowledge prerequisite**:
 
- - [Markdown][markdown]
+- [Markdown][markdown]
 
 **Mentor**: [Marek Marczykowski-Górecki][team]
 
@@ -55,12 +56,12 @@ Here's a suggested template for adding project ideas:
 
 **Expected results**:
 
- - Review [past discussions on the issue](https://github.com/QubesOS/qubes-issues/issues/1774)
+- Review [past discussions on the issue](https://github.com/QubesOS/qubes-issues/issues/1774)
- - Provide visual mock-ups and proposed text 
+- Provide visual mock-ups and proposed text
 
 **Knowledge prerequisite**:
 
- - some experience with Anaconda would be helpful
+- some experience with Anaconda would be helpful
 
 **Mentor**: [Marek Marczykowski-Górecki][team]
 

developer/general/join.md

@@ -10,4 +10,3 @@ Joining the Qubes OS Team
 The Qubes OS Project does not currently have any open positions.
 This page will be updated when open positions become available.
 In the meantime, there are many different ways you can [contribute to the Qubes OS project](/doc/contributing/).
-

developer/general/package-contributions.md

@@ -15,38 +15,41 @@ This page explains the inclusion criteria and procedures for such packages, as w
 
 Inclusion Criteria
 ------------------
+
 In order to be accepted, packages must:
 
- * In no way weaken the security of Qubes OS.
+* In no way weaken the security of Qubes OS.
- * Be published under an open-source license (read about the [Qubes OS License]).
+* Be published under an open-source license (read about the [Qubes OS License]).
- * Follow our [coding guidelines].
+* Follow our [coding guidelines].
- * Be thoroughly tested.
+* Be thoroughly tested.
- * Have a clearly-defined use case for Qubes users.
+* Have a clearly-defined use case for Qubes users.
- * Not be unduly burdensome to review.
+* Not be unduly burdensome to review.
 
 (Please note that we always reserve the right to add criteria to this list.)
 
 Contribution Procedure
 ----------------------
+
 Before you start putting serious work into a package, we recommend that you discuss your idea with the Qubes developers and the broader community on the [qubes-devel mailing list].
 Once you have a package that's ready to become part of Qubes OS, please follow this procedure:
 
- 1. Ensure that your package satisfies the [Inclusion Criteria].
+1. Ensure that your package satisfies the [Inclusion Criteria].
- 2. If your code isn't already on GitHub, create a GitHub repo that contains your code. You can have a look to an example package called [qubes-skeleton].
+2. If your code isn't already on GitHub, create a GitHub repo that contains your code. You can have a look to an example package called [qubes-skeleton].
- 3. If you haven't already, [sign your code][sig].
+3. If you haven't already, [sign your code][sig].
- 4. Create an issue in [qubes-issues] with the title `[Contribution] your-package-name`.
+4. Create an issue in [qubes-issues] with the title `[Contribution] your-package-name`.
-    Include a link to your repo, a brief description of your package, and a brief explanation of why you think it should be included in Qubes.
+   Include a link to your repo, a brief description of your package, and a brief explanation of why you think it should be included in Qubes.
-    Please note that the Qubes core developers are very busy.
+   Please note that the Qubes core developers are very busy.
-    If they are under heavy load when you submit your contribution, it may be a very long time before they have time to review your package.
+   If they are under heavy load when you submit your contribution, it may be a very long time before they have time to review your package.
-    If this happens, please do not be discouraged.
+   If this happens, please do not be discouraged.
-    If you think they may have forgotten about your pending contribution, you may "bump" your request by commenting on your issue, but please do this *very* sparingly (i.e., no more than once a month).
+   If you think they may have forgotten about your pending contribution, you may "bump" your request by commenting on your issue, but please do this *very* sparingly (i.e., no more than once a month).
-    We appreciate your understanding!
+   We appreciate your understanding!
- 5. You may be asked followup questions.
+5. You may be asked followup questions.
-    If we decide to accept your contribution, you will be invited to join the [QubesOS-contrib] organization on GitHub as public recognition of your contribution (but without push access; see [Review Procedure]), and [QubesOS-contrib] will fork your repo.
+   If we decide to accept your contribution, you will be invited to join the [QubesOS-contrib] organization on GitHub as public recognition of your contribution (but without push access; see [Review Procedure]), and [QubesOS-contrib] will fork your repo.
-    If we decide not to accept your contribution, we will state the reason and close the issue.
+   If we decide not to accept your contribution, we will state the reason and close the issue.
 
 Update Procedure
 ----------------
+
 *Anyone* can provide an update (patch) to a contributed package, not just the person who contributed that package!
 The update procedure is the same for everyone, including the original package contributor.
 
@@ -57,6 +60,7 @@ Please be prepared to read and respond to these comments.
 
 Review Procedure
 ----------------
+
 This review procedure covers both original package contributions (see [Contribution Procedure]) and all subsequent updates to those packages, including updates from the original package contributor (see [Update Procedure]).
 All changes will be reviewed by a Qubes Core Reviewer (QCR) and the [Package Maintainer] (PM).
 In all cases, the QCR will be a core Qubes developer.
@@ -65,38 +69,39 @@ For example, if someone contributes a package, then disappears, and no suitable
 
 The review procedure is as follows:
 
- 1. Someone, S, wishes to make a change to a package, P.
+1. Someone, S, wishes to make a change to a package, P.
- 2. S submits a fast-forwardable pull request against the fork of P's repo owned by [QubesOS-contrib].
+2. S submits a fast-forwardable pull request against the fork of P's repo owned by [QubesOS-contrib].
- 3. The PM reviews the pull request.
+3. The PM reviews the pull request.
-    If the the pull request passes the PM's review, the PM adds a [signed][sig] *comment* on the pull request stating that it has passed review.
+   If the the pull request passes the PM's review, the PM adds a [signed][sig] *comment* on the pull request stating that it has passed review.
-    (In cases in which S = PM, the PM can simply add a [signed][sig] *tag* to the HEAD commit prior to submitting the pull request.)
+   (In cases in which S = PM, the PM can simply add a [signed][sig] *tag* to the HEAD commit prior to submitting the pull request.)
-    If the pull request does not pass the PM's review, the PM leaves a comment on the pull request explaining why not.
+   If the pull request does not pass the PM's review, the PM leaves a comment on the pull request explaining why not.
- 4. The QCR reviews the pull request.
+4. The QCR reviews the pull request.
-    If the pull request passes the QCR's review, the QCR pushes a [signed][sig] tag to the HEAD commit stating that it has passed review and fast-forward merges the pull request.
+   If the pull request passes the QCR's review, the QCR pushes a [signed][sig] tag to the HEAD commit stating that it has passed review and fast-forward merges the pull request.
-    If the pull request does not pass the QCR's review, the QCR leaves a comment on the pull request explaining why not, and the QCR may decide to close the pull request.
+   If the pull request does not pass the QCR's review, the QCR leaves a comment on the pull request explaining why not, and the QCR may decide to close the pull request.
 
 In all the cases, the first condition to be validated by the QCR's review is to ensure that the contribution **will not** hijack any core packages of [QubesOS] and of course, none of the [QubesOS-contrib] packages too. More precisely, particular attention to the whole build pipeline will be made with a specific review of:
-   - Package dependencies,
+
-   - Build scripts (including downloaded ones),
+* Package dependencies,
-   - All downloaded components should be verified against static hash,
+* Build scripts (including downloaded ones),
-   - RPM/DEB installation scripts (e.g. looking at constraints who would hijack other packages),
+* All downloaded components should be verified against static hash,
-   - Makefiles,
+* RPM/DEB installation scripts (e.g. looking at constraints who would hijack other packages),
-   - Package build [reproducible]
+* Makefiles,
+* Package build [reproducible]
 
 and any steps which would result in partial/total compromise of legitimate components. For this part, you can have a look to an example package called [qubes-skeleton].
 
 Package Maintainers
 -------------------
+
 If you contribute a package, we assume that you will be the maintainer of that package, unless you tell us otherwise.
 As the maintainer of the package, it is your privilege and responsibility to:
 
- * [Review][Review Procedure] each pull request made against the package.
+* [Review][Review Procedure] each pull request made against the package.
- * Decide when the package has reached a new version, and notify the Qubes core developers when this occurs.
+* Decide when the package has reached a new version, and notify the Qubes core developers when this occurs.
 
 If you do not wish to be the maintainer of your package, please let us know.
 If you do not act on your maintainer duties for a given package for an extended period of time and after at least one reminder, we will assume that you no longer wish to be the maintainer for that package.
 
-
 [installing contributed packages]: /doc/installing-contributed-packages/
 [Inclusion Criteria]: #inclusion-criteria
 [Contribution Procedure]: #contribution-procedure

developer/general/usability-ux.md

@@ -4,8 +4,7 @@ title: Usability & UX
 permalink: /doc/usability-ux/
 ---
 
-Usability & UX
+# Usability & UX
-==============
 
 Software that is too complicated to use, is often unused. Because we want as many people as possible to benefit from its unique security properties, the usability and user experience of Qubes OS is an utmost priority!
 
@@ -39,7 +38,6 @@ Perhaps the most common cause of mistakes is complexity. If there is a configura
 
 In making software easy to use, it is crucial to be mindful of [cognitive load](https://en.wikipedia.org/wiki/Cognitive_load) which dictates that *"humans are generally able to hold only seven +/-  two units of information in short-term memory."* Making sure your interfaces don't pass this short-term memory limit is perhaps the most important factor in helping a user feel comfortable instead of overwhelmed.
 
-
 ---
 
 ## Easy to Understand

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

@@ -6,41 +6,36 @@ redirect_from:
 - /en/doc/releases/1.0/release-notes/
 ---
 
-Qubes R1.0 Release Notes
+# Qubes R1.0 Release Notes
-========================
 
 Detailed release notes in [this blog post](https://blog.invisiblethings.org/2012/09/03/introducing-qubes-10.html).
 
-Known issues
+## 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).
+- 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 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.
+- 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.
 
--   On systems with more than 8GB of RAM there is problem with DisposableVM. To fix it, limit maximum memory allocation for DispVM to 3GB
+- On systems with more than 8GB of RAM there is problem with DisposableVM. To fix it, limit maximum memory allocation for DispVM to 3GB
 
     ~~~
     qvm-prefs -s fedora-17-x64-dvm maxmem 3072
     qvm-create-default-dvm --default-template --default-script
     ~~~
 
--   On some systems the KDE Window Manager might freeze upon resuming from S3 sleep when compositing is enabled (and the only method to log in to the system if this happens is to switch to a text console, enter your user's password, kill the kwin process, go back to the Xorg console, log in, and start a new instance of kwin using Konsole application :) If you experience such problems, make sure to disable compositing before putting the system into sleep by pressing Alt-Ctrl-F12 (and then enabling it back once you log in after resume) -- this way you should never see this problem again.
+- On some systems the KDE Window Manager might freeze upon resuming from S3 sleep when compositing is enabled (and the only method to log in to the system if this happens is to switch to a text console, enter your user's password, kill the kwin process, go back to the Xorg console, log in, and start a new instance of kwin using Konsole application :) If you experience such problems, make sure to disable compositing before putting the system into sleep by pressing Alt-Ctrl-F12 (and then enabling it back once you log in after resume) -- this way you should never see this problem again.
 
-Downloads
+## Downloads
----------
 
 See [Qubes Downloads](/doc/QubesDownloads/).
 
-Installation instructions
+## Installation instructions
--------------------------
 
 See [Installation Guide](/doc/installation-guide/).
 
-Upgrading
+## Upgrading
----------
 
 ### From Qubes 1.0-rc1
 
@@ -53,4 +48,3 @@ If you have Qubes Beta 3 currently installed on your system, you must reinstall
 ~~~
 qvm-backup-restore <backup_dir> --replace-template=fedora-15-x64:fedora-17-x64
 ~~~
-

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

@@ -6,13 +6,11 @@ redirect_from:
 - /en/doc/releases/2.0/release-notes/
 ---
 
-Qubes R2.0 Release Notes
+# Qubes R2.0 Release Notes
-========================
 
 Detailed release notes in [this blog post](https://blog.invisiblethings.org/2014/09/26/announcing-qubes-os-release-2.html)
 
-New features since 1.0
+## New features since 1.0
-----------------------
 
 * Support for generic fully virtualized VMs (without qemu in the TCB!)
 * Support for Windows-based AppVMs integration (clipboard, file exchange, qrexec, pv drivers)
@@ -28,35 +26,31 @@ New features since 1.0
 * Support for dynamic screen resolution change
 * Dom0 distribution upgraded to Fedora 20
 
-Known issues
+## Known issues
-------------
 
--   On some graphics cards the Xfce4 Window Manager (one of the two supported Dom0 Windows Managers in Qubes R2, the other being KDE) might behave "strangely", e.g. decorations might not be drawn sometimes. Also the accompanying lightdm login manager might incorrectly display the wallpaper. If you're facing those problems, it's advisable to use the KDE Window Manager and kdm instead of Xfce4 and lightdm (this is default if one chooses the KDE only installation option in the installer).
+* On some graphics cards the Xfce4 Window Manager (one of the two supported Dom0 Windows Managers in Qubes R2, the other being KDE) might behave "strangely", e.g. decorations might not be drawn sometimes. Also the accompanying lightdm login manager might incorrectly display the wallpaper. If you're facing those problems, it's advisable to use the KDE Window Manager and kdm instead of Xfce4 and lightdm (this is default if one chooses the KDE only installation option in the installer).
 
--   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.
+* 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.
 
--   If your GPU is not correctly supported by the Dom0 kernel (e.g. the 3D desktop effects do not run smoothly) then you might experience "heaviness" with Windows 7-based AppVMs. In that case, please solve the problem with your GPU support in Dom0 in the first place (by using a different kernel), or install Qubes OS on a different system.
+* If your GPU is not correctly supported by the Dom0 kernel (e.g. the 3D desktop effects do not run smoothly) then you might experience "heaviness" with Windows 7-based AppVMs. In that case, please solve the problem with your GPU support in Dom0 in the first place (by using a different kernel), or install Qubes OS on a different system.
 
--   Under some circumstances, Qubes backup can create broken backup, without any visible message (\#902). It is advisable to verify a backup to spot the problem. If you encounter this problem, backup VM directory manually.
+* Under some circumstances, Qubes backup can create broken backup, without any visible message (\#902). It is advisable to verify a backup to spot the problem. If you encounter this problem, backup VM directory manually.
 
--   System shutdown sometimes is very slow (\#903). To mitigate the problem, shutdown all the VMs first.
+* System shutdown sometimes is very slow (\#903). To mitigate the problem, shutdown all the VMs first.
 
--   For other known issues take a look at [our trac tickets](https://wiki.qubes-os.org/query?status=accepted&status=assigned&status=new&status=reopened&type=defect&milestone=Release+2.1+(post+R2)&col=id&col=summary&col=status&col=type&col=priority&col=milestone&col=component&order=priority)
+* For other known issues take a look at [our trac tickets](https://wiki.qubes-os.org/query?status=accepted&status=assigned&status=new&status=reopened&type=defect&milestone=Release+2.1+(post+R2)&col=id&col=summary&col=status&col=type&col=priority&col=milestone&col=component&order=priority)
 
 It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems.
 
-Downloads
+## Downloads
----------
 
 See [Qubes Downloads](/doc/QubesDownloads/).
 
-Installation instructions
+## Installation instructions
--------------------------
 
 See [Installation Guide](/doc/installation-guide/).
 
-Upgrading
+## Upgrading
----------
 
 ### From Qubes R2 rc1
 

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

@@ -6,13 +6,11 @@ redirect_from:
 - /en/doc/releases/3.0/release-notes/
 ---
 
-Qubes R3.0 Release Notes
+### Qubes R3.0 Release Notes
-========================
 
 This Qubes OS release is dedicated to the memory of Caspar Bowden.
 
-New features since 2.0
+## New features since 2.0
-----------------------
 
 * HAL (Hypervisor Abstraction Layer) - based on libvirt, opens a whole new
   possibilities of using different hypervisors. Currently Qubes OS uses Xen.
@@ -27,8 +25,7 @@ New features since 2.0
   templates using DispVM.
 * Automated tests - makes much easier to find bugs, before its even shipped to users
 
-Known issues
+## Known issues
-------------
 
 * Windows Tools: `qvm-block` does not work
 
@@ -42,18 +39,15 @@ Known issues
 
 It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems.
 
-Downloads
+## Downloads
----------
 
 See [Qubes Downloads](/doc/QubesDownloads/).
 
-Installation instructions
+## Installation instructions
--------------------------
 
 See [Installation Guide](/doc/installation-guide/).
 
-Upgrading
+## Upgrading
----------
 
 ### From R3.0 release candidate
 
@@ -64,4 +58,3 @@ If you are using Qubes R3.0rc1, R3.0rc2 or R3.0rc3, just install system updates,
 The easiest and safest way to upgrade to Qubes R3.0 is to install it from scratch and use [qubes backup and restore tools](/doc/backup-restore/) for migrating of all of the user VMs.
 
 Users of Qubes R2 can upgrade using [experimental procedure](/doc/upgrade-to-r3.0/).
-

developer/releases/3_1/release-notes.md

@@ -4,11 +4,9 @@ title: Qubes R3.1 release notes
 permalink: /doc/releases/3.1/release-notes/
 ---
 
-Qubes R3.1 release notes
+# Qubes R3.1 release notes
-========================
 
-New features since 3.0
+## New features since 3.0
-----------------------
 
 * Management Stack based of Salt Stack in dom0 - [documentation][salt-doc]
 * Out of the box Whonix setup
@@ -23,8 +21,7 @@ New features since 3.0
 
 You can get detailed description in [completed github issues][github-release-notes]
 
-Known issues
+## Known issues
-------------
 
 * Installation image does not fit on DVD, requires either DVD DL, or USB stick (5GB or more)
 
@@ -38,18 +35,15 @@ Known issues
 
 It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems.
 
-Downloads
+## Downloads
----------
 
 See [Qubes Downloads](/downloads/).
 
-Installation instructions
+## Installation instructions
--------------------------
 
 See [Installation Guide](/doc/installation-guide/).
 
-Upgrading
+## Upgrading
----------
 
 ### From R3.0
 

developer/releases/3_1/schedule.md

@@ -18,4 +18,4 @@ This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule
 | 12 Jan 2016 | 3.1-rc2 release                         |
 | 26 Jan 2016 | decide whether 3.1-rc2 is the final 3.1 |
 |  9 Feb 2016 | current-testing freeze before 3.1-rc3   |
-| <strike>16 Feb 2016</strike><br/>23 Feb 2016 | 3.1-rc3 release                         |
+| ~~16 Feb 2016~~ <br/> 23 Feb 2016 | 3.1-rc3 release                         |

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

@@ -4,11 +4,9 @@ title: Qubes R3.2 release notes
 permalink: /doc/releases/3.2/release-notes/
 ---
 
-Qubes R3.2 release notes
+# Qubes R3.2 release notes
-========================
 
-New features since 3.1
+## New features since 3.1
-----------------------
 
 * Management Stack extended to support in-VM configuration - [documentation][salt-doc]
 * PV USB - [documentation][usb]
@@ -21,8 +19,7 @@ New features since 3.1
 
 You can get detailed description in [completed github issues][github-release-notes]
 
-Known issues
+## 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/2018/01/06/fedora-26-upgrade/).
 
@@ -34,19 +31,16 @@ Known issues
 
 It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems.
 
-Downloads
+## Downloads
----------
 
 See [Qubes Downloads](/downloads/).
 
-Installation instructions
+## Installation instructions
--------------------------
 
 See [Installation Guide](/doc/installation-guide/).
 After installation, [manually upgrade to Fedora 26](/news/2018/01/06/fedora-26-upgrade/).
 
-Upgrading
+## Upgrading
----------
 
 ### From R3.1
 

developer/releases/3_2/schedule.md

@@ -15,9 +15,9 @@ This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule
 | -----------:| --------------------------------------- |
 | 18 Jun 2016 | 3.2-rc1 release                         |
 |  2 Jul 2016 | decide whether 3.2-rc1 is the final 3.2 |
-| <strike>16 Jul 2016</strike><br/>20 Jul 2016 | current-testing freeze before 3.2-rc2   |
+| ~~16 Jul 2016~~ <br/> 20 Jul 2016 | current-testing freeze before 3.2-rc2   |
-| <strike>23 Jul 2016</strike><br/>27 Jul 2016 | 3.2-rc2 release                         |
+| ~~23 Jul 2016~~ <br/> 27 Jul 2016 | 3.2-rc2 release                         |
-| <strike> 5 Aug 2016</strike><br/> 9 Aug 2016 | decide whether 3.2-rc2 is the final 3.2 |
+| ~~5 Aug 2016~~ <br/> 9 Aug 2016 | decide whether 3.2-rc2 is the final 3.2 |
 | 24 Aug 2016 | current-testing freeze before 3.2-rc3   |
 | 31 Aug 2016 | 3.2-rc3 release                         |
 | 29 Sep 2016 | 3.2 release                             |

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

@@ -103,7 +103,6 @@ supported option to upgrade to Qubes R4.0 is to install it from scratch and use
 [qubes backup and restore tools][backup] for migrating of all of the user VMs.
 We also provide [detailed instruction][upgrade-to-r4.0] for this procedure.
 
-
 [backup]: /doc/backup-restore/
 [github-release-notes]: https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+4.0%22+label%3Arelease-notes+is%3Aclosed
 [custom-ip]: https://github.com/QubesOS/qubes-issues/issues/1477

developer/releases/4_0/schedule.md

@@ -14,15 +14,15 @@ This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule
 |  Date       | Stage                                   |
 | -----------:| --------------------------------------- |
 | 31 Jul 2017 | 4.0-rc1 release                         |
-| <strike>28 Aug 2017</strike><br/><strike>11 Sep 2017</strike><br/><strike>9 Oct 2017</strike><br/>18 Oct 2017 | current-testing freeze before 4.0-rc2   |
+| ~~28 Aug 2017~~ <br/>~~11 Sep 2017~~ <br/>~~9 Oct 2017~~ <br/>18 Oct 2017 | current-testing freeze before 4.0-rc2   |
-| <strike> 4 Sep 2017</strike><br/><strike>18 Sep 2017</strike><br/><strike>16 Oct 2017</strike><br/>23 Oct 2017 | 4.0-rc2 release                         |
+| ~~4 Sep 2017~~ <br/> ~~18 Sep 2017~~ <br/>~~16 Oct 2017~~ <br/>23 Oct 2017 | 4.0-rc2 release                        |
-| 6 Nov 2017 | decide whether 4.0-rc2 is the final 4.0 |
+| 6 Nov 2017 | decide whether 4.0-rc2 is the final 4
 | 20 Nov 2017 | current-testing freeze before 4.0-rc3 |
 | 27 Nov 2017 | 4.0-rc3 release |
 | 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 |
+| ~~8 Jan 2018~~ <br/>31 Jan 2018 | 4.0-rc4 release |
-| <strike>22 Jan 2018</strike><br/>14 Feb 2018 | decide whether 4.0-rc4 is the final 4.0 |
+| ~~22 Jan 2018~~ <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 |

developer/releases/notes.md

@@ -7,10 +7,9 @@ permalink: /doc/releases/notes/
 Release Notes
 =============
 
- * [Qubes R1.0 release notes](/doc/releases/1.0/release-notes/)
+* [Qubes R1.0 release notes](/doc/releases/1.0/release-notes/)
- * [Qubes R2.0 release notes](/doc/releases/2.0/release-notes/)
+* [Qubes R2.0 release notes](/doc/releases/2.0/release-notes/)
- * [Qubes R3.0 release notes](/doc/releases/3.0/release-notes/)
+* [Qubes R3.0 release notes](/doc/releases/3.0/release-notes/)
- * [Qubes R3.1 release notes](/doc/releases/3.1/release-notes/)
+* [Qubes R3.1 release notes](/doc/releases/3.1/release-notes/)
- * [Qubes R3.2 release notes](/doc/releases/3.2/release-notes/)
+* [Qubes R3.2 release notes](/doc/releases/3.2/release-notes/)
- * [Qubes R4.0 release notes](/doc/releases/4.0/release-notes/)
+* [Qubes R4.0 release notes](/doc/releases/4.0/release-notes/)
-

developer/releases/schedules.md

@@ -7,8 +7,7 @@ permalink: /doc/releases/schedules/
 Release Schedules
 =================
 
- * [Qubes R3.0 release schedule](/doc/releases/3.0/schedule/)
+* [Qubes R3.0 release schedule](/doc/releases/3.0/schedule/)
- * [Qubes R3.1 release schedule](/doc/releases/3.1/schedule/)
+* [Qubes R3.1 release schedule](/doc/releases/3.1/schedule/)
- * [Qubes R3.2 release schedule](/doc/releases/3.2/schedule/)
+* [Qubes R3.2 release schedule](/doc/releases/3.2/schedule/)
- * [Qubes R4.0 release schedule](/doc/releases/4.0/schedule/)
+* [Qubes R4.0 release schedule](/doc/releases/4.0/schedule/)
-

developer/releases/todo.md

@@ -13,6 +13,7 @@ Release Checklist
 
 On -rc1
 -------
+
 * write schedule
 * create package repositories (linux-yum, linux-deb)
 * update repository definition (core-agent-linux, installer-qubes-os/qubes-release)
@@ -24,6 +25,7 @@ On -rc1
 
 On subsequent -rc
 -----------------
+
 * push packages to `current`
 * update release notes
 * build ISO and push to mirrors
@@ -31,6 +33,7 @@ On subsequent -rc
 
 On final release
 ----------------
+
 * push packages to `current`
 * finish release notes
 * update InstallationInstructions

developer/services/admin-api.md

@@ -148,23 +148,22 @@ to set the policy using current mechanism.
 
 Volume properties:
 
- - `pool`
+- `pool`
- - `vid`
+- `vid`
- - `size`
+- `size`
- - `usage`
+- `usage`
- - `rw`
+- `rw`
- - `source`
+- `source`
- - `save_on_stop`
+- `save_on_stop`
- - `snap_on_start`
+- `snap_on_start`
- - `revisions_to_keep`
+- `revisions_to_keep`
- - `is_outdated`
+- `is_outdated`
 
 Method `admin.vm.Stats` returns `vm-stats` events every `stats_interval` seconds, for every running VM. Parameters of `vm-stats` events:
 
- - `memory_kb` - memory usage in kB
+- `memory_kb` - memory usage in kB
- - `cpu_time` - absolute CPU time (in milliseconds) spent by the VM since its startup, normalized for one CPU
+- `cpu_time` - absolute CPU time (in milliseconds) spent by the VM since its startup, normalized for one CPU
- - `cpu_usage` - CPU usage in percents
+- `cpu_usage` - CPU usage in percents
-
 
 ## Returned messages
 
@@ -329,6 +328,7 @@ The changes are validated before saving, so that the policy cannot end up in an
 invalid state (e.g. syntax error, missing include file).
 
 In addition, there is a mechanism to prevent concurrent modifications of the policy files:
+
 - A `*.Get` call returns a file along with a *token* (currently implemented as
   a hash of the file).
 - When calling `Replace` or `Remove`, you need to include the current token as

developer/services/dom0-secure-updates.md

@@ -18,9 +18,9 @@ Normally there should be few reasons for updating software in Dom0. This is beca
 
 However, we anticipate some other situations when updating Dom0 software might be required:
 
--   Updating drivers/libs for new hardware support
+- Updating drivers/libs for new hardware support
--   Correcting non-security related bugs (e.g. new buttons for qubes manager)
+- Correcting non-security related bugs (e.g. new buttons for qubes manager)
--   Adding new features (e.g. GUI backup tool)
+- Adding new features (e.g. GUI backup tool)
 
 Problems with traditional network-based update mechanisms
 ---------------------------------------------------------

developer/services/dvm-impl.md

@@ -20,19 +20,19 @@ DisposableVM is not started like other VMs, by executing equivalent of `xl creat
 
 Preparing a savefile is done by `/usr/lib/qubes/qubes_prepare_saved_domain.sh` script. It takes two mandatory arguments, appvm name (APPVM) and the savefile name, and optional path to "prerun" script. The script executes the following steps:
 
-1.  APPVM is started by `qvm-start`
+1. APPVM is started by `qvm-start`
-2.  xenstore key `/local/domain/appvm_domain_id/qubes_save_request` is created
+2. xenstore key `/local/domain/appvm_domain_id/qubes_save_request` is created
-3.  if prerun script was specified, copy it to `qubes_save_script` xenstore key
+3. if prerun script was specified, copy it to `qubes_save_script` xenstore key
-4.  wait for the `qubes_used_mem` key to appear
+4. wait for the `qubes_used_mem` key to appear
-5.  (in APPVM) APPVM boots normally, up to the point in `/etc/init.d/qubes_core` script when the presence of `qubes_save_request` key is tested. If it exists, then
+5. (in APPVM) APPVM boots normally, up to the point in `/etc/init.d/qubes_core` script when the presence of `qubes_save_request` key is tested. If it exists, then
-    1.  (in APPVM) if exists, prerun script is retrieved from the respective xenstore key and executed. This preloads filesystem cache with useful applications, so that they will start faster.
+    1. (in APPVM) if exists, prerun script is retrieved from the respective xenstore key and executed. This preloads filesystem cache with useful applications, so that they will start faster.
-    2.  (in APPVM) the amount of used memory is stored to `qubes_used_mem` xenstore key
+    2. (in APPVM) the amount of used memory is stored to `qubes_used_mem` xenstore key
-    3.  (in APPVM) busy-waiting for `qubes_restore_complete` xenstore key to appear
+    3. (in APPVM) busy-waiting for `qubes_restore_complete` xenstore key to appear
 
-6.  when `qubes_used_mem` key appears, the domain memory is reduced to this amount, to make the savefile smaller.
+6. when `qubes_used_mem` key appears, the domain memory is reduced to this amount, to make the savefile smaller.
-7.  APPVM private image is detached
+7. APPVM private image is detached
-8.  the domain is saved via `xl save`
+8. the domain is saved via `xl save`
-9.  the COW file volatile.img (cow for root fs and swap) is packed to `saved_cows.tar` archive
+9. the COW file volatile.img (cow for root fs and swap) is packed to `saved_cows.tar` archive
 
 The `qubes_prepare_saved_domain.sh` script is lowlevel. It is usually called by `qvm-create-default-dvm` script, that takes care of creating a special AppVM (named template\_name-dvm) to be passed to `qubes_prepare_saved_domain.sh`, as well as copying the savefile to /dev/shm (the latter action is not done if the `/var/lib/qubes/dvmdata/dont_use_shm` file exists).
 
@@ -41,12 +41,12 @@ Restoring a DisposableVM from the savefile
 
 Normally, disposable VM is created when qubes rpc request with target *\$dispvm* is received. Then, as a part of rpc connection setup, the `qfile-daemon-dvm` program is executed; it executes `/usr/lib/qubes/qubes_restore` program. It is crucial that this program executes quickly, to make DisposableVM creation overhead bearable for the user. Its main steps are:
 
-1.  modify the savefile so that the VM name, VM UUID, MAC address and IP address are unique
+1. modify the savefile so that the VM name, VM UUID, MAC address and IP address are unique
-2.  restore the COW files from the `saved_cows.tar`
+2. restore the COW files from the `saved_cows.tar`
-3.  create the `/var/run/qubes/fast_block_attach` file, whose presence tells the `/etc/xen/scripts/block` script to bypass some redundant checks and execute as fast as possible.
+3. create the `/var/run/qubes/fast_block_attach` file, whose presence tells the `/etc/xen/scripts/block` script to bypass some redundant checks and execute as fast as possible.
-4.  execute `xl restore` in order to restore a domain.
+4. execute `xl restore` in order to restore a domain.
-5.  create the same xenstore keys as normally created when AppVM boots (e.g. `qubes_ip`)
+5. create the same xenstore keys as normally created when AppVM boots (e.g. `qubes_ip`)
-6.  create the `qubes_restore_complete` xenstore key. This allows the boot process in DisposableVM to continue.
+6. create the `qubes_restore_complete` xenstore key. This allows the boot process in DisposableVM to continue.
 
 The actual passing of files between AppVM and a DisposableVM is implemented via qubes rpc.
 

developer/services/qfilecopy.md

@@ -13,15 +13,15 @@ InterVM file copy design
 
 There are two cases when we need a mechanism to copy files between VMs:
 
--   "regular" file copy - when user instructs file manager to copy a given files/directories to a different VM
+- "regular" file copy - when user instructs file manager to copy a given files/directories to a different VM
--   DispVM copy - user selects "open in DispVM" on a file; this file must be copied to a DisposableVM, edited by user, and possibly a modified file copied back from DispVM to VM.
+- DispVM copy - user selects "open in DispVM" on a file; this file must be copied to a DisposableVM, edited by user, and possibly a modified file copied back from DispVM to VM.
 
 Prior to Qubes Beta1, for both cases, a block device (backed by a file in dom0 with a vfat filesystem on it) was attached to VM, file(s) copied there, and then the device was detached and attached to target VM. In the DispVM case, if a edited file has been modified, another block device is passed to requester VM in order to update the source file.
 
 This has the following disadvantages:
 
--   performance - dom0 has to prepare and attach/detach block devices, which is slow because of hotplug scripts involvement.
+- performance - dom0 has to prepare and attach/detach block devices, which is slow because of hotplug scripts involvement.
--   security - VM kernel parses partition table and filesystem metadata from the block device; they are controlled by (potentially untrusted) sender VM.
+- security - VM kernel parses partition table and filesystem metadata from the block device; they are controlled by (potentially untrusted) sender VM.
 
 In Qubes Beta1, we have reimplemented interVM file copy using qrexec, which addresses the above mentioned disadvantages. In Qubes Beta2, even more generic solution (qubes rpc) is used. See the developer docs on qrexec and qubes rpc. In a nutshell, the file sender and the file receiver just read/write from stdin/stdout, and the qubes rpc layer passes data properly - so, no block devices are used.
 

developer/services/qfileexchgd.md

@@ -21,37 +21,36 @@ Overview
 
 *qfilexchgd* is a dom0 daemon responsible for managing exchange of block devices ("virtual pendrives") between VMs. It is used for
 
--   copying files between AppVMs
+- copying files between AppVMs
--   copying a single file between an AppVM and a DisposableVM
+- copying a single file between an AppVM and a DisposableVM
 
 *qfilexchgd* is started after first *qubes\_guid* has been started, so that it has access to X display in dom0 to present dialog messages.
 
 *qfilexchgd* is event driven. The sources of events are:
 
--   trigger of xenstore watch for the changes in `/local/domain` xenstore hierarchy - to detect start/stop of VMs, and maintain vmname-\>vm\_xid dictionary
+- trigger of xenstore watch for the changes in `/local/domain` xenstore hierarchy - to detect start/stop of VMs, and maintain vmname-\>vm\_xid dictionary
--   trigger of xenstore watch for a change in `/local/domain/domid/device/qpen` key - VMs write to this key to request service from *qfilexchgd*
+- trigger of xenstore watch for a change in `/local/domain/domid/device/qpen` key - VMs write to this key to request service from *qfilexchgd*
 
 Copying files between AppVMs
 ----------------------------
 
-1.  AppVM1 user runs *qvm-copy-to-vm* script (accessible from Dolphin file manager by right click on a "file(s)-\>Actions-\>Send to VM" menu). It calls */usr/lib/qubes/qubes\_penctl new*, and it writes "new" request to its `device/qpen` xenstore key. *qfilexchgd* creates a new 1G file, makes vfat fs on it, and does block-attach so that this file is attached as `/dev/xvdg` in AppVM1.
+1. AppVM1 user runs *qvm-copy-to-vm* script (accessible from Dolphin file manager by right click on a "file(s)-\>Actions-\>Send to VM" menu). It calls */usr/lib/qubes/qubes\_penctl new*, and it writes "new" request to its `device/qpen` xenstore key. *qfilexchgd* creates a new 1G file, makes vfat fs on it, and does block-attach so that this file is attached as `/dev/xvdg` in AppVM1.
-2.  AppVM1 mounts `/dev/xvdg` on `/mnt/outgoing` and copies requested files there, then unmounts it.
+2. AppVM1 mounts `/dev/xvdg` on `/mnt/outgoing` and copies requested files there, then unmounts it.
-3.  AppVM1 writes "send DestVM" request to its `device/qpen` xenstore key (calling */usr/lib/qubes/qubes\_penctl send DestVM*). After getting confirmation by displaying a dialog box in dom0 display, *qfilexchgd* detaches `/dev/xvdg` from AppVM1, attaches it as `/dev/xvdh` to DestVM.
+3. AppVM1 writes "send DestVM" request to its `device/qpen` xenstore key (calling */usr/lib/qubes/qubes\_penctl send DestVM*). After getting confirmation by displaying a dialog box in dom0 display, *qfilexchgd* detaches `/dev/xvdg` from AppVM1, attaches it as `/dev/xvdh` to DestVM.
-4.  In DestVM, udev script for `/dev/xvdh` named *qubes\_add\_pendrive\_script* (see `/etc/udev/rules.d/qubes.rules`) mounts `/dev/xvdh` on `/mnt/incoming`, and then waits for `/mnt/incoming` to become unmounted. A file manager running in DestVM shows a new volume, and user in DestVM may copy files from it. When user in DestVM is done, then user unmounts `/mnt/incoming`. *qubes\_add\_pendrive*\_script then tells *qfilexchgd* to detach `/dev/xvdh` and terminates.
+4. In DestVM, udev script for `/dev/xvdh` named *qubes\_add\_pendrive\_script* (see `/etc/udev/rules.d/qubes.rules`) mounts `/dev/xvdh` on `/mnt/incoming`, and then waits for `/mnt/incoming` to become unmounted. A file manager running in DestVM shows a new volume, and user in DestVM may copy files from it. When user in DestVM is done, then user unmounts `/mnt/incoming`. *qubes\_add\_pendrive*\_script then tells *qfilexchgd* to detach `/dev/xvdh` and terminates.
 
 Copying a single file between AppVM and a DisposableVM
 ------------------------------------------------------
 
 In order to minimize attack surface presented by necessity to process virtual pendrive metadata sent by (potentially compromised and malicious) DisposableVM, AppVM\<-\>DisposableVM file exchange protocol does not use any filesystem.
 
-1.  User in AppVM1 runs *qvm-open-in-dvm* (accessible from Dolphin file manager by right click on a "file-\>Actions-\>Open in DisposableVM" menu). *qvm-open-in-dvm*
+1. User in AppVM1 runs *qvm-open-in-dvm* (accessible from Dolphin file manager by right click on a "file-\>Actions-\>Open in DisposableVM" menu). *qvm-open-in-dvm*
-    1.  gets a new `/dev/xvdg` (just as described in previous paragraph)
+    1. gets a new `/dev/xvdg` (just as described in previous paragraph)
-    2.  computes a new unique transaction seq SEQ by incrementing `/home/user/.dvm/seq` contents,
+    2. computes a new unique transaction seq SEQ by incrementing `/home/user/.dvm/seq` contents,
-    3.  writes the requested file name (say, /home/user/document.txt) to `/home/user/.dvm/SEQ`
+    3. writes the requested file name (say, /home/user/document.txt) to `/home/user/.dvm/SEQ`
-    4.  creates a dvm\_header (see core.git/appvm/dvm.h) on `/dev/xvdg`, followed by file contents
+    4. creates a dvm\_header (see core.git/appvm/dvm.h) on `/dev/xvdg`, followed by file contents
-    5.  writes the "send disposable SEQ" command to its `device/qpen` xenstore key.
+    5. writes the "send disposable SEQ" command to its `device/qpen` xenstore key.
-
-2.  *qfilexchgd* sees that "send" argument=="disposable", and creates a new DisposableVM by calling */usr/lib/qubes/qubes\_restore*. It adds the new DisposableVM to qubesDB via qvm\_collection.add\_new\_disposablevm. Then it attaches the virtual pendrive (previously attached as `/dev/xvdg` at AppVM1) as `/dev/xvdh` in DisposableVM.
-3.  In DisposableVM, *qubes\_add\_pendrive\_script* sees non-zero `qubes_transaction_seq` key in xenstore, and instead processing the virtual pendrive as in the case of normal copy, treats it as DVM transaction (a request, because we run in DisposableVM). It retrieves the body of the file passed in `/dev/xvdh`, copies to /tmp, and runs *mime-open* utility to open appropriate executable to edit it. When *mime-open* returns, if the file was modified, it is sent back to AppVM1 (by writing "send AppVM1 SEQ" to `device/qpen` xenstore key). Then DisposableVM destroys itself.
-4.  In AppVM1, a new `/dev/xvdh` appears (because DisposableVM has sent it). *qubes\_add\_pendrive\_script* sees non-zero `qubes_transaction_seq` key, and treats it as DVM transaction (a response, because we run in AppVM, not DisposableVM). It retrieves the filename from `/home/user/.dvm/SEQ`, and copies data from `/dev/xvdh` to it.
 
+2. *qfilexchgd* sees that "send" argument=="disposable", and creates a new DisposableVM by calling */usr/lib/qubes/qubes\_restore*. It adds the new DisposableVM to qubesDB via qvm\_collection.add\_new\_disposablevm. Then it attaches the virtual pendrive (previously attached as `/dev/xvdg` at AppVM1) as `/dev/xvdh` in DisposableVM.
+3. In DisposableVM, *qubes\_add\_pendrive\_script* sees non-zero `qubes_transaction_seq` key in xenstore, and instead processing the virtual pendrive as in the case of normal copy, treats it as DVM transaction (a request, because we run in DisposableVM). It retrieves the body of the file passed in `/dev/xvdh`, copies to /tmp, and runs *mime-open* utility to open appropriate executable to edit it. When *mime-open* returns, if the file was modified, it is sent back to AppVM1 (by writing "send AppVM1 SEQ" to `device/qpen` xenstore key). Then DisposableVM destroys itself.
+4. In AppVM1, a new `/dev/xvdh` appears (because DisposableVM has sent it). *qubes\_add\_pendrive\_script* sees non-zero `qubes_transaction_seq` key, and treats it as DVM transaction (a response, because we run in AppVM, not DisposableVM). It retrieves the filename from `/home/user/.dvm/SEQ`, and copies data from `/dev/xvdh` to it.

developer/services/qmemman.md

@@ -18,8 +18,8 @@ Traditionally, Xen VMs are assigned a fixed amount of memory. It is not the opti
 
 The [tmem](https://oss.oracle.com/projects/tmem/) project provides a "pseudo-RAM" that is assigned on per-need basis. However this solution has some disadvantages:
 
--   It does not provide real RAM, just an interface to copy memory to/from fast, RAM-based storage. It is perfect for swap, good for file cache, but not ideal for many tasks.
+- It does not provide real RAM, just an interface to copy memory to/from fast, RAM-based storage. It is perfect for swap, good for file cache, but not ideal for many tasks.
--   It is deeply integrated with the Linux kernel. When Qubes will support Windows guests natively, we would have to port *tmem* to Windows, which may be challenging.
+- It is deeply integrated with the Linux kernel. When Qubes will support Windows guests natively, we would have to port *tmem* to Windows, which may be challenging.
 
 Therefore, in Qubes another solution is used. There is the *qmemman* dom0 daemon. All VMs report their memory usage (via xenstore) to *qmemman*, and it makes decisions on whether to balance memory across domains. The actual mechanism to add/remove memory from a domain (*xc.domain\_set\_target\_mem*) is already supported by both PV Linux guests and Windows guests (the latter via PV drivers).
 
@@ -27,24 +27,24 @@ Similarly, when there is need for Xen free memory (for instance, in order to cre
 
 To sum up, *qmemman* pros and cons. Pros:
 
--   provides automatic balancing of memory across participating PV and HVM domains, based on their memory demand
+- provides automatic balancing of memory across participating PV and HVM domains, based on their memory demand
--   works well in practice, with less than 1% CPU consumption in the idle case
+- works well in practice, with less than 1% CPU consumption in the idle case
--   simple, concise implementation
+- simple, concise implementation
 
 Cons:
 
--   the algorithm to calculate the memory requirement for a domain is necessarily simple, and may not closely reflect reality
+- the algorithm to calculate the memory requirement for a domain is necessarily simple, and may not closely reflect reality
--   *qmemman* is notified by a VM about memory usage change not more often than 10 times per second (to limit CPU overhead in VM). Thus, there can be up to 0.1s delay until qmemman starts to react to the new memory requirements
+- *qmemman* is notified by a VM about memory usage change not more often than 10 times per second (to limit CPU overhead in VM). Thus, there can be up to 0.1s delay until qmemman starts to react to the new memory requirements
--   it takes more time to obtain free Xen memory, as all participating domains need to instructed to yield memory
+- it takes more time to obtain free Xen memory, as all participating domains need to instructed to yield memory
 
 Interface
 ---------
 
 *qmemman* listens for the following events:
 
--   writes to `/local/domain/domid/memory/meminfo` xenstore keys by *meminfo-writer* process in VM. The content of this key is taken from the VM's `/proc/meminfo` pseudofile ; *meminfo-writer* just strips some unused lines from it. Note that *meminfo-writer* writes its xenstore key only if the VM memory usage has changed significantly enough since the last update (by default 30MB), to prevent flooding with almost identical data
+- writes to `/local/domain/domid/memory/meminfo` xenstore keys by *meminfo-writer* process in VM. The content of this key is taken from the VM's `/proc/meminfo` pseudofile ; *meminfo-writer* just strips some unused lines from it. Note that *meminfo-writer* writes its xenstore key only if the VM memory usage has changed significantly enough since the last update (by default 30MB), to prevent flooding with almost identical data
--   commands issued over Unix socket `/var/run/qubes/qmemman.sock`. Currently, the only command recognized is to free the specified amount of memory. The QMemmanClient class implements the protocol.
+- commands issued over Unix socket `/var/run/qubes/qmemman.sock`. Currently, the only command recognized is to free the specified amount of memory. The QMemmanClient class implements the protocol.
--   if the `/var/run/qubes/do-not-membalance` file exists, *qmemman* suspends memory balancing. It is primarily used when allocating memory for a to-be-created domain, to prevent using up the free Xen memory by the balancing algorithm before the domain creation is completed.
+- if the `/var/run/qubes/do-not-membalance` file exists, *qmemman* suspends memory balancing. It is primarily used when allocating memory for a to-be-created domain, to prevent using up the free Xen memory by the balancing algorithm before the domain creation is completed.
 
 Algorithms basics
 -----------------
@@ -53,28 +53,27 @@ The core VM property is `prefmem`. It denotes the amount of memory that should b
 
 Whenever *meminfo-writer* running in domain A provides new data on memory usage to *qmemman*, the `prefmem` value for A is updated and the following balance algorithm (*qmemman\_algo.balance*) is triggered. Its output is the list of (domain\_id, new\_memory\_target\_to\_be\_set) pairs:
 
-1.  TOTAL\_PREFMEM = sum of `prefmem` of all participating domains
+1. TOTAL\_PREFMEM = sum of `prefmem` of all participating domains
-2.  TOTAL\_MEMORY = sum of all memory assigned to participating domains plus Xen free memory
+2. TOTAL\_MEMORY = sum of all memory assigned to participating domains plus Xen free memory
-3.  if TOTAL\_MEMORY \> TOTAL\_PREFMEM, then redistribute TOTAL\_MEMORY across all domains proportionally to their `prefmem`
+3. if TOTAL\_MEMORY \> TOTAL\_PREFMEM, then redistribute TOTAL\_MEMORY across all domains proportionally to their `prefmem`
-4.  if TOTAL\_MEMORY \< TOTAL\_PREFMEM, then
+4. if TOTAL\_MEMORY \< TOTAL\_PREFMEM, then
-    1.  for all domains whose `prefmem` is less than actual memory, shrink them to their `prefmem`
+    1. for all domains whose `prefmem` is less than actual memory, shrink them to their `prefmem`
-    2.  redistribute memory reclaimed in the previous step between the rest of domains, proportionally to their `prefmem`
+    2. redistribute memory reclaimed in the previous step between the rest of domains, proportionally to their `prefmem`
 
 In order to avoid too frequent memory redistribution, it is actually executed only if one of the below conditions hold:
 
--   the sum of memory size changes for all domains is more than MIN\_TOTAL\_MEMORY\_TRANSFER (150MB)
+- the sum of memory size changes for all domains is more than MIN\_TOTAL\_MEMORY\_TRANSFER (150MB)
--   one of the domains is below its `prefmem`, and more than MIN\_MEM\_CHANGE\_WHEN\_UNDER\_PREF (15MB) would be added to it
+- one of the domains is below its `prefmem`, and more than MIN\_MEM\_CHANGE\_WHEN\_UNDER\_PREF (15MB) would be added to it
 
 Additionally, the balance algorithm is tuned so that XEN\_FREE\_MEM\_LEFT (50MB) is always left as Xen free memory, to make coherent memory allocations in driver domains work.
 
 Whenever *qmemman* is asked to return X megabytes of memory to Xen free pool, the following algorithm (*qmemman\_algo.balloon*) is executed:
 
-1.  find all domains ("donors") whose actual memory is greater than its `prefmem`
+1. find all domains ("donors") whose actual memory is greater than its `prefmem`
-2.  calculate how much memory can be reclaimed by shrinking donors to their `prefmem`. If it is less than X, return error.
+2. calculate how much memory can be reclaimed by shrinking donors to their `prefmem`. If it is less than X, return error.
-3.  shrink donors, proportionally to their `prefmem`, so that X MB should become free
+3. shrink donors, proportionally to their `prefmem`, so that X MB should become free
-4.  wait BALOON\_DELAY (0.1s)
+4. wait BALOON\_DELAY (0.1s)
-5.  if some domain have not given back any memory, remove it from the donors list, and go to step 2, unless we already did MAX\_TRIES (20) iterations (then return error).
+5. if some domain have not given back any memory, remove it from the donors list, and go to step 2, unless we already did MAX\_TRIES (20) iterations (then return error).
-
 
 Notes
 -----

developer/services/qrexec-internals.md

@@ -32,6 +32,7 @@ These tools are not designed to be used by users directly.
 
 One instance is required for every active domain.
 `qrexec-daemon` is responsible for both:
+
 - handling execution and service requests from **dom0** (source: `qrexec-client`); and
 - handling service requests from the associated domain (source: `qrexec-client-vm`, then `qrexec-agent`).
 
@@ -39,9 +40,9 @@ Command line usage:
 
 `qrexec-daemon domain-id domain-name [default user]`
 
-* `domain-id`: Numeric Qubes ID assigned to the associated domain.
+- `domain-id`: Numeric Qubes ID assigned to the associated domain.
-* `domain-name`: Associated domain name.
+- `domain-name`: Associated domain name.
-* `default user`: Optional. If passed, `qrexec-daemon` uses this user as default for all execution requests that don't specify one.
+- `default user`: Optional. If passed, `qrexec-daemon` uses this user as default for all execution requests that don't specify one.
 
 ### qrexec-client
 
@@ -51,11 +52,11 @@ Used to pass execution and service requests to `qrexec-daemon`.
 
 Command line usage:
 
-* `-d target-domain-name`: Specifies the target for the execution/service request.
+- `-d target-domain-name`: Specifies the target for the execution/service request.
-* `-l local-program`: Optional. If present, `local-program` is executed and its stdout/stdin are used when sending/receiving data to/from the remote peer.
+- `-l local-program`: Optional. If present, `local-program` is executed and its stdout/stdin are used when sending/receiving data to/from the remote peer.
-* `-e`: Optional. If present, stdout/stdin are not connected to the remote   peer. Only process creation status code is received.
+- `-e`: Optional. If present, stdout/stdin are not connected to the remote   peer. Only process creation status code is received.
-* `-c <request-id,src-domain-name,src-domain-id>`: used for connecting a VM-VM service request by `qrexec-policy`. Details described below in the service example.
+- `-c <request-id,src-domain-name,src-domain-id>`: used for connecting a VM-VM service request by `qrexec-policy`. Details described below in the service example.
-* `cmdline`: Command line to pass to `qrexec-daemon` as the execution/service request. Service request format is described below in the service example.
+- `cmdline`: Command line to pass to `qrexec-daemon` as the execution/service request. Service request format is described below in the service example.
 
 ## VM tools implementation
 
@@ -65,8 +66,9 @@ Command line usage:
 
 One instance runs in each active domain.
 Responsible for:
-  * Handling service requests from `qrexec-client-vm` and passing them to connected `qrexec-daemon` in dom0.
+
-  * Executing associated `qrexec-daemon` execution/service requests.
+- Handling service requests from `qrexec-client-vm` and passing them to connected `qrexec-daemon` in dom0.
+- Executing associated `qrexec-daemon` execution/service requests.
 
 The `qrexec-agent` command takes no parameters.
 
@@ -81,26 +83,30 @@ Command line usage:
 
 `qrexec-client-vm target-domain-name service-name local-program [local program arguments]`
 
-* `target-domain-name`: Target domain for the service request. Source is the current domain.
+- `target-domain-name`: Target domain for the service request. Source is the current domain.
-* `service-name`: Requested service name.
+- `service-name`: Requested service name.
-* `local-program`: `local-program` is executed locally and its stdin/stdout are connected to the remote service endpoint.
+- `local-program`: `local-program` is executed locally and its stdin/stdout are connected to the remote service endpoint.
 
 ## Qrexec protocol details
 
 The qrexec protocol is message-based.
 All messages share a common header followed by an optional data packet.
 
-    /* uniform for all peers, data type depends on message type */
+```c
-    struct msg_header {
+/* uniform for all peers, data type depends on message type */
-       uint32_t type;           /* message type */
+struct msg_header {
-       uint32_t len;            /* data length */
+   uint32_t type;           /* message type */
-    };
+   uint32_t len;            /* data length */
+};
+```
 
 When two peers establish connection, the server sends `MSG_HELLO` followed by `peer_info` struct:
 
-    struct peer_info {
+```c
-       uint32_t version; /* qrexec protocol version */
+struct peer_info {
-    };
+   uint32_t version; /* qrexec protocol version */
+};
+```
 
 The client then should reply with its own `MSG_HELLO` and `peer_info`.
 The lower of two versions define protocol used for this connection.

developer/services/qrexec-socket-services.md

@@ -20,11 +20,15 @@ If the file is a Unix socket, qrexec will try to connect to it.
 Before passing user input, the socket service will receive a null-terminated service descriptor, i.e. the part after `QUBESRPC`.
 When running in a VM, this is:
 
+```
     <service_name> <source>\0
+```
 
 When running in dom0, it is:
 
+```
     <service_name> <source> <target_type> <target>\0
+```
 
 (The target type can be `name`, in which case target is a domain name, or `keyword`, in which the target is a keyword like `@dispvm`).
 

developer/services/qrexec2.md

@@ -17,7 +17,6 @@ Qubes **qrexec** is a framework for implementing inter-VM (incl. Dom0-VM)
 services. It offers a mechanism to start programs in VMs, redirect their
 stdin/stdout, and a policy framework to control this all.
 
-
 ## Qrexec basics ##
 
 During each domain creation a process named `qrexec-daemon` is started in
@@ -31,7 +30,9 @@ the stdin/stdout/stderr from this remote process will be passed to the
 
 E.g., to start a primitive shell in a VM type the following in Dom0 console:
 
+```shell_session
     [user@dom0 ~]$ /usr/lib/qubes/qrexec-client -d <vm name> user:bash
+```
 
 The string before first semicolon specifies what user to run the command as.
 
@@ -55,7 +56,6 @@ There is a similar command line utility available inside Linux AppVMs (note
 the `-vm` suffix): `qrexec-client-vm` that will be described in subsequent
 sections.
 
-
 ## Qubes RPC services ##
 
 Apart from simple Dom0-\>VM command executions, as discussed above, it is
@@ -90,7 +90,6 @@ themselves. Qrexec framework is careful about connecting the stdin/stdout
 of the server process with the corresponding stdin/stdout of the requesting
 process in the requesting VM (see example Hello World service described below).
 
-
 ## Qubes RPC administration ##
 
 Besides each VM needing to provide explicit programs to serve each supported
@@ -100,6 +99,7 @@ In dom0, there is a bunch of files in `/etc/qubes-rpc/policy/` directory,
 whose names describe the available RPC actions; their content is the RPC
 access policy database. Some example of the default services in Qubes are:
 
+```
     qubes.Filecopy
     qubes.OpenInVM
     qubes.ReceiveUpdates
@@ -109,10 +109,13 @@ access policy database. Some example of the default services in Qubes are:
     qubes.Gpg
     qubes.NotifyUpdates
     qubes.PdfConvert
+```
 
 These files contain lines with the following format:
 
+```
     srcvm destvm (allow|deny|ask)[,user=user_to_run_as][,target=VM_to_redirect_to]
+```
 
 You can specify `srcvm` and `destvm` by name, or by one of `$anyvm`,
 `$dispvm`, `dom0` reserved keywords (note string `dom0` does not match the
@@ -132,12 +135,13 @@ if still there is no policy file after prompting, the action is denied.
 On the target VM, the `/etc/qubes-rpc/XYZ` must exist, containing the file
 name of the program that will be invoked.
 
-
 ### Requesting VM-VM (and VM-Dom0) services execution ###
 
 In a src VM, one should invoke the qrexec client via the following command:
 
+```
     /usr/lib/qubes/qrexec-client-vm <target vm name> <service name> <local program path> [local program arguments]
+```
 
 Note that only stdin/stdout is passed between RPC server and client --
 notably, no cmdline argument are passed.
@@ -169,7 +173,9 @@ to the policy file, which will unconditionally allow further calls for given
 In order to remove such authorization, issue this command from a Dom0 terminal
 (example below for `qubes.Filecopy` service):
 
+```shell_session
     sudo nano /etc/qubes-rpc/policy/qubes.Filecopy
+```
 
 and then remove any line(s) ending in "allow" (before the first `##` comment)
 which are the "Yes to All" results.
@@ -178,35 +184,44 @@ A user might also want to set their own policies in this section. This may
 mostly serve to prevent the user from mistakenly copying files or text from
 a trusted to untrusted domain, or vice-versa.
 
-
 ### Qubes RPC "Hello World" service ###
 
 We will show the necessary files to create a simple RPC call that adds two
 integers on the target VM and returns back the result to the invoking VM.
 
- * Client code on source VM (`/usr/bin/our_test_add_client`)
+* Client code on source VM (`/usr/bin/our_test_add_client`)
 
+```bash
         #!/bin/sh
         echo $1 $2    # pass data to rpc server
         exec cat >&$SAVED_FD_1 # print result to the original stdout, not to the other rpc endpoint
+```
 
- * Server code on target VM (`/usr/bin/our_test_add_server`)
+* Server code on target VM (`/usr/bin/our_test_add_server`)
 
+```bash
         #!/bin/sh
         read arg1 arg2 # read from stdin, which is received from the rpc client
         echo $(($arg1+$arg2)) # print to stdout - so, pass to the rpc client
+```
 
- * Policy file in dom0 (`/etc/qubes-rpc/policy/test.Add`)
+* Policy file in dom0 (`/etc/qubes-rpc/policy/test.Add`)
 
+```shell_session
         $anyvm $anyvm ask
+```
 
- * Server path definition on target VM (`/etc/qubes-rpc/test.Add`)
+* Server path definition on target VM (`/etc/qubes-rpc/test.Add`)
 
+```
         /usr/bin/our_test_add_server
+```
 
- * To test this service, run the following in the source VM:
+* To test this service, run the following in the source VM:
 
+```
         /usr/lib/qubes/qrexec-client-vm <target VM> test.Add /usr/bin/our_test_add_client 1 2
+```
 
 and we should get "3" as answer, provided dom0 policy allows the call to pass
 through, which would happen after we click "Yes" in the popup that should
@@ -227,7 +242,6 @@ users/app developers are always free to run more high-level RPC protocols on
 top of qrexec. Care should be taken, however, to consider potential attack
 surfaces that are exposed to untrusted or less trusted VMs in that case.
 
-
 # Qubes RPC internals #
 
 (*This is about the implementation of qrexec v2. For the implementation of
@@ -235,52 +249,48 @@ qrexec v3, see [here](/doc/qrexec-internals/). Note that the user
 API in v3 is backward compatible: qrexec apps written for Qubes R2 should
 run without modification on Qubes R3.*)
 
-
 ## Dom0 tools implementation ##
 
 Players:
 
- * `/usr/lib/qubes/qrexec-daemon`: started by mgmt stack (qubes.py) when a
+* `/usr/lib/qubes/qrexec-daemon`: started by mgmt stack (qubes.py) when a
  VM is started.
- * `/usr/lib/qubes/qrexec-policy`: internal program used to evaluate the
+* `/usr/lib/qubes/qrexec-policy`: internal program used to evaluate the
  policy file and making the 2nd half of the connection.
- * `/usr/lib/qubes/qrexec-client`: raw command line tool that talks to the
+* `/usr/lib/qubes/qrexec-client`: raw command line tool that talks to the
  daemon via unix socket (`/var/run/qubes/qrexec.XID`)
 
 **Note:** None of the above tools are designed to be used by users.
 
-
 ## Linux VMs implementation ##
 
 Players:
 
- * `/usr/lib/qubes/qrexec-agent`: started by VM bootup scripts, a daemon.
+* `/usr/lib/qubes/qrexec-agent`: started by VM bootup scripts, a daemon.
- * `/usr/lib/qubes/qubes-rpc-multiplexer`: executes the actual service program,
+* `/usr/lib/qubes/qubes-rpc-multiplexer`: executes the actual service program,
  as specified in VM's `/etc/qubes-rpc/qubes.XYZ`.
- * `/usr/lib/qubes/qrexec-client-vm`: raw command line tool that talks to
+* `/usr/lib/qubes/qrexec-client-vm`: raw command line tool that talks to
  the agent.
 
 **Note:** None of the above tools are designed to be used by
 users. `qrexec-client-vm` is designed to be wrapped up by Qubes apps.
 
-
 ## Windows VMs implementation ##
 
 `%QUBES_DIR%` is the installation path (`c:\Program Files\Invisible Things
 Lab\Qubes OS Windows Tools` by default).
 
- * `%QUBES_DIR%\bin\qrexec-agent.exe`: runs as a system service. Responsible
+* `%QUBES_DIR%\bin\qrexec-agent.exe`: runs as a system service. Responsible
  both for raw command execution and interpreting RPC service requests.
- * `%QUBES_DIR%\qubes-rpc`: directory with `qubes.XYZ` files that contain
+* `%QUBES_DIR%\qubes-rpc`: directory with `qubes.XYZ` files that contain
  commands for executing RPC services. Binaries for the services are contained
  in `%QUBES_DIR%\qubes-rpc-services`.
- * `%QUBES_DIR%\bin\qrexec-client-vm`: raw command line tool that talks to
+* `%QUBES_DIR%\bin\qrexec-client-vm`: raw command line tool that talks to
  the agent.
 
 **Note:** None of the above tools are designed to be used by
 users. `qrexec-client-vm` is designed to be wrapped up by Qubes apps.
 
-
 ## All the pieces together at work ##
 
 **Note:** This section is not needed to use qrexec for writing Qubes
@@ -298,30 +308,30 @@ vchan connections.
 When a user in a source VM executes `qrexec-client-vm` utility, the following
 steps are taken:
 
- * `qrexec-client-vm` connects to `qrexec-agent`'s
+* `qrexec-client-vm` connects to `qrexec-agent`'s
  `/var/run/qubes/qrexec-agent-fdpass` unix socket 3 times. Reads 4 bytes from
  each of them, which is the fd number of the accepted socket in agent. These
  3 integers, in text, concatenated, form "connection identifier" (CID)
- * `qrexec-client-vm` writes to `/var/run/qubes/qrexec-agent` fifo a blob,
+* `qrexec-client-vm` writes to `/var/run/qubes/qrexec-agent` fifo a blob,
  consisting of target vmname, rpc action, and CID
- * `qrexec-client-vm` executes the rpc client, passing the above mentioned
+* `qrexec-client-vm` executes the rpc client, passing the above mentioned
  unix sockets as process stdin/stdout, and optionally stderr (if the
  `PASS_LOCAL_STDERR` env variable is set)
- * `qrexec-agent` passes the blob to `qrexec-daemon`, via
+* `qrexec-agent` passes the blob to `qrexec-daemon`, via
  `MSG_AGENT_TO_SERVER_TRIGGER_CONNECT_EXISTING` message over vchan
- * `qrexec-daemon` executes `qrexec-policy`, passing source vmname, target
+* `qrexec-daemon` executes `qrexec-policy`, passing source vmname, target
  vmname, rpc action, and CID as cmdline arguments
- * `qrexec-policy` evaluates the policy file. If successful, creates a pair of
+* `qrexec-policy` evaluates the policy file. If successful, creates a pair of
  `qrexec-client` processes, whose stdin/stdout are cross-connected.
-   * The first `qrexec-client` connects to the src VM, using the `-c ClientID`
+  * The first `qrexec-client` connects to the src VM, using the `-c ClientID`
    parameter, which results in not creating a new process, but connecting to
    the existing process file descriptors (these are the fds of unix socket
    created in step 1).
-   * The second `qrexec-client` connects to the target VM, and executes
+  * The second `qrexec-client` connects to the target VM, and executes
    `qubes-rpc-multiplexer` command there with the rpc action as the cmdline
    argument. Finally, `qubes-rpc-multiplexer` executes the correct rpc server
    on the target.
- * In the above step, if the target VM is `$dispvm`, the DispVM is created
+* In the above step, if the target VM is `$dispvm`, the DispVM is created
  via the `qfile-daemon-dvm` program. The latter waits for the `qrexec-client`
  process to exit, and then destroys the DispVM.
 

developer/system/architecture.md

@@ -18,25 +18,23 @@ Qubes implements a Security by Isolation approach. To do this, Qubes utilizes vi
 
 Qubes lets the user define many security domains, which are implemented as lightweight Virtual Machines (VMs), or “AppVMs.” For example, the user can have “personal,” “work,” “shopping,” “bank,” and “random” AppVMs and can use the applications within those VMs just as if they were executing on the local machine. At the same time, however, these applications are well isolated from each other. Qubes also supports secure copy-and-paste and file sharing between the AppVMs, of course.
 
-
 Key Architecture features
 -------------------------
 
--   Based on a secure bare-metal hypervisor (Xen)
+- Based on a secure bare-metal hypervisor (Xen)
--   Networking code sand-boxed in an unprivileged VM (using IOMMU/VT-d)
+- Networking code sand-boxed in an unprivileged VM (using IOMMU/VT-d)
--   USB stacks and drivers sand-boxed in an unprivileged VM (currently experimental feature)
+- USB stacks and drivers sand-boxed in an unprivileged VM (currently experimental feature)
--   No networking code in the privileged domain (dom0)
+- No networking code in the privileged domain (dom0)
--   All user applications run in “AppVMs,” lightweight VMs based on Linux
+- All user applications run in “AppVMs,” lightweight VMs based on Linux
--   Centralized updates of all AppVMs based on the same template
+- Centralized updates of all AppVMs based on the same template
--   Qubes GUI virtualization presents applications as if they were running locally
+- Qubes GUI virtualization presents applications as if they were running locally
--   Qubes GUI provides isolation between apps sharing the same desktop
+- Qubes GUI provides isolation between apps sharing the same desktop
--   Secure system boot based (optional)
+- Secure system boot based (optional)
 
 (For those interested in the history of the project, [Architecture Spec v0.3 [PDF]](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf) is the original 2009 document that started this all.
 Please note that this document is for historical interest only.
 For the latest information, please see the rest of the [System Documentation](/doc/#system).)
 
-
 Qubes Core Stack
 ----------------
 
@@ -45,26 +43,26 @@ the glue that connects all the other components together, and which allows users
 and admins to interact with and configure the system. The other components of
 the Qubes system include:
 
- - VM-located core agents (implementing e.g. qrexec endpoints used by various
+- VM-located core agents (implementing e.g. qrexec endpoints used by various
-   Qubes services)
+  Qubes services)
- - VM-customizations (making the VMs lightweight and working well with seamless
+- VM-customizations (making the VMs lightweight and working well with seamless
-   GUI virtualization)
+  GUI virtualization)
- - Qubes GUI virtualization (the protocol, VM-located agents, and daemons
+- Qubes GUI virtualization (the protocol, VM-located agents, and daemons
-   located in the GUI domain which, for now, happens to be the same as dom0),
+  located in the GUI domain which, for now, happens to be the same as dom0),
- - GUI domain customizations (Desktop Environment customizations, decoration
+- GUI domain customizations (Desktop Environment customizations, decoration
-   coloring plugin, etc)
+  coloring plugin, etc)
- - The AdminVM distribution (various customizations, special services, such as
+- The AdminVM distribution (various customizations, special services, such as
-   for receiving and verifying updates, in the future: custom distro)
+  for receiving and verifying updates, in the future: custom distro)
- - The Xen hypervisor (with a bunch of customization patches, occasional
+- The Xen hypervisor (with a bunch of customization patches, occasional
-   hardening) or - in the future - some other virtualising or containerizing
+  hardening) or - in the future - some other virtualising or containerizing
-   software or technology
+  software or technology
- - Multiple "Qubes Apps" (various services built on top of Qubes qrexec
+- Multiple "Qubes Apps" (various services built on top of Qubes qrexec
-   infrastructure, such as: trusted PDF and Image converters, Split GPG, safe
+  infrastructure, such as: trusted PDF and Image converters, Split GPG, safe
-   USB proxies for HID devices, USB proxy for offering USB devices (exposed via
+  USB proxies for HID devices, USB proxy for offering USB devices (exposed via
-   qvm-usb), Yubikey support, USB Armory support, etc)
+  qvm-usb), Yubikey support, USB Armory support, etc)
- - Various ready-to-use templates (e.g. Debian-, Whonix-based), which are used
+- Various ready-to-use templates (e.g. Debian-, Whonix-based), which are used
-   to create actual VMs, i.e. provide the root filesystem to the VMs
+  to create actual VMs, i.e. provide the root filesystem to the VMs
- - Salt Stack integration
+- Salt Stack integration
 
 And all these components are "glued together" by the Qubes Core Stack.
 

developer/system/audio.md

@@ -10,8 +10,8 @@ Audio Virtualization
 VMs on Qubes OS have access to virtualized audio through the PulseAudio module.
 It consists of two parts:
 
- - `pacat-simple-vchan` running in a dom0/Audio VM (standalone application, one per VM, connected to the PulseAudio daemon)
+- `pacat-simple-vchan` running in a dom0/Audio VM (standalone application, one per VM, connected to the PulseAudio daemon)
- - `module-vchan-sink` running in a VM (loaded into the PulseAudio process)
+- `module-vchan-sink` running in a VM (loaded into the PulseAudio process)
 
 Protocol
 --------
@@ -33,10 +33,10 @@ Each such notification is a 4-byte number in little-endian format.
 
 List of defined codes:
 
- - `0x00010001` -- VM wants to receive audio input (some process is listening); prior to this message, `pacat-simple-vchan` will not send any audio samples to the VM.
+- `0x00010001` -- VM wants to receive audio input (some process is listening); prior to this message, `pacat-simple-vchan` will not send any audio samples to the VM.
- - `0x00010000` -- VM does not want to receive audio input (no process is listening anymore); after this message, `pacat-simple-vchan` will not send any audio samples to the VM.
+- `0x00010000` -- VM does not want to receive audio input (no process is listening anymore); after this message, `pacat-simple-vchan` will not send any audio samples to the VM.
- - `0x00020000` -- VM does not want to send audio output; informational for dom0, to avoid buffer under runs (may affect PulseAudio calculated delays).
+- `0x00020000` -- VM does not want to send audio output; informational for dom0, to avoid buffer under runs (may affect PulseAudio calculated delays).
- - `0x00020001` -- VM does want to send audio output.
+- `0x00020001` -- VM does want to send audio output.
 
 pacat-simple-vchan
 ------------------
@@ -52,20 +52,19 @@ It needs to be both requested by the VM part and explicitly enabled in `pacat-si
 The mechanism to do this differs between Qubes versions.
 In Qubes before R4.1, `pacat-simple-vchan` is controlled over system D-Bus:
 
-  - destination: `org.qubesos.Audio.VMNAME` (where `VMNAME` is the VM's name)
+- destination: `org.qubesos.Audio.VMNAME` (where `VMNAME` is the VM's name)
-  - object path: `/org/qubesos/audio`
+- object path: `/org/qubesos/audio`
-  - interface: `org.qubesos.Audio`
+- interface: `org.qubesos.Audio`
-  - property: `RecAllowed` (which can be set using the `org.freedesktop.DBus.Properties` interface)
+- property: `RecAllowed` (which can be set using the `org.freedesktop.DBus.Properties` interface)
 
 In Qubes R4.1 and later, `pacat-simple-vchan` is controlled over a UNIX socket at `/var/run/qubes/audio-control.VMNAME` (where `VMNAME` is the VM's name).
 Supported commands:
 
-  - `audio-input 1\n` - enable audio input
+- `audio-input 1\n` - enable audio input
-  - `audio-input 0\n` - disable audio input
+- `audio-input 0\n` - disable audio input
 
 These commands can be sent using the `qubes.AudioInputEnable+VMNAME` and `qubes.AudioInputDisable+VMNAME` qrexec services, respectively.
 The current status is written into QubesDB at `/audio-input/VMNAME` (where `VMNAME` is the VM's name) with either `1` or `0` values.
 The lack of a key means that the `pacat-simple-vchan` for a given VM is not running.
 
 In either version, it is exposed to the user as device of class `mic`, which can be attached to a VM (for example, using the `qvm-device mic` command).
-

developer/system/gui.md

@@ -17,23 +17,23 @@ qubes_gui and qubes_guid processes
 
 All AppVM X applications connect to local (running in AppVM) Xorg servers that use the following "hardware" drivers:
 
--   *dummyqsb_drv* - video driver, that paints onto a framebuffer located in RAM, not connected to real hardware
+- *dummyqsb_drv* - video driver, that paints onto a framebuffer located in RAM, not connected to real hardware
--   *qubes_drv* - it provides a virtual keyboard and mouse (in fact, more, see below)
+- *qubes_drv* - it provides a virtual keyboard and mouse (in fact, more, see below)
 
 For each AppVM, there is a pair of *qubes_gui* (running in AppVM) and *qubes_guid* (running in dom0) processes connected over vchan.
 The main responsibilities of *qubes_gui* are:
 
--   call XCompositeRedirectSubwindows on the root window, so that each window has its own composition buffer
+- call XCompositeRedirectSubwindows on the root window, so that each window has its own composition buffer
--   instruct the local Xorg server to notify it about window creation, configuration and damage events; pass information on these events to dom0
+- instruct the local Xorg server to notify it about window creation, configuration and damage events; pass information on these events to dom0
--   receive information about keyboard and mouse events from dom0, tell *qubes_drv* to fake appropriate events
+- receive information about keyboard and mouse events from dom0, tell *qubes_drv* to fake appropriate events
--   receive information about window size/position change, apply them to the local window
+- receive information about window size/position change, apply them to the local window
 
 The main responsibilities of *qubes_guid* are:
 
--   create a window in dom0 whenever an information on window creation in AppVM is received from *qubes_gui*
+- create a window in dom0 whenever an information on window creation in AppVM is received from *qubes_gui*
--   whenever the local window receives XEvent, pass information on it to AppVM (particularly, mouse and keyboard data)
+- whenever the local window receives XEvent, pass information on it to AppVM (particularly, mouse and keyboard data)
--   whenever AppVM signals damage event, tell local Xorg server to repaint a given window fragment
+- whenever AppVM signals damage event, tell local Xorg server to repaint a given window fragment
--   receive information about window size/position change, apply them to the local window
+- receive information about window size/position change, apply them to the local window
 
 Note that keyboard and mouse events are passed to AppVM only if a window belonging to this AppVM has focus.
 AppVM has no way to get information on keystrokes fed to other AppVMs (e.g. XTEST extension will report the status of local AppVM keyboard only) or synthesize and pass events to other AppVMs.
@@ -45,26 +45,26 @@ Typical remote desktop applications, like *vnc*, pass information on all changed
 As that channel has limited throughput, this impacts video performance.
 In the case of Qubes, *qubes_gui* does not transfer all changed pixels via vchan. Instead, for each window, upon its creation or size change, *qubes_gui*
 
--   asks *qubes_drv* driver for the list of physical memory frames that hold the composition buffer of a window
+- asks *qubes_drv* driver for the list of physical memory frames that hold the composition buffer of a window
--   passes this information via `MFNDUMP` message to *qubes_guid* in dom0
+- passes this information via `MFNDUMP` message to *qubes_guid* in dom0
 
 Now, *qubes_guid* has to tell the dom0 Xorg server about the location of the buffer.
 There is no supported way (e.g. Xorg extension) to do this zero-copy style.
 The following method is used in Qubes:
 
--   in dom0, the Xorg server is started with *LD_PRELOAD*-ed library named *shmoverride.so*. This library hooks all function calls related to shared memory.
+- in dom0, the Xorg server is started with *LD_PRELOAD*-ed library named *shmoverride.so*. This library hooks all function calls related to shared memory.
--   *qubes_guid* creates a shared memory segment, and then tells Xorg to attach it via *MIT-SHM* extension
+- *qubes_guid* creates a shared memory segment, and then tells Xorg to attach it via *MIT-SHM* extension
--   when Xorg tries to attach the segment (via glibc *shmat*) *shmoverride.so* intercepts this call and instead maps AppVM memory via *xc_map_foreign_pages*
+- when Xorg tries to attach the segment (via glibc *shmat*) *shmoverride.so* intercepts this call and instead maps AppVM memory via *xc_map_foreign_pages*
--   since then, we can use MIT-SHM functions, e.g. *XShmPutImage* to draw onto a dom0 window. *XShmPutImage* will paint with DRAM speed; actually, many drivers use DMA for this.
+- since then, we can use MIT-SHM functions, e.g. *XShmPutImage* to draw onto a dom0 window. *XShmPutImage* will paint with DRAM speed; actually, many drivers use DMA for this.
 
 The important detail is that *xc_map_foreign_pages* verifies that a given mfn range actually belongs to a given domain id (and the latter is provided by trusted *qubes_guid*).
 Therefore, rogue AppVM cannot gain anything by passing crafted mnfs in the `MFNDUMP` message.
 
 To sum up, this solution has the following benefits:
 
--   window updates at DRAM speed
+- window updates at DRAM speed
--   no changes to Xorg code
+- no changes to Xorg code
--   minimal size of the supporting code
+- minimal size of the supporting code
 
 ![gui.png](/attachment/wiki/GUIdocs/gui.png)
 
@@ -81,9 +81,9 @@ Clipboard sharing implementation
 Certainly, it would be insecure to allow AppVM to read/write the clipboards of other AppVMs unconditionally.
 Therefore, the following mechanism is used:
 
--   there is a "qubes clipboard" in dom0 - its contents are stored in a regular file in dom0.
+- there is a "qubes clipboard" in dom0 - its contents are stored in a regular file in dom0.
--   if the user wants to copy local AppVM clipboard to qubes clipboard, she must focus on any window belonging to this AppVM, and press **Ctrl-Shift-C**. This combination is trapped by *qubes-guid*, and `CLIPBOARD_REQ` message is sent to AppVM. *qubes-gui* responds with *CLIPBOARD_DATA* message followed by clipboard contents.
+- if the user wants to copy local AppVM clipboard to qubes clipboard, she must focus on any window belonging to this AppVM, and press **Ctrl-Shift-C**. This combination is trapped by *qubes-guid*, and `CLIPBOARD_REQ` message is sent to AppVM. *qubes-gui* responds with *CLIPBOARD_DATA* message followed by clipboard contents.
--   the user focuses on other AppVM window, presses **Ctrl-Shift-V**. This combination is trapped by *qubes-guid*, and `CLIPBOARD_DATA` message followed by qubes clipboard contents is sent to AppVM; *qubes_gui* copies data to the local clipboard, and then user can paste its contents to local applications normally.
+- the user focuses on other AppVM window, presses **Ctrl-Shift-V**. This combination is trapped by *qubes-guid*, and `CLIPBOARD_DATA` message followed by qubes clipboard contents is sent to AppVM; *qubes_gui* copies data to the local clipboard, and then user can paste its contents to local applications normally.
 
 This way, the user can quickly copy clipboards between AppVMs.
 This action is fully controlled by the user, it cannot be triggered/forced by any AppVM.
@@ -93,8 +93,8 @@ This action is fully controlled by the user, it cannot be triggered/forced by an
 
 Both applications are structured similarly. They use *select* function to wait for any of these two event sources:
 
--   messages from the local X server
+- messages from the local X server
--   messages from the vchan connecting to the remote party
+- messages from the vchan connecting to the remote party
 
 The XEvents are handled by the *handle_xevent_eventname* function, and messages are handled by *handle_messagename* function. One should be very careful when altering the actual *select* loop, because both XEvents and vchan messages are buffered, and  *select* will not wake for each message.
 
@@ -115,7 +115,7 @@ Window manager hints and flags are described in the [Extended Window Manager Hin
 
 Each message starts with the following header:
 
-~~~
+```c
 struct msghdr {
         uint32_t type;
         uint32_t window;
@@ -126,7 +126,7 @@ struct msghdr {
          * whatever it wants! */
         uint32_t untrusted_len;
 };
-~~~
+```
 
 This header is followed by message-specific data:
 
@@ -279,12 +279,12 @@ Proper handling of the below messages is NOT security-critical.
 
 Each message starts with the following header
 
-~~~
+```c
 struct msghdr {
         uint32_t type;
         uint32_t window;
 };
-~~~
+```
 
 The header is followed by message-specific data:
 

developer/system/networking.md

@@ -9,18 +9,15 @@ redirect_from:
 - /wiki/QubesNet/
 ---
 
-VM network in Qubes
+# VM network in Qubes
-===================
 
-Overall description
+## Overall description
--------------------
 
 In Qubes, the standard Xen networking is used, based on backend driver in the driver domain and frontend drivers in VMs. In order to eliminate layer 2 attacks originating from a compromised VM, routed networking is used instead of the default bridging of `vif` devices and NAT is applied at each network hop. The default *vif-route* script had some deficiencies (requires `eth0` device to be up, and sets some redundant iptables rules), therefore the custom *vif-route-qubes* script is used.
 
 The IP address of `eth0` interface in AppVM, as well as two IP addresses to be used as nameservers (`DNS1` and `DNS2`), are passed via QubesDB to AppVM during its boot (thus, there is no need for DHCP daemon in the network driver domain). `DNS1` and `DNS2` are private addresses; whenever an interface is brought up in the network driver domain, the */usr/lib/qubes/qubes\_setup\_dnat\_to\_ns* script sets up the DNAT iptables rules translating `DNS1` and `DNS2` to the newly learned real dns servers. This way AppVM networking configuration does not need to be changed when configuration in the network driver domain changes (e.g. user switches to a different WLAN). Moreover, in the network driver domain, there is no DNS server either, and consequently there are no ports open to the VMs.
 
-Routing tables examples
+## Routing tables examples
------------------------
 
 VM routing table is simple:
 
@@ -40,18 +37,21 @@ Network driver domain routing table is a bit longer:
 |192.168.0.0|0.0.0.0|255.255.255.0|U|1|0|0|eth0|
 |0.0.0.0|192.168.0.1|0.0.0.0|UG|0|0|0|eth0|
 
-IPv6
+## IPv6
-----
 
 Starting with Qubes 4.0, there is opt-in support for IPv6 forwarding. Similar to the IPv4, traffic is routed and NAT is applied at each network gateway. This way we avoid reconfiguring every connected qube whenever uplink connection is changed, and even telling the qube what that uplink is - which may be complex when VPN or other tunneling services are employed.
 The feature can be enabled on any network-providing qube, and will be propagated down the network tree, so every qube connected to it will also have IPv6 enabled.
 To enable the `ipv6` feature use `qvm-features` tool and set the value to `1`. For example to enable it on `sys-net`, execute in dom0:
 
+```
     qvm-features sys-net ipv6 1
+```
 
 It is also possible to explicitly disable IPv6 support for some qubes, even if it is connected to IPv6-providing one. This can be done by setting `ipv6` feature to empty value:
 
+```
     qvm-features ipv4-only-qube ipv6 ''
+```
 
 This configuration is presented below - green qubes have IPv6 access, red one does not.
 
@@ -64,8 +64,7 @@ Such configuration can be expressed by enabling `ipv6` feature only on some subs
 
 Besides enabling IPv6 forwarding, standard Qubes firewall can be used to limit what network resources are available to each qube. Currently only `qvm-firewall` command support adding IPv6 rules, GUI firewall editor will have this ability later.
 
-### Limitations ###
+### Limitations
 
 Currently only IPv4 DNS servers are configured, regardless of `ipv6` feature state. It is done this way to avoid reconfiguring all connected qubes whenever IPv6 DNS becomes available or not. Configuring qubes to always use IPv6 DNS and only fallback to IPv4 may result in relatively long timeouts and poor usability.
 But note that DNS using IPv4 does not prevent to return IPv6 addresses. In practice this is only a problem for IPv6-only networks.
-

developer/system/security-critical-code.md

@@ -21,20 +21,18 @@ The size of the current TCB is on the order order of hundreds of thousands of li
 
 For more information, see [Qubes Security Goals].
 
-
 Security-critical Qubes-specific Components
 -------------------------------------------
 
 The following code components are security-critical in Qubes OS:
 
- - Dom0-side of the libvchan library
+- Dom0-side of the libvchan library
- - Dom0-side of the GUI virtualization code (`qubes-guid`)
+- Dom0-side of the GUI virtualization code (`qubes-guid`)
- - Dom0-side of the sound virtualization code (`pacat-simple-vchan`)
+- Dom0-side of the sound virtualization code (`pacat-simple-vchan`)
- - Dom0-side in qrexec-related code (`qrexec_daemon`)
+- Dom0-side in qrexec-related code (`qrexec_daemon`)
- - VM memory manager (`qmemman`) that runs in Dom0
+- VM memory manager (`qmemman`) that runs in Dom0
- - Select Qubes RPC servers that run in Dom0: `qubes.ReceiveUpdates` and `qubes.SyncAppMenus`
+- Select Qubes RPC servers that run in Dom0: `qubes.ReceiveUpdates` and `qubes.SyncAppMenus`
- - The `qubes.Filecopy` RPC server that runs in a VM (critical because it could allow one VM to compromise another if the user allows a file copy operation to be performed between them)
+- The `qubes.Filecopy` RPC server that runs in a VM (critical because it could allow one VM to compromise another if the user allows a file copy operation to be performed between them)
-
 
 Security-critical Third-party Components
 ----------------------------------------
@@ -42,26 +40,24 @@ Security-critical Third-party Components
 We did not create these components, but Qubes OS relies on them.
 At the current stage of the project, we cannot afford to spend the time to thoroughly review and audit them, so we more or less "blindly" trust that they are secure.
 
- - The Xen hypervisor
+- The Xen hypervisor
- - Xen's xenstore backend running in Dom0
+- Xen's xenstore backend running in Dom0
- - Xen's block backend running in Dom0's kernel
+- Xen's block backend running in Dom0's kernel
- - The RPM program used in Dom0 for verifying signatures on dom0 updates
+- The RPM program used in Dom0 for verifying signatures on dom0 updates
- - Somewhat trusted: log viewing software in dom0 that parses VM-influenced logs
+- Somewhat trusted: log viewing software in dom0 that parses VM-influenced logs
-
 
 Attacks on Networking Components
 --------------------------------
 
 Here are two examples of networking components that an adversary might seek to attack (or in which to exploit a vulnerability as part of an attack):
 
- - Xen network PV frontends
+- Xen network PV frontends
- - VMs' core networking stacks (core TCP/IP code)
+- VMs' core networking stacks (core TCP/IP code)
 
 Hypothetically, an adversary could compromise a NetVM, `sys-net-1`, and try to use it to attack the VMs connected to that NetVM.
 However, Qubes allows for the existence of more than one NetVM, so the adversary would not be able to use `sys-net-1` in order to attack VMs connected to a *different* NetVM, `sys-net-2` without also compromising `sys-net-2`.
 In addition, the adversary would not be able to use `sys-net-1` (or, for that matter, `sys-net-2`) to attack VMs that have networking disabled (i.e., VMs that are not connected to any NetVM).
 
-
 Buggy Code vs. Backdoored Code
 ------------------------------
 
@@ -74,8 +70,6 @@ This means that we must trust at least some of the vendors that supply the code
 In practice, we trust the software provided by the [Fedora Project].
 This software is signed by Fedora distribution keys, so it is also critical that the tools used in domains for software updates (`dnf` and `rpm`) are trustworthy.
 
-
 [Qubes Security Goals]: /security/goals/
 [Fedora Project]: https://getfedora.org/
 [Understanding and Preventing Data Leaks]: /doc/data-leaks/
-

developer/system/storage-pools.md

@@ -32,7 +32,6 @@ When installed, the system has, as you can see from the contents of
 default pool is special in R3.2. It will add `dir_path=/var/lib/qubes`
 configuration value from `defaults[pool_config]`, if not overwritten.
 
-
 Currently the only supported driver out of the box is `xen`. The benefit of
 pools (besides that you can write your own storage driver e.g. for Btrfs) in R3.2
 is that you can store your domains in multiple places.

developer/system/template-implementation.md

@@ -8,59 +8,54 @@ redirect_from:
 - /wiki/TemplateImplementation/
 ---
 
-Overview of VM block devices
+# Overview of VM block devices
-============================
 
 Every VM has 4 block devices connected:
 
--   **xvda** – base root device (/) – details described below
+- **xvda** – base root device (/) – details described below
--   **xvdb** – private.img – place where VM always can write.
+- **xvdb** – private.img – place where VM always can write.
--   **xvdc** – volatile.img, discarded at each VM restart – here is placed swap and temporal "/" modifications (see below)
+- **xvdc** – volatile.img, discarded at each VM restart – here is placed swap and temporal "/" modifications (see below)
--   **xvdd** – modules.img – kernel modules and firmware
+- **xvdd** – modules.img – kernel modules and firmware
 
-private.img (xvdb)
+## private.img (xvdb)
-------------------
 
 This is mounted as /rw and here is placed all VM private data. This includes:
 
--   */home* – which is bind mounted to /rw/home
+- */home* – which is bind mounted to /rw/home
--   */usr/local* – which is symlink to /rw/usrlocal
+- */usr/local* – which is symlink to /rw/usrlocal
--   some config files (/rw/config) called by qubes core scripts (ex /rw/config/rc.local)
+- some config files (/rw/config) called by qubes core scripts (ex /rw/config/rc.local)
 
 **Note:** Whenever a TemplateBasedVM is created, the contents of the `/home` directory of its parent TemplateVM are copied to the child TemplateBasedVM's `/home`. From that point onward, the child TemplateBasedVM's `/home` is independent from its parent TemplateVM's `/home`, which means that any subsequent changes to the parent TemplateVM's `/home` will no longer affect the child TemplateBasedVM's `/home`. Once a TemplateBasedVM has been created, any changes in its `/home`, `/usr/local`, or `/rw/config` directories will be persistent across reboots, which means that any files stored there will still be available after restarting the TemplateBasedVM. No changes in any other directories in TemplateBasedVMs persist in this manner. If you would like to make changes in other directories which *do* persist in this manner, you must make those changes in the parent TemplateVM.
 
-modules.img (xvdd)
+## modules.img (xvdd)
-------------------
 
 As the kernel is chosen in dom0, there must be some way to provide matching kernel modules to VM. Qubes kernel directory consists of 3 files:
 
--   *vmlinuz* – actual kernel
+- *vmlinuz* – actual kernel
--   *initramfs* – initial ramdisk containing script to setup snapshot devices (see below) and mount /lib/modules
+- *initramfs* – initial ramdisk containing script to setup snapshot devices (see below) and mount /lib/modules
--   *modules.img* – filesystem image of /lib/modules with matching kernel modules and firmware (/lib/firmware/updates is symlinked to /lib/modules/firmware)
+- *modules.img* – filesystem image of /lib/modules with matching kernel modules and firmware (/lib/firmware/updates is symlinked to /lib/modules/firmware)
 
 Normally kernel "package" is common for many VMs (can be set using qvm-prefs). One of them can be set as default (qvm-set-default-kernel) to simplify kernel updates (by default all VMs use the default kernel). All installed kernels are placed in /var/lib/qubes/vm-kernels as separate subdirs. In this case, modules.img is attached to the VM as R/O device.
 
 There is a special case when the VM can have a custom kernel – when it is updateable (StandaloneVM or TemplateVM) and the kernel is set to "none" (by qvm-prefs). In this case the VM uses the kernel from the "kernels" VM subdir and modules.img is attached as R/W device. FIXME: "none" should be renamed to "custom".
 
-Qubes TemplateVM implementation
+# Qubes TemplateVM implementation
-===============================
 
 TemplateVM has a shared root.img across all AppVMs that are based on it. This mechanism has some advantages over a simple common device connected to multiple VMs:
 
--   root.img can be modified while there are AppVMs running – without corrupting the filesystem
+- root.img can be modified while there are AppVMs running – without corrupting the filesystem
--   multiple AppVMs that are using different versions of root.img (from various points in time) can be running concurrently
+- multiple AppVMs that are using different versions of root.img (from various points in time) can be running concurrently
 
 There are two layers of the device-mapper snapshot device; the first one enables modifying root.img without stopping the AppVMs and the second one, which is contained in the AppVM, enables temporal modifications to its filesystem. These modifications will be discarded after a restart of the AppVM.
 
 ![TemplateSharing2.png](/attachment/wiki/TemplateImplementation/TemplateSharing2.png)
 
-Snapshot device in Dom0
+## Snapshot device in Dom0
------------------------
 
 This device consists of:
 
--   root.img – real template filesystem
+- root.img – real template filesystem
--   root-cow.img – differences between the device as seen by AppVM and the current root.img
+- root-cow.img – differences between the device as seen by AppVM and the current root.img
 
 The above is achieved through creating device-mapper snapshots for each version of root.img. When an AppVM is started, a xen hotplug script (/etc/xen/scripts/block-snapshot) reads the inode numbers of root.img and root-cow.img; these numbers are used as the snapshot device's name. When a device with the same name exists the new AppVM will use it – therefore, AppVMs based on the same version of root.img will use the same device. Of course, the device-mapper cannot use the files directly – it must be connected through /dev/loop\*. The same mechanism detects if there is a loop device associated with a file determined by the device and inode numbers – or if creating a new loop device is necessary.
 
@@ -82,31 +77,29 @@ This is done using snapshot-merge device-mapper target (available from 2.6.34 ke
 
 Steps performed by **qvm-revert-template-changes**:
 
-1.  Ensure that no other VMs uses this template.
+1. Ensure that no other VMs uses this template.
-2.  Prepare snapshot device with ***root-cow.img.old*** instead of *root-cow.img* (*/etc/xen/scripts/block-snapshot prepare*).
+2. Prepare snapshot device with ***root-cow.img.old*** instead of *root-cow.img* (*/etc/xen/scripts/block-snapshot prepare*).
-3.  Replace *snapshot* device-mapper target with *snapshot-merge*, other parameters (chunk size etc) remains untouched. Now kernel starts merging changes stored in *root-cow.img.old* into *root.img*. d-m device can be used normally (if needed).
+3. Replace *snapshot* device-mapper target with *snapshot-merge*, other parameters (chunk size etc) remains untouched. Now kernel starts merging changes stored in *root-cow.img.old* into *root.img*. d-m device can be used normally (if needed).
-4.  Waits for merge completed: *dmsetup status* shows used snapshot blocks – it should be equal to metadata size when completed.
+4. Waits for merge completed: *dmsetup status* shows used snapshot blocks – it should be equal to metadata size when completed.
-5.  Replace *snapshot-merge* d-m target back to *snapshot*.
+5. Replace *snapshot-merge* d-m target back to *snapshot*.
-6.  Cleanup snapshot device (if nobody uses it at the moment).
+6. Cleanup snapshot device (if nobody uses it at the moment).
-7.  Move *root-cow.img.old* to *root-cow.img* (overriding existing file).
+7. Move *root-cow.img.old* to *root-cow.img* (overriding existing file).
 
-Snapshot device in AppVM
+## Snapshot device in AppVM
-------------------------
 
 Root device is exposed to AppVM in read-only mode. AppVM can write only in:
 
--   private.img – persistent storage (mounted in /rw) used for /home, /usr/local – in future versions, its use may be extended
+- private.img – persistent storage (mounted in /rw) used for /home, /usr/local – in future versions, its use may be extended
--   volatile.img – temporary storage, which is discarded after an AppVM restart
+- volatile.img – temporary storage, which is discarded after an AppVM restart
 
 volatile.img is divided into two partitions:
 
-1.  changes to root device
+1. changes to root device
-2.  swap partition
+2. swap partition
 
 Inside of an AppVM, the root device is wrapped by the snapshot in the first partition of volatile.img. Therefore, the AppVM can write anything to its filesystem – however, such changes will be discarded after a restart.
 
-StandaloneVM
+## StandaloneVM
-------------
 
 Standalone VM enables user to modify root filesystem persistently. It can be created using *--standalone* switch to *qvm-create*.
 

introduction/contributing.md

@@ -57,7 +57,6 @@ preferably via the [qubes-devel] mailing list. Once we've worked out the
 details, we'll add you to our [Community-Developed Feature Tracker]. We'll then
 be grateful to [receive your patch][patch].
 
-
 [source code]: /doc/source-code/
 [Report security issues]: /security/
 [patch]: /doc/source-code/#how-to-send-patches
@@ -79,4 +78,3 @@ be grateful to [receive your patch][patch].
 [qubes-devel]: /support/#qubes-devel
 [Community-Developed Feature Tracker]: /qubes-issues/
 [Qubes download mirror]: /downloads/mirrors/
-

introduction/faq.md

@@ -102,7 +102,6 @@ Booting your computer from a live CD (or DVD) when you need to perform sensitive
 For example, popular live OSes (such as [Tails] and other Linux distributions) are still **monolithic** in the sense that all software is still running in the same OS.
 This means, once again, that if your session is compromised, then all the data and activities performed within that same session are also potentially compromised.
 
-
 ### How does Qubes OS compare to running VMs in a conventional OS?
 
 Not all virtual machine software is equal when it comes to security.
@@ -121,7 +120,6 @@ Qubes makes it so that multiple VMs running under a Type 1 hypervisor can be sec
 For example, it puts all of your application windows on the same desktop with special colored borders indicating the trust levels of their respective VMs.
 It also allows for things like secure copy/paste operations between VMs, securely copying and transferring files between VMs, and secure networking between VMs and the Internet.
 
-
 ### How does Qubes OS compare to using a separate physical machine?
 
 Using a separate physical computer for sensitive activities can certainly be more secure than using one computer with a conventional OS for everything, but there are still risks to consider.
@@ -131,23 +129,22 @@ Briefly, here are some of the main pros and cons of this approach relative to Qu
   <i class="fa fa-check"></i> <strong>Pros</strong>
 </div>
 
- * Physical separation doesn't rely on a hypervisor. (It's very unlikely that an attacker will break out of Qubes' hypervisor, but if one were to manage to do so, one could potentially gain control over the entire system.)
+- Physical separation doesn't rely on a hypervisor. (It's very unlikely that an attacker will break out of Qubes' hypervisor, but if one were to manage to do so, one could potentially gain control over the entire system.)
- * Physical separation can be a natural complement to physical security.
+- Physical separation can be a natural complement to physical security.
-	(For example, you might find it natural to lock your secure laptop in a safe when you take your unsecure laptop out with you.)
+  (For example, you might find it natural to lock your secure laptop in a safe when you take your unsecure laptop out with you.)
 
 <div class="focus">
     <i class="fa fa-times"></i> <strong>Cons</strong>
 </div>
 
- * Physical separation can be cumbersome and expensive, since we may have to obtain and set up a separate physical machine for each security level we need.
+- Physical separation can be cumbersome and expensive, since we may have to obtain and set up a separate physical machine for each security level we need.
- * There's generally no secure way to transfer data between physically separate computers running conventional OSes.
+- There's generally no secure way to transfer data between physically separate computers running conventional OSes.
-	(Qubes has a secure inter-VM file transfer system to handle this.)
+  (Qubes has a secure inter-VM file transfer system to handle this.)
- * Physically separate computers running conventional OSes are still independently vulnerable to most conventional attacks due to their monolithic nature.
+- Physically separate computers running conventional OSes are still independently vulnerable to most conventional attacks due to their monolithic nature.
- * Malware which can bridge air gaps has existed for several years now and is becoming increasingly common.
+- Malware which can bridge air gaps has existed for several years now and is becoming increasingly common.
 
 (For more on this topic, please see the paper [Software compartmentalization vs. physical separation][paper-compart].)
 
-
 ### What is the main concept behind Qubes?
 
 To build security on the "Security by Compartmentalization (or Isolation)" principle.
@@ -208,25 +205,25 @@ See the [XSA Tracker].
 
 Whenever starting a discussion about another (micro)kernel or hypervisor in relation to Qubes, we strongly suggest including answers to the following questions first:
 
-1.  What kinds of containers does it use for isolation? Processes? PV VMs? Fully virtualized VMs (HVMs)? And what underlying h/w technology is used (ring0/3, VT-x)?
+1. What kinds of containers does it use for isolation? Processes? PV VMs? Fully virtualized VMs (HVMs)? And what underlying h/w technology is used (ring0/3, VT-x)?
-2.  Does it require specially written/built applications (e.g. patched Firefox)?
+2. Does it require specially written/built applications (e.g. patched Firefox)?
-3.  Does it require custom drivers, or can it use Linux/Windows ones?
+3. Does it require custom drivers, or can it use Linux/Windows ones?
-4.  Does it support VT-d, and does it allow for the creation of untrusted driver domains?
+4. Does it support VT-d, and does it allow for the creation of untrusted driver domains?
-5.  Does it support S3 sleep?
+5. Does it support S3 sleep?
-6.  Does it work on multiple CPUs/Chipsets?
+6. Does it work on multiple CPUs/Chipsets?
-7.  What are the performance costs, more or less? (e.g. "XYZ prevents concurrent execution of two domains/processes on shared cores of a single processor", etc.)
+7. What are the performance costs, more or less? (e.g. "XYZ prevents concurrent execution of two domains/processes on shared cores of a single processor", etc.)
-8.  Other special features? E.g. eliminates cooperative covert channels between VMs?
+8. Other special features? E.g. eliminates cooperative covert channels between VMs?
 
 Here are the answers for Xen 4.1 (which we use as of 2014-04-28):
 
-1.  PV and HVM Virtual Machines (ring0/3 for PV domains, VT-x/AMD-v for HVMs).
+1. PV and HVM Virtual Machines (ring0/3 for PV domains, VT-x/AMD-v for HVMs).
-2.  Runs unmodified usermode apps (binaries).
+2. Runs unmodified usermode apps (binaries).
-3.  Runs unmodified Linux drivers (dom0 and driver domains). PV VMs require special written pvdrivers.
+3. Runs unmodified Linux drivers (dom0 and driver domains). PV VMs require special written pvdrivers.
-4.  Full VT-d support including untrusted driver domains.
+4. Full VT-d support including untrusted driver domains.
-5.  S3 sleep supported well.
+5. S3 sleep supported well.
-6.  Works on most modern CPUs/Chipsets.
+6. Works on most modern CPUs/Chipsets.
-7.  Biggest performance hit on disk operations (especially in Qubes when complex 2-layer mapping used for Linux qubes). No GPU virtualization.
+7. Biggest performance hit on disk operations (especially in Qubes when complex 2-layer mapping used for Linux qubes). No GPU virtualization.
-8.  Mostly Works<sup>TM</sup> :)
+8. Mostly Works<sup>TM</sup> :)
 
 ### Which virtualization modes do VMs use?
 
@@ -253,6 +250,7 @@ Please refer to [this page].
 ### Why is dom0 so old?
 
 Please see:
+
 - [Installing and updating software in dom0]
 - [Note on dom0 and EOL]
 
@@ -315,7 +313,6 @@ So, if feature X isn't enabled, it's most likely for one of three reasons:
 
 If it seems like a feature that we can and should enable, please [let us know][reporting-bugs]!
 
-
 ## Users
 
 ### Can I watch YouTube videos in qubes?
@@ -332,8 +329,8 @@ AppVMs use a software-only (CPU-based) implementation of OpenGL, which may be go
 
 For further discussion about the potential for GPU passthrough on Xen/Qubes, please see the following threads:
 
--   [GPU passing to HVM]
+- [GPU passing to HVM]
--   [Clarifications on GPU security]
+- [Clarifications on GPU security]
 
 ### Is Qubes a multi-user system?
 
@@ -346,7 +343,6 @@ See [here] for details.
 However, in Qubes 4.x we will be implementing management functionality.
 See [Admin API] and [Core Stack] for more details.
 
-
 ### What are the system requirements for Qubes OS?
 
 See the [system requirements].
@@ -437,7 +433,6 @@ You shouldn't do that, because it poses a security risk for your Qubes OS instal
 But if you understand the risk and accept it, read [documentation on multibooting].
 It begins with an explanation of the risks with such a setup.
 
-
 ### Which version of Qubes am I running?
 
 See [here][version].
@@ -473,16 +468,18 @@ This is an intended feature.
 A device which was previously assigned to a less trusted qube could attack dom0 if it were automatically reassigned there.
 In order to re-enable the device in dom0, either:
 
- * Reboot the physical machine.
+- Reboot the physical machine.
 
 or
 
- * Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver and attach back to the original driver. Replace `<BDF>` with your device, for example `00:1c.2`:
+- Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver and attach back to the original driver. Replace `<BDF>` with your device, for example `00:1c.2`:
 
-        echo 0000:<BDF> > /sys/bus/pci/drivers/pciback/unbind
+    ```
-        MODALIAS=`cat /sys/bus/pci/devices/0000:<BDF>/modalias`
+    echo 0000:<BDF> > /sys/bus/pci/drivers/pciback/unbind
-        MOD=`modprobe -R $MODALIAS | head -n 1`
+    MODALIAS=`cat /sys/bus/pci/devices/0000:<BDF>/modalias`
-        echo 0000:<BDF> > /sys/bus/pci/drivers/$MOD/bind
+    MOD=`modprobe -R $MODALIAS | head -n 1`
+    echo 0000:<BDF> > /sys/bus/pci/drivers/$MOD/bind
+    ```
 
 See also [here][assign_devices].
 
@@ -510,7 +507,9 @@ For Debian:
 1. (Recommended) Clone an existing Debian TemplateVM
 2. Install VLC in that TemplateVM:
 
-       $ sudo apt install vlc
+    ```bash_session
+    $ sudo apt install vlc
+    ```
 
 3. Use VLC to play your video files.
 
@@ -520,7 +519,9 @@ For Fedora:
 2. [Enable the appropriate RPMFusion repos in the desired Fedora TemplateVM][Enable RPMFusion].
 3. Install VLC in that TemplateVM:
 
-       $ sudo dnf install vlc
+    ```bash_session
+    $ sudo dnf install vlc
+    ```
 
 4. Use VLC to play your video files.
 
@@ -585,7 +586,9 @@ I see a screen popup with SeaBios and 4 lines, last one being `Probing EDD (edd=
 
 From a `dom0` prompt, enter:
 
-    qvm-prefs <HVMname> kernel ""
+```
+qvm-prefs <HVMname> kernel ""
+```
 
 ### When I try to install a TemplateVM, it says no match is found.
 
@@ -603,6 +606,7 @@ The full message looks like:
 [FAILED] Failed to start Load Kernel Modules.
 See 'systemctl status systemd-modules-load.service' for details.
 ```
+
 This is cosmetic only, and can safely be ignored.
 
 ### Why is Qubes so slow and how can I make it faster?
@@ -622,7 +626,6 @@ There is no particular configuration that will be ideal for everyone (despite ho
 Please don't ask for your favorite program to be installed by default or for some setting that obviously varies by user preference to be changed so that it matches *your* preference.
 This is an incredibly selfish attitude that demonstrates a complete lack of consideration for the thousands of other Qubes users who don't happen to share your preferences.
 
-
 ## Developers
 
 ### Are there restrictions on the software that the Qubes developers are willing to use?
@@ -631,10 +634,10 @@ Yes.
 In general, the Qubes developers will not use a piece of software unless there is an *easy* way to verify both its **integrity** and **authenticity**, preferably via PGP signatures (see [Verifying Signatures](/security/verifying-signatures/)).
 Specifically:
 
- * If PGP signatures are used, the signing key(s) should have well-publicized fingerprint(s) verifiable via multiple independent channels or be accessible to the developers through a web of trust.
+- If PGP signatures are used, the signing key(s) should have well-publicized fingerprint(s) verifiable via multiple independent channels or be accessible to the developers through a web of trust.
- * If the software is security-sensitive and requires communication with the outside world, a "split" implementation is highly preferred (for examples, see [Split GPG](/doc/split-gpg/) and [Split Bitcoin](/doc/split-bitcoin/)).
+- If the software is security-sensitive and requires communication with the outside world, a "split" implementation is highly preferred (for examples, see [Split GPG](/doc/split-gpg/) and [Split Bitcoin](/doc/split-bitcoin/)).
- * If the software has dependencies, these should be packaged and available in repos for a [current, Qubes-supported version](/doc/supported-versions/#templatevms) of Fedora (preferred) or Debian (unless all the insecure dependencies can run in an untrusted VM in a "split" implementation).
+- If the software has dependencies, these should be packaged and available in repos for a [current, Qubes-supported version](/doc/supported-versions/#templatevms) of Fedora (preferred) or Debian (unless all the insecure dependencies can run in an untrusted VM in a "split" implementation).
- * If the software must be built from source, the source code and any builders must be signed.
+- If the software must be built from source, the source code and any builders must be signed.
    (Practically speaking, the more cumbersome and time-consuming it is to build from source, the less likely the developers are to use it.)
 
 ### Why does dom0 need to be 64-bit?
@@ -667,11 +670,11 @@ See the discussion on issue [#1014](https://github.com/QubesOS/qubes-issues/issu
 
 The policy is there mostly to ease maintenance, on several levels:
 
- * Less modifications means easier migration to new upstream distribution
+- Less modifications means easier migration to new upstream distribution
    releases.
- * The upstream documentation matches the distribution running in the Qubes VM.
+- The upstream documentation matches the distribution running in the Qubes VM.
- * We're less likely to introduce Qubes-specific issues.
+- We're less likely to introduce Qubes-specific issues.
- * Each officially supported distribution (ideally) should offer the same set of
+- Each officially supported distribution (ideally) should offer the same set of
    Qubes-specific features - a change in one supported distribution should be
    followed also in others, including new future distributions.
 

introduction/intro.html

@@ -11,6 +11,7 @@ redirect_from:
 ---
 
 <h2>What is Qubes OS?</h2>
+<a id = "what-is-qubes-os"></a>
 
 <div class="row">
   <div class="col-lg-12 col-md-12">
@@ -159,6 +160,7 @@ redirect_from:
 
 
 <h2 class="more-bottom">Why Qubes OS?</h2>
+<a id = "why-qubes-os"></a>
 
 <h3>Physical isolation is a given safeguard that the digital world lacks</h3>
 
@@ -336,4 +338,3 @@ redirect_from:
     </li>
   </ul>
 </p>
-

introduction/reporting-bugs.md

@@ -123,7 +123,6 @@ If the issue is closed without one of these specific resolutions, then it means,
 - [Package Contributions]
 - [Documentation Guidelines]
 
-
 [qubes-issues-all]: https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue
 [qubes-issues-bug-up-desc]: https://github.com/QubesOS/qubes-issues/issues?q=label%3Abug+sort%3Aupdated-desc
 [qubes-issues-labels]: https://github.com/QubesOS/qubes-issues/labels
@@ -146,4 +145,3 @@ If the issue is closed without one of these specific resolutions, then it means,
 [Package Contributions]: /doc/package-contributions/
 [Documentation Guidelines]: /doc/doc-guidelines/
 [hcl-howto]: /doc/hcl/#generating-and-submitting-new-reports
-

introduction/statistics.md

@@ -12,8 +12,7 @@ redirect_from:
   </a>
 </div>
 
-FAQ
+## FAQ
----
 
 ### How often is this graph updated?
 
@@ -39,10 +38,11 @@ tor_users = tor_requests * (plain_users / plain_requests)
 ```
 
 Where:
- - `tor_users` is the estimated number of Qubes users who download updates via Tor each month.
+
- - `tor_requests` is the total number of requests the Qubes update servers receive from Tor exit nodes each month.
+- `tor_users` is the estimated number of Qubes users who download updates via Tor each month.
- - `plain_users` is the number of unique clearnet IPv4 addresses that connect to the Qubes update servers each month.
+- `tor_requests` is the total number of requests the Qubes update servers receive from Tor exit nodes each month.
- - `plain_requests` is the total number of requests the Qubes update servers receive from clearnet IPv4 addresses each month.
+- `plain_users` is the number of unique clearnet IPv4 addresses that connect to the Qubes update servers each month.
+- `plain_requests` is the total number of requests the Qubes update servers receive from clearnet IPv4 addresses each month.
 
 We cross-reference the list of connecting IP addresses with [TorDNSEL's exit lists] in order to distinguish Tor and clearnet IPs and requests.
 For this purpose, we count an IP address as belonging to a Tor exit node if there was a Tor exit node active for that address within the 24-hour periods before or after it connected to the Qubes update servers.
@@ -51,9 +51,9 @@ For this purpose, we count an IP address as belonging to a Tor exit node if ther
 
 We collect:
 
- - The IPv4 addresses that connect to the Qubes update servers
+- The IPv4 addresses that connect to the Qubes update servers
- - The number of requests from each IPv4 address
+- The number of requests from each IPv4 address
- - Standard server access and error logs
+- Standard server access and error logs
 
 We do not collect any other kinds of data about Qubes users.
 
@@ -64,9 +64,7 @@ The raw data is available [here][raw-data].
 Please note that the format of this data is not documented and may change any time if the developers feel the need to include something else.
 The source code is available [here][source-code].
 
-
 [tor-methodology]: #how-has-the-methodology-for-counting-tor-users-changed
 [TorDNSEL's exit lists]: https://metrics.torproject.org/collector.html#type-tordnsel
 [raw-data]: https://tools.qubes-os.org/counter/stats.json
 [source-code]: https://github.com/woju/qubes-stats
-

introduction/support.md

@@ -13,7 +13,7 @@ redirect_from:
 - /wiki/QubesLists/
 ---
 
-# Help, Support, Mailing Lists, and Forum #
+# Help, Support, Mailing Lists, and Forum
 
 Help and support for Qubes OS is available from the [documentation], the
 [mailing lists], and our [forum] which are explained below. The Qubes OS
@@ -24,8 +24,7 @@ see the [issue tracker]. These issues are constantly being updated and may
 contain workarounds for problems that you're experiencing, so it's worth
 [searching the issue tracker] as a first step.
 
-
+## Staying safe
-## Staying safe ##
 
 The Qubes mailing lists and forum are open to the public. The contents are
 crawled by search engines and archived by third-party services outside of our
@@ -61,8 +60,7 @@ every contribution to the Qubes OS Project is publicly visible and
 cryptographically signed, anyone would be in a position to [verify] that these
 came from the same keyholder.
 
-
+## Discussion guidelines
-## Discussion guidelines ##
 
 Qubes discussions mainly take place on `qubes-users`, `qubes-devel`, and our
 [forum], all of which are explained below. Most questions should be directed to
@@ -81,7 +79,7 @@ and knowledgeable people who enjoy corresponding on these lists. The vast
 majority of them will be happy to help you if you follow these simple
 guidelines.
 
-### Be polite and respectful ###
+### Be polite and respectful
 
 Remember, no one here is under any obligation
 to reply to you. Think about your readers. Most of them are coming home after
@@ -89,14 +87,14 @@ a long, hard day at work. The last thing they need is someone's temper
 tantrum. If you are rude and disrespectful, you are very
 likely to be ignored.
 
-### Be concise ###
+### Be concise
 
 Include only essential information. Most of your readers lead
 busy lives and have precious little time. We *want* to spend some of that
 time helping you, if we can. But if you ramble, it will be easier to skip
 over you and help someone else who gets right to the point.
 
-### Help us help you ###
+### Help us help you
 
 Tell us what you've already tried, and which
 documentation pages you've already read. Put yourself in your readers' shoes.
@@ -106,7 +104,7 @@ provide your hardware details is by [generating and submitting a Hardware
 Compatibility List (HCL) report][hcl-howto], then linking to it in your
 message. [Ask questions the smart way.][smart-questions]
 
-### Be patient ###
+### Be patient
 
 Do not "bump" a thread more than once every three days *at
 most*. If it seems like your messages to the mailing lists are consistently
@@ -116,7 +114,7 @@ likely that no one who knows the answer has had time to reply yet. Remember
 that the devs are very busy working on Qubes. They usually only have a chance
 to answer questions on the mailing lists once every several days.
 
-### Be a good community member ###
+### Be a good community member
 
 As with any social community, members earn different reputations for themselves
 over time. We want these discussion venues to be friendly, productive places
@@ -135,7 +133,7 @@ complexities of privacy and anonymity, and we know that many users have no
 other choice but to post anonymously.) You can read our project's [Code of
 Conduct][coc] for more information.
 
-### Report issues and submit changes in the right places ###
+### Report issues and submit changes in the right places
 
 The mailing lists and [forum] are good places to ask questions and discuss
 things. However, if you're submitting a more formal report, we'd prefer that
@@ -144,21 +142,21 @@ Likewise, if you see that something in the documentation should be changed,
 don't simply point it out in a discussion venue. Instead, [submit the
 change][contributing to the documentation].
 
-### Moderation ###
+### Moderation
 
 The moderation team aims to enforce our [Code of Conduct][coc].
 Beyond this, users should not expect any specific action from the moderation team.
 Specifically, users should not request that posts or messages be deleted or edited by a moderator.
 Users are reminded that, in most venues, anything posted will be sent out as an email to other others, and these emails cannot be deleted from others' inboxes.
 
-### Specific mailing list rules and notes ###
+### Specific mailing list rules and notes
 
-#### Use the correct list ####
+#### Use the correct list
 
 Send your message to the correct list. Read the sections below to determine
 which list is correct for your message.
 
-#### Do not top-post ####
+#### Do not top-post
 
 [Top-posting] is placing your reply above the quoted message to which you're
 replying. Please refrain from doing this. Instead, either [interleave] your
@@ -166,28 +164,28 @@ reply by placing parts of your message immediately below each quoted portion
 to which it is replying, or [bottom-post] by placing your entire reply below
 the quoted message to which you're replying.
 
-#### Use proper subject lines ####
+#### Use proper subject lines
 
 Include a precise and informative subject line. This will allow others to
 easily find your thread in the future and use it as a reference. (Bad: "Help!
 Qubes problems!" Good: "R2B2 Installation problem: Apple keyboard not working
 in installer.")
 
-#### Do not send duplicates ####
+#### Do not send duplicates
 
 If your message is not successfully sent to the list, it probably got caught
 in the spam filter. We check the spam filter regularly, so please be patient,
 and your message should be approved (and your email address added to the
 whitelist) within a few days.
 
-#### Keep the list CCed ####
+#### Keep the list CCed
 
 Keep the mailing list CCed throughout the conversation unless there's a
 special need for privacy (in which case, use PGP encryption). This increases
 the likelihood that a greater quantity of useful information will be
 available to everyone in the future.
 
-#### Quote appropriately ####
+#### Quote appropriately
 
 If you're replying to a thread (whether your own or
 someone else's), you should make sure to quote enough from previous messages
@@ -198,7 +196,7 @@ in itself. Do not quote advertisements in signatures or inline PGP signature
 blocks. (Quoting the latter interferes with the ability of programs like
 Enigmail to properly quote replies thereafter).
 
-#### English not required ####
+#### English not required
 
 If you do not speak English, you should feel free to post in your own
 language. However, bear in mind that most members of the list can only read
@@ -207,7 +205,7 @@ of consideration for those readers. If you choose to write in English, please
 do not apologize for doing so poorly, as it is unnecessary. We understand and
 will ask for clarification if needed.
 
-#### Suggestions ####
+#### Suggestions
 
 While we're generally open to hearing suggestions for new features, please
 note that we already have a pretty well defined [roadmap], and it's rather
@@ -219,7 +217,7 @@ Please note, however, that it's always a good idea to field a discussion of
 your idea on the `qubes-devel` list before putting in a lot of hard work on
 something that we may not be able or willing to accept.
 
-#### Google Groups ####
+#### Google Groups
 
 While the mailing lists are implemented as Google Group web forums, a Google
 account is in no way required, expected, or encouraged. Many discussants
@@ -231,14 +229,12 @@ example, we encourage discussants to use [Split GPG] to sign all of their
 messages to the lists, but we do not endorse the use of these Google Groups
 as web forums. For that, we have a separate, dedicated [forum].
 
-
+## Mailing lists
-## Mailing lists ##
 
 This section covers each of our individual [mailing lists][wiki-ml], with
 details about the purpose of each list and how to use it.
 
-
+### qubes-announce
-### qubes-announce ###
 
 This is a read-only list for those who wish to receive only very important,
 infrequent messages. Only the core Qubes team can post to this list. Only
@@ -251,26 +247,25 @@ required. Any email address will work.) To unsubscribe, send a blank email to
 `qubes-announce+unsubscribe@googlegroups.com`. This list also has an optional
 [Google Groups web interface][qubes-announce-web].
 
-
+### qubes-users
-### qubes-users ###
 
 This list is for helping users solve various daily problems with Qubes OS.
 Examples of topics or questions suitable for this list include:
 
- * [HCL] reports
+* [HCL] reports
- * Installation problems
+* Installation problems
- * Hardware compatibility problems
+* Hardware compatibility problems
- * Questions of the form: "How do I...?"
+* Questions of the form: "How do I...?"
 
 Please try searching both the Qubes website and the archives of the mailing
 lists before sending a question. In addition, please make sure that you have
 read and understood the following basic documentation prior to posting to the
 list:
 
- * The [Installation Guide], [System Requirements], and [HCL] (for problems
+* The [Installation Guide], [System Requirements], and [HCL] (for problems
-   related to installing Qubes OS)
+  related to installing Qubes OS)
- * The [User FAQ]
+* The [User FAQ]
- * The [documentation] (for questions about how to use Qubes OS)
+* The [documentation] (for questions about how to use Qubes OS)
 
 You don't have to subscribe in order to post to this list. However, subscribing
 makes your messages less likely to be marked as spam and allows you to receive
@@ -283,20 +278,19 @@ send a blank email to `qubes-users+unsubscribe@googlegroups.com`. This list
 also has an optional [Google Groups web interface][qubes-users-web] and
 [traditional mail archive][qubes-users-archive].
 
-
+### qubes-devel
-### qubes-devel ###
 
 This list is primarily intended for people who are interested in contributing to
 Qubes or who are willing to learn more about its architecture and
 implementation. Examples of topics and questions suitable for this list include:
 
- * Questions about why we made certain architecture or implementation decisions.
+* Questions about why we made certain architecture or implementation decisions.
-   * For example: "Why did you implement XYZ this way and not the other way?"
+  * For example: "Why did you implement XYZ this way and not the other way?"
- * Questions about code layout and where code is for certain functionality.
+* Questions about code layout and where code is for certain functionality.
- * Discussions about proposed new features, patches, etc.
+* Discussions about proposed new features, patches, etc.
-   * For example: "I would like to implement feature XYZ."
+  * For example: "I would like to implement feature XYZ."
- * Contributed code and patches.
+* Contributed code and patches.
- * Security discussions which are relevant to Qubes in some way.
+* Security discussions which are relevant to Qubes in some way.
 
 You must be subscribed in order to post to this list. To subscribe, send a
 blank email to `qubes-devel+subscribe@googlegroups.com`. (Note: A Google
@@ -307,18 +301,17 @@ unsubscribe, send a blank email to `qubes-devel+unsubscribe@googlegroups.com`.
 This list also has an optional [Google Groups web interface][qubes-devel-web]
 and [traditional mail archive][qubes-devel-archive].
 
-
+### qubes-project
-### qubes-project ###
 
 This list is for non-technical discussion and coordination around the
 Qubes OS project.
 
 Examples of topics or question suitable for this list include:
 
- * Participation (talks, workshops, etc.) at upcoming events
+* Participation (talks, workshops, etc.) at upcoming events
- * Project funding applications and strategies
+* Project funding applications and strategies
- * FOSS governance discussions
+* FOSS governance discussions
- * Most Github issues tagged "[business]"
+* Most Github issues tagged "[business]"
 
 You don't have to subscribe in order to post to this list. However, subscribing
 makes your messages less likely to be marked as spam and allows you to receive
@@ -330,17 +323,16 @@ immediately, please allow time for moderation to occur. To unsubscribe, send a
 blank email to `qubes-project+unsubscribe@googlegroups.com`. This list also
 also has an optional [Google Groups web interface][qubes-project-web].
 
-
+### qubes-translation
-### qubes-translation ###
 
 This list is for discussion around the localization and translation of Qubes OS,
 its documentation, and the website.
 
 Examples of topics or question suitable for this list include:
 
- * Questions about or issues with [Transifex], the translation platform we use
+* Questions about or issues with [Transifex], the translation platform we use
- * Who is managing localization for a given language
+* Who is managing localization for a given language
- * Most Github issues tagged "[localization]"
+* Most Github issues tagged "[localization]"
 
 You don't have to subscribe in order to post to this list. However, subscribing
 makes your messages less likely to be marked as spam and allows you to receive
@@ -353,8 +345,7 @@ unsubscribe, send a blank email to
 `qubes-translation+unsubscribe@googlegroups.com`. This list also has an
 optional [Google Groups web interface][qubes-translation-web].
 
-
+## Forum
-## Forum ##
 
 We have a community forum for Qubes OS users:
 
@@ -368,7 +359,7 @@ fills this need for us, as it does for many other open-source projects. Thanks
 to their generous [free hosting for open source projects], we're pleased to be
 able to create this space for our community.
 
-### Why was this forum created? ###
+### Why was this forum created?
 
 Previously, the only option for a forum-like experience was to interact with
 our mailing lists via Google Groups, but we understand all too well that the
@@ -379,7 +370,7 @@ ease-of-use, and modern social features that today's forums support. Moreover,
 Discourse features email integration for those who still prefer the traditional
 mailing list format.
 
-### How is this different from our mailing lists? ###
+### How is this different from our mailing lists?
 
 To be clear, this is *not* a replacement for the mailing lists. This forum is
 simply an *additional* place for discussion. Certain types of discussions
@@ -392,7 +383,7 @@ users simply appreciate the ability to add a "reaction" to a message instead of
 having to add an entirely new reply. Whatever your reasons, it's up to you to
 decide where and how you want to join the conversation.
 
-### Does this split the community? ###
+### Does this split the community?
 
 Many open-source projects (such as Fedora and Debian) have both mailing lists
 and forums (and additional discussion venues). In fact, Qubes already had
@@ -418,15 +409,13 @@ Generally speaking, these are not intended to be primary support venues.
 Rather, these are primarily intended to be a way to more widely disseminate items published on the [news](/news/) page.
 If you use one of these platforms, you may find it convenient to follow the Qubes OS Project there as a way of receiving Qubes news.
 
-
+## Unofficial chat channels
-## Unofficial chat channels ##
 
 The following unofficial chat channels are maintained by the community:
 
- * Matrix, Qubes-related: <https://matrix.to/#/#cybersec-qubes_os:matrix.org>
+* Matrix, Qubes-related: <https://matrix.to/#/#cybersec-qubes_os:matrix.org>
- * Matrix, strictly Qubes: <https://matrix.to/#/#Qubes-OS:matrix.org>
+* Matrix, strictly Qubes: <https://matrix.to/#/#Qubes-OS:matrix.org>
- * `#qubes` channel on freenode.net via traditional IRC clients or: <https://webchat.freenode.net/>
+* `#qubes` channel on freenode.net via traditional IRC clients or: <https://webchat.freenode.net/>
-
 
 [mailing lists]: #mailing-lists
 [wiki-ml]: https://en.wikipedia.org/wiki/Electronic_mailing_list
@@ -473,4 +462,3 @@ The following unofficial chat channels are maintained by the community:
 [IRC]: #unofficial-chat-channels
 [Reddit]: https://www.reddit.com/r/Qubes/
 [hcl-howto]: /doc/hcl/#generating-and-submitting-new-reports
-

project-security/canary-checklist.md

@@ -4,21 +4,17 @@ title: Canary Checklist
 permalink: /security/canaries/checklist/
 ---
 
-Canary Checklist
+# Canary Checklist
-================
 
-Preparation
+## Preparation
------------
 
- * Draft canary and push to private repository
+* Draft canary and push to private repository
- * Finalize canary, sign, and add signed tags
+* Finalize canary, sign, and add signed tags
 
-Announcement
+## Announcement
-------------
-
- * Push canary to public repository
- * Publish a [news post](/news/) using the [Canary Template](/security/canaries/template/)
- * Send the content of the news post to the appropriate [mailing lists](/support/) 
- * Share link to news post on social media
- * Set a reminder for the next canary
 
+* Push canary to public repository
+* Publish a [news post](/news/) using the [Canary Template](/security/canaries/template/)
+* Send the content of the news post to the appropriate [mailing lists](/support/)
+* Share link to news post on social media
+* Set a reminder for the next canary

project-security/canary-template.md

@@ -58,4 +58,3 @@ Footnotes
 ```
 
 ~~~
-

project-security/security-bulletins-checklist.md

@@ -5,22 +5,18 @@ permalink: /security/bulletins/checklist/
 redirect_from: /doc/security-bulletins/checklist/
 ---
 
-Security Bulletin Checklist
+# Security Bulletin Checklist
-===========================
 
-Preparation
+## Preparation
------------
 
- * Draft QSB and push to private repository
+* Draft QSB and push to private repository
- * Build fixed packages
+* Build fixed packages
- * Finalize QSB, sign, and add signed tags
+* Finalize QSB, sign, and add signed tags
 
-Announcement
+## Announcement
-------------
-
- * Upload packages to `security-testing` and `current-testing` repositories
- * Push QSB to public repository
- * Publish a [news post](/news/) using the [QSB Template](/security/bulletins/template/)
- * Send the content of the news post to the appropriate [mailing lists](/support/) 
- * Share link to news post on social media
 
+* Upload packages to `security-testing` and `current-testing` repositories
+* Push QSB to public repository
+* Publish a [news post](/news/) using the [QSB Template](/security/bulletins/template/)
+* Send the content of the news post to the appropriate [mailing lists](/support/)
+* Share link to news post on social media

project-security/security-bulletins-template.md

@@ -80,4 +80,3 @@ https://www.qubes-os.org/security/
 ```
 
 ~~~
-

project-security/security-pack.md

@@ -20,18 +20,17 @@ Qubes Security Pack
 
 The **Qubes Security Pack** (`qubes-secpack`) is a Git repository that contains:
 
- * [Qubes PGP keys](https://keys.qubes-os.org/keys/)
+* [Qubes PGP keys](https://keys.qubes-os.org/keys/)
- * [Qubes Security Bulletins (QSBs)](/security/bulletins/)
+* [Qubes Security Bulletins (QSBs)](/security/bulletins/)
- * [Qubes warrant canaries](https://github.com/QubesOS/qubes-secpack/tree/master/canaries)
+* [Qubes warrant canaries](https://github.com/QubesOS/qubes-secpack/tree/master/canaries)
- * [Qubes Bitcoin fund information](https://github.com/QubesOS/qubes-secpack/tree/master/fund)
+* [Qubes Bitcoin fund information](https://github.com/QubesOS/qubes-secpack/tree/master/fund)
- * Security-related information and announcements (e.g., key revocations)
+* Security-related information and announcements (e.g., key revocations)
 
 While `qubes-secpack` itself is independent of any particular host, its current
 official location is:
 
 <https://github.com/QubesOS/qubes-secpack>
 
-
 History and Rationale
 ---------------------
 
@@ -40,6 +39,7 @@ rationale in an
 [email](https://groups.google.com/d/msg/qubes-devel/twkOEaMLtNI/lZyGx6_jFCEJ)
 to the Qubes mailing lists:
 
+```
     Hello,
 
     A new Qubes Security Bulletin has been just released and is available here:
@@ -126,6 +126,7 @@ to the Qubes mailing lists:
     [3] Deterministic builds are required because it's the only way we can
     implement multiple signature scheme for distributed binaries.
 
+```
 
 How to Obtain, Verify, and Read
 -------------------------------
@@ -133,129 +134,138 @@ How to Obtain, Verify, and Read
 The following example demonstrates one method of obtaining the `qubes-secpack`,
 verifying its contents, and reading them.
 
- 1. Clone the `qubes-secpack` repo.
+1. Clone the `qubes-secpack` repo.
 
-        $ git clone https://github.com/QubesOS/qubes-secpack.git
+    ```shell_session
-        Cloning into 'qubes-secpack'...
+    $ git clone https://github.com/QubesOS/qubes-secpack.git
-        remote: Counting objects: 195, done.
+    Cloning into 'qubes-secpack'...
-        remote: Total 195 (delta 0), reused 0 (delta 0)
+    remote: Counting objects: 195, done.
-        Receiving objects: 100% (195/195), 130.94 KiB | 207.00 KiB/s, done.
+    remote: Total 195 (delta 0), reused 0 (delta 0)
-        Resolving deltas: 100% (47/47), done.
+    Receiving objects: 100% (195/195), 130.94 KiB | 207.00 KiB/s, done.
-        Checking connectivity... done.
+    Resolving deltas: 100% (47/47), done.
+    Checking connectivity... done.
+    ```
 
- 2. Import the included PGP keys.
+2. Import the included PGP keys.
 
-        $ gpg --import qubes-secpack/keys/*/*
+    ```shell_session
-        gpg: directory `/home/user/.gnupg' created
+    $ gpg --import qubes-secpack/keys/*/*
-        gpg: new configuration file `/home/user/.gnupg/gpg.conf' created
+    gpg: directory `/home/user/.gnupg' created
-        gpg: WARNING: options in `/home/user/.gnupg/gpg.conf' are not yet active during this run
+    gpg: new configuration file `/home/user/.gnupg/gpg.conf' created
-        gpg: keyring `/home/user/.gnupg/secring.gpg' created
+    gpg: WARNING: options in `/home/user/.gnupg/gpg.conf' are not yet active during this run
-        gpg: keyring `/home/user/.gnupg/pubring.gpg' created
+    gpg: keyring `/home/user/.gnupg/secring.gpg' created
-        gpg: /home/user/.gnupg/trustdb.gpg: trustdb created
+    gpg: keyring `/home/user/.gnupg/pubring.gpg' created
-        gpg: key C37BB66B: public key "Joanna Rutkowska (Qubes OS signing key) <joanna@invisiblethingslab.com>" imported
+    gpg: /home/user/.gnupg/trustdb.gpg: trustdb created
-        gpg: key 1E30A75D: public key "Joanna Rutkowska (Qubes OS signing key) <joanna@invisiblethingslab.com>" imported
+    gpg: key C37BB66B: public key "Joanna Rutkowska (Qubes OS signing key) <joanna@invisiblethingslab.com>" imported
-        gpg: key 74EADABC: public key "Joanna Rutkowska (Qubes OS signing key) <joanna@invisiblethingslab.com>" imported
+    gpg: key 1E30A75D: public key "Joanna Rutkowska (Qubes OS signing key) <joanna@invisiblethingslab.com>" imported
-        gpg: key 65EF29CA: public key "Joanna Rutkowska (Qubes OS Signing Key) <joanna@invisiblethingslab.com>" imported
+    gpg: key 74EADABC: public key "Joanna Rutkowska (Qubes OS signing key) <joanna@invisiblethingslab.com>" imported
-        gpg: key 34898310: public key "Joanna Rutkowska (Qubes OS Signing Key) <joanna@invisiblethingslab.com>" imported
+    gpg: key 65EF29CA: public key "Joanna Rutkowska (Qubes OS Signing Key) <joanna@invisiblethingslab.com>" imported
-        gpg: key B298547C: public key "Marek Marczykowski (Qubes OS signing key) <marmarek@mimuw.edu.pl>" imported
+    gpg: key 34898310: public key "Joanna Rutkowska (Qubes OS Signing Key) <joanna@invisiblethingslab.com>" imported
-        gpg: key AB5EEF90: public key "Marek Marczykowski (Qubes OS signing key) <marmarek@invisiblethingslab.com>" imported
+    gpg: key B298547C: public key "Marek Marczykowski (Qubes OS signing key) <marmarek@mimuw.edu.pl>" imported
-        gpg: key A603BCB6: public key "Marek Marczykowski (Qubes OS signing key) <marmarek@invisiblethingslab.com>" imported
+    gpg: key AB5EEF90: public key "Marek Marczykowski (Qubes OS signing key) <marmarek@invisiblethingslab.com>" imported
-        gpg: key 42CFA724: public key "Marek Marczykowski-Górecki (Qubes OS signing key) <marmarek@invisiblethingslab.com>" imported
+    gpg: key A603BCB6: public key "Marek Marczykowski (Qubes OS signing key) <marmarek@invisiblethingslab.com>" imported
-        gpg: key 15CE40BF: public key "Wojciech Zygmunt Porczyk (Qubes OS signing key) <woju@invisiblethingslab.com>" imported
+    gpg: key 42CFA724: public key "Marek Marczykowski-Górecki (Qubes OS signing key) <marmarek@invisiblethingslab.com>" imported
-        gpg: key 36879494: public key "Qubes Master Signing Key" imported
+    gpg: key 15CE40BF: public key "Wojciech Zygmunt Porczyk (Qubes OS signing key) <woju@invisiblethingslab.com>" imported
-        gpg: key 211093A7: public key "Qubes OS Release 1 Signing Key" imported
+    gpg: key 36879494: public key "Qubes Master Signing Key" imported
-        gpg: key 0A40E458: public key "Qubes OS Release 2 Signing Key" imported
+    gpg: key 211093A7: public key "Qubes OS Release 1 Signing Key" imported
-        gpg: key 03FA5082: public key "Qubes OS Release 3 Signing Key" imported
+    gpg: key 0A40E458: public key "Qubes OS Release 2 Signing Key" imported
-        gpg: key 92C7B3DC: public key "Joanna Rutkowska (Qubes Security Pack Signing Key) <joanna@invisiblethingslab.com>" imported
+    gpg: key 03FA5082: public key "Qubes OS Release 3 Signing Key" imported
-        gpg: key 1830E06A: public key "Marek Marczykowski-Górecki (Qubes security pack) <marmarek@invisiblethingslab.com>" imported
+    gpg: key 92C7B3DC: public key "Joanna Rutkowska (Qubes Security Pack Signing Key) <joanna@invisiblethingslab.com>" imported
-        gpg: key 3F48CB21: public key "Qubes OS Security Team <security@qubes-os.org>" imported
+    gpg: key 1830E06A: public key "Marek Marczykowski-Górecki (Qubes security pack) <marmarek@invisiblethingslab.com>" imported
-        gpg: Total number processed: 17
+    gpg: key 3F48CB21: public key "Qubes OS Security Team <security@qubes-os.org>" imported
-        gpg:               imported: 17  (RSA: 17)
+    gpg: Total number processed: 17
-        gpg: no ultimately trusted keys found
+    gpg:               imported: 17  (RSA: 17)
+    gpg: no ultimately trusted keys found
+    ```
 
- 3. Verify and trust the Qubes Master Signing Key.
+3. Verify and trust the Qubes Master Signing Key.
 
-        $ gpg --edit-key 36879494
+    ```shell_session
-        gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc.
+    $ gpg --edit-key 36879494
-        This is free software: you are free to change and redistribute it.
+    gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc.
-        There is NO WARRANTY, to the extent permitted by law.
+    This is free software: you are free to change and redistribute it.
+    There is NO WARRANTY, to the extent permitted by law.
 
 
-        pub  4096R/36879494  created: 2010-04-01  expires: never       usage: SC  
+    pub  4096R/36879494  created: 2010-04-01  expires: never       usage: SC
-                             trust: unknown       validity: unknown
+                         trust: unknown       validity: unknown
-        [ unknown] (1). Qubes Master Signing Key
+    [ unknown] (1). Qubes Master Signing Key
 
-        gpg> fpr
+    gpg> fpr
-        pub   4096R/36879494 2010-04-01 Qubes Master Signing Key
+    pub   4096R/36879494 2010-04-01 Qubes Master Signing Key
-         Primary key fingerprint: 427F 11FD 0FAA 4B08 0123  F01C DDFA 1A3E 3687 9494
+    Primary key fingerprint: 427F 11FD 0FAA 4B08 0123  F01C DDFA 1A3E 3687 9494
 
-        gpg> trust
+    gpg> trust
-        pub  4096R/36879494  created: 2010-04-01  expires: never       usage: SC  
+    pub  4096R/36879494  created: 2010-04-01  expires: never       usage: SC
-                             trust: unknown       validity: unknown
+                         trust: unknown       validity: unknown
-        [ unknown] (1). Qubes Master Signing Key
+    [ unknown] (1). Qubes Master Signing Key
 
-        Please decide how far you trust this user to correctly verify other users' keys
+    Please decide how far you trust this user to correctly verify other users' keys
-        (by looking at passports, checking fingerprints from different sources, etc.)
+    (by looking at passports, checking fingerprints from different sources, etc.)
 
-          1 = I don't know or won't say
+    1 = I don't know or won't say
-          2 = I do NOT trust
+    2 = I do NOT trust
-          3 = I trust marginally
+    3 = I trust marginally
-          4 = I trust fully
+    4 = I trust fully
-          5 = I trust ultimately
+    5 = I trust ultimately
-          m = back to the main menu
+    m = back to the main menu
 
-        Your decision? 5
+    Your decision? 5
-        Do you really want to set this key to ultimate trust? (y/N) y
+    Do you really want to set this key to ultimate trust? (y/N) y
 
-        pub  4096R/36879494  created: 2010-04-01  expires: never       usage: SC  
+    pub  4096R/36879494  created: 2010-04-01  expires: never       usage: SC
-                             trust: ultimate      validity: unknown
+                         trust: ultimate      validity: unknown
-        [ unknown] (1). Qubes Master Signing Key
+    [ unknown] (1). Qubes Master Signing Key
-        Please note that the shown key validity is not necessarily correct
+    Please note that the shown key validity is not necessarily correct
-        unless you restart the program.
+    unless you restart the program.
 
-        gpg> q
+    gpg> q
+    ```
 
-    **Important!**
+   **Important!**
 
-    In order to verify the authenticity of the Qubes Master Signing Key prior to
+   In order to verify the authenticity of the Qubes Master Signing Key prior to
-    trusting it, you should obtain the Qubes Master Signing Key fingerprint from
+   trusting it, you should obtain the Qubes Master Signing Key fingerprint from
-    a trustworthy source (ideally, multiple sources) *other than* this website
+   a trustworthy source (ideally, multiple sources) *other than* this website
-    and visually compare it (them) to the fingerprint displayed in the preceding
+   and visually compare it (them) to the fingerprint displayed in the preceding
-    step, ensuring they match. You can read more about digital signatures and
+   step, ensuring they match. You can read more about digital signatures and
-    key verification [here](/security/verifying-signatures/).
+   key verification [here](/security/verifying-signatures/).
 
- 4. Verify signed Git tags.
+4. Verify signed Git tags.
 
-        $ cd qubes-secpack/
+    ```shell_session
-        $ git tag -v `git describe`
+    $ cd qubes-secpack/
-        object 2bb7f0b966593d8ed74e140a04d60c68b96b164e
+    $ git tag -v `git describe`
-        type commit
+    object 2bb7f0b966593d8ed74e140a04d60c68b96b164e
-        tag joanna_sec_2bb7f0b9
+    type commit
-        tagger Joanna Rutkowska <joanna@invisiblethingslab.com> 1468335706 +0000
+    tag joanna_sec_2bb7f0b9
+    tagger Joanna Rutkowska <joanna@invisiblethingslab.com> 1468335706 +0000
 
-        Tag for commit 2bb7f0b966593d8ed74e140a04d60c68b96b164e
+    Tag for commit 2bb7f0b966593d8ed74e140a04d60c68b96b164e
-        gpg: Signature made 2016-07-12T08:01:46 PDT
+    gpg: Signature made 2016-07-12T08:01:46 PDT
-        gpg:                using RSA key 0x4E6829BC92C7B3DC
+    gpg:                using RSA key 0x4E6829BC92C7B3DC
-        gpg: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) <joanna@invisiblethingslab.com>" [full]
+    gpg: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) <joanna@invisiblethingslab.com>" [full]
+    ```
 
     (The final line of output confirms that the signature is good.)
 
- 5. Verify detached PGP signatures.
+5. Verify detached PGP signatures.
 
-        $ cd canaries/                                     
+    ```shell_session
-        $ gpg --verify canary-001-2015.txt.sig.joanna canary-001-2015.txt
+    $ cd canaries/
-        gpg: Signature made Mon Jan  5 20:21:40 2015 UTC using RSA key ID 92C7B3DC
+    $ gpg --verify canary-001-2015.txt.sig.joanna canary-001-2015.txt
-        gpg: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) <joanna@invisiblethingslab.com>"
+    gpg: Signature made Mon Jan  5 20:21:40 2015 UTC using RSA key ID 92C7B3DC
-        $ gpg --verify canary-001-2015.txt.sig.marmarek canary-001-2015.txt
+    gpg: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) <joanna@invisiblethingslab.com>"
-        gpg: Signature made Mon Jan  5 20:13:37 2015 UTC using RSA key ID 1830E06A
+    $ gpg --verify canary-001-2015.txt.sig.marmarek canary-001-2015.txt
-        gpg: Good signature from "Marek Marczykowski-Górecki (Qubes security pack) <marmarek@invisiblethingslab.com>"
+    gpg: Signature made Mon Jan  5 20:13:37 2015 UTC using RSA key ID 1830E06A
+    gpg: Good signature from "Marek Marczykowski-Górecki (Qubes security pack) <marmarek@invisiblethingslab.com>"
+    ```
 
-    (The fourth and final lines of output confirm that the two signatures are
+(The fourth and final lines of output confirm that the two signatures are
-    good.)
+ good.)
 
 The same procedures can be applied to any directory or file in the
 `qubes-secpack`. Two methods of verification (signed Git tags and detached PGP
 signatures) are provided to ensure that the system is robust (e.g., against a
 potential failure in Git tag-based verification) and to give users more options
 to verify the files.
-

project-security/security.md

@@ -14,8 +14,7 @@ redirect_from:
 - /trac/wiki/SecurityPage/
 ---
 
-Qubes OS Project Security Center
+# Qubes OS Project Security Center
-================================
 
 - [Security FAQ]
 - [Security Goals]
@@ -26,50 +25,46 @@ Qubes OS Project Security Center
 - [Why and How to Verify Signatures]
 - [PGP Keys]
 
-
+## Reporting Security Issues in Qubes OS
-Reporting Security Issues in Qubes OS
--------------------------------------
 
 If you believe you have found a security issue affecting Qubes OS, either directly or indirectly (e.g. the issue affects Xen in a configuration that is used in Qubes OS), then we would be more than happy to hear from you!
 We promise to treat any reported issue seriously and, if the investigation confirms that it affects Qubes, to patch it within a reasonable time and release a public [Qubes Security Bulletin][Security Bulletins] that describes the issue, discusses the potential impact of the vulnerability, references applicable patches or workarounds, and credits the discoverer.
 
-Security Updates
+## Security Updates
-----------------
 
 Qubes security updates are obtained by [Updating Qubes OS].
 
-The Qubes Security Team
+## The Qubes Security Team
------------------------
 
 The Qubes Security Team (QST) is the subset of the [Qubes Team] that is responsible for ensuring the security of Qubes OS and the Qubes OS Project.
 In particular, the QST is responsible for:
 
- - Responding to [reported security issues]
+- Responding to [reported security issues]
- - Evaluating whether [XSAs][Xen Security Advisory (XSA) Tracker] affect the security of Qubes OS
+- Evaluating whether [XSAs][Xen Security Advisory (XSA) Tracker] affect the security of Qubes OS
- - Writing, applying, and/or distributing security patches to fix vulnerabilities in Qubes OS
+- Writing, applying, and/or distributing security patches to fix vulnerabilities in Qubes OS
- - Writing, signing, and publishing [Security Bulletins]
+- Writing, signing, and publishing [Security Bulletins]
- - Writing, signing, and publishing [Canaries]
+- Writing, signing, and publishing [Canaries]
- - Generating, safeguarding, and using the project's [PGP Keys]
+- Generating, safeguarding, and using the project's [PGP Keys]
 
 As a security-oriented operating system, the QST is fundamentally important to Qubes, and every Qubes user implicitly trusts the members of the QST by virtue of the actions listed above.
 The Qubes Security Team can be contacted via email at the following address:
 
-    security at qubes-os dot org
+```
+security at qubes-os dot org
+```
 
-
+### Security Team PGP Key
-### Security Team PGP Key ###
 
 Please use the [Security Team PGP Key] to encrypt all emails sent to this address.
 This key is signed by the [Qubes Master Signing Key].
 Please see [Why and How to Verify Signatures] for information about how to verify these keys.
 
-### Members of the Security Team ###
+### Members of the Security Team
 
 - [Marek Marczykowski-Górecki]
 - [Simon Gaiser (aka HW42)]
 - [Joanna Rutkowska] ([emeritus, canaries only])
 
-
 [Security FAQ]: /faq/#general--security
 [Security Goals]: /security/goals/
 [Security Pack]: /security/pack/

project-security/verifying-signatures.md

@@ -9,11 +9,9 @@ redirect_from:
 - /wiki/VerifyingSignatures/
 ---
 
-On Digital Signatures and Key Verification
+# On Digital Signatures and Key Verification
-==========================================
 
-What Digital Signatures Can and Cannot Prove
+## What Digital Signatures Can and Cannot Prove
---------------------------------------------
 
 Most people --- even programmers --- are confused about the basic concepts underlying digital signatures.
 Therefore, most people should read this section, even if it looks trivial at first sight.
@@ -39,20 +37,17 @@ Anybody can generate a GPG key pair that purports to belong to "The Qubes Projec
 The next section explains how to verify the validity of the Qubes signing keys in the process of verifying a Qubes ISO.
 (However, the same general principles apply to all cases in which you may wish to verify a PGP signature, such as [verifying repos], not just verifying ISOs.)
 
-
+## How to Verify Qubes ISO Signatures
-How to Verify Qubes ISO Signatures
-----------------------------------
 
 This section will guide you through the process of verifying a Qubes ISO by checking its PGP signature.
 There are three basic steps in this process:
 
- 1. [Get the Qubes Master Signing Key and verify its authenticity][QMSK]
+1. [Get the Qubes Master Signing Key and verify its authenticity][QMSK]
- 2. [Get the Release Signing Key][RSK]
+2. [Get the Release Signing Key][RSK]
- 3. [Verify your Qubes ISO][signature file]
+3. [Verify your Qubes ISO][signature file]
 
 If you run into any problems, please consult the [Troubleshooting FAQ] below.
 
-
 ### Preparation
 
 Before we begin, you'll need a program that can verify PGP signatures.
@@ -70,7 +65,6 @@ Open a terminal to enter commands.
 The commands below will use `gpg2`, but if that doesn't work for you, try `gpg` instead.
 If that still doesn't work, please consult the documentation for your specific program (see links above).
 
-
 ### 1. Get the Qubes Master Signing Key and verify its authenticity
 
 Every file published by the Qubes Project (ISO, RPM, TGZ files and Git repositories) is digitally signed by one of the developer keys or Release Signing Keys.
@@ -80,27 +74,37 @@ This Qubes Master Signing Key was generated on and is kept only on a dedicated,
 
 There are several ways to get the Qubes Master Signing Key.
 
- - If you have access to an existing Qubes installation, it's available in every VM ([except dom0]):
+- If you have access to an existing Qubes installation, it's available in every VM ([except dom0]):
 
-       $ gpg2 --import /usr/share/qubes/qubes-master-key.asc
+    ```shell_session
+    $ gpg2 --import /usr/share/qubes/qubes-master-key.asc
+    ```
 
- - If you're on Fedora, you can get it in the `distribution-gpg-keys` package:
+- If you're on Fedora, you can get it in the `distribution-gpg-keys` package:
     
-       $ dnf install distribution-gpg-keys
+    ```shell_session
+    $ dnf install distribution-gpg-keys
+    ```
 
- - If you're on Debian, it may already be included in your keyring.
+- If you’re on Debian, it may already be included in your keyring.
 
- - Fetch it with GPG:
+- Fetch it with GPG:
 
-       $ gpg2 --fetch-keys https://keys.qubes-os.org/keys/qubes-master-signing-key.asc
+    ```shell_session
+    $ gpg2 --fetch-keys https://keys.qubes-os.org/keys/qubes-master-signing-key.asc
+    ```
 
- - Download it as a [file][Qubes Master Signing Key], then import it with GPG:
+- Download it as a [file][Qubes Master Signing Key], then import it with GPG:
 
-       $ gpg2 --import ./qubes-master-signing-key.asc 
+    ```shell_session
+    $ gpg2 --import ./qubes-master-signing-key.asc
+    ```
 
- - Get it from a public [keyserver] (specified on first use with `--keyserver <URI>` along with keyserver options to include key signatures), e.g.:
+- Get it from a public [keyserver] (specified on first use with `--keyserver <URI>` along with keyserver options to include key signatures), e.g.:
 
-       $ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --keyserver hkp://pool.sks-keyservers.net:11371 --recv-keys 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
+    ```shell_session
+    $ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --keyserver hkp://pool.sks-keyservers.net:11371 --recv-keys 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
+    ```
 
 The Qubes Master Signing Key is also available in the [Qubes Security Pack] and in the archives of the project's [developer][devel-master-key-msg] and [user][user-master-key-msg] [mailing lists].
 
@@ -120,9 +124,11 @@ Therefore, if you know the genuine Qubes Master Signing Key fingerprint, then yo
 
 For example, here is the Qubes Master Signing Key fingerprint:
 
-    pub   4096R/36879494 2010-04-01
+```
-          Key fingerprint = 427F 11FD 0FAA 4B08 0123  F01C DDFA 1A3E 3687 9494
+pub   4096R/36879494 2010-04-01
-    uid   Qubes Master Signing Key
+      Key fingerprint = 427F 11FD 0FAA 4B08 0123  F01C DDFA 1A3E 3687 9494
+uid   Qubes Master Signing Key
+```
 
 But how do you know that this is the real fingerprint?
 After all, [this website could be compromised][website-trust], so the fingerprint you see here may not be genuine.
@@ -130,61 +136,62 @@ That's why we strongly suggest obtaining the fingerprint from *multiple, indepen
 
 Here are some ideas for how to do that:
 
- - Check the fingerprint on various websites (e.g., [mailing lists](https://groups.google.com/g/qubes-devel/c/RqR9WPxICwg/m/kaQwknZPDHkJ), [discussion forums](https://qubes-os.discourse.group/t/there-is-no-way-to-validate-qubes-master-signing-key/1441/9?u=adw), [social](https://twitter.com/rootkovska/status/496976187491876864) [media](https://www.reddit.com/r/Qubes/comments/5bme9n/fingerprint_verification/), [personal websites](https://andrewdavidwong.com/fingerprints.txt)).
+- Check the fingerprint on various websites (e.g., [mailing lists](https://groups.google.com/g/qubes-devel/c/RqR9WPxICwg/m/kaQwknZPDHkJ), [discussion forums](https://qubes-os.discourse.group/t/there-is-no-way-to-validate-qubes-master-signing-key/1441/9?u=adw), [social](https://twitter.com/rootkovska/status/496976187491876864) [media](https://www.reddit.com/r/Qubes/comments/5bme9n/fingerprint_verification/), [personal websites](https://andrewdavidwong.com/fingerprints.txt)).
- - Check against PDFs, photographs, and videos in which the fingerprint appears
+- Check against PDFs, photographs, and videos in which the fingerprint appears
    (e.g., [slides from a talk](https://hyperelliptic.org/PSC/slides/psc2015_qubesos.pdf), on a [T-shirt](https://twitter.com/legind/status/813847907858337793/photo/2), or in the [recording of a presentation](https://youtu.be/S0TVw7U3MkE?t=2563)).
- - Download old Qubes ISOs from different sources and check the included Qubes Master Signing Key.
+- Download old Qubes ISOs from different sources and check the included Qubes Master Signing Key.
- - Ask people to post the fingerprint on various mailing lists, forums, and chat rooms.
+- Ask people to post the fingerprint on various mailing lists, forums, and chat rooms.
- - Repeat the above over Tor.
+- Repeat the above over Tor.
- - Repeat the above over various VPNs and proxy servers.
+- Repeat the above over various VPNs and proxy servers.
- - Repeat the above on different networks (work, school, internet cafe, etc.).
+- Repeat the above on different networks (work, school, internet cafe, etc.).
- - Text, email, call, video chat, snail mail, or meet up with people you know to confirm the fingerprint.
+- Text, email, call, video chat, snail mail, or meet up with people you know to confirm the fingerprint.
- - Repeat the above from different computers and devices.
+- Repeat the above from different computers and devices.
 
 Once you've obtained the fingerprint from enough independent sources in enough different ways that you feel confident that you know the genuine fingerprint, keep it in a safe place.
 Every time you need to check whether a key claiming to be the Qubes Master Signing Key is authentic, compare that key's fingerprint to your trusted copy and confirm they match.
 
 Now that you've imported the authentic Qubes Master Signing Key, set its trust level to "ultimate" so that it can be used to automatically verify all the keys signed by the Qubes Master Signing Key (in particular, Release Signing Keys).
 
-    $ gpg2 --edit-key 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
+```
-    gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc.
+$ gpg2 --edit-key 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
-    This is free software: you are free to change and redistribute it.
+gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc.
-    There is NO WARRANTY, to the extent permitted by law.
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
 
+pub  4096R/36879494  created: 2010-04-01  expires: never       usage: SC
+                     trust: unknown       validity: unknown
+[ unknown] (1). Qubes Master Signing Key
 
-    pub  4096R/36879494  created: 2010-04-01  expires: never       usage: SC
+gpg> fpr
-                         trust: unknown       validity: unknown
+pub   4096R/36879494 2010-04-01 Qubes Master Signing Key
-    [ unknown] (1). Qubes Master Signing Key
+Primary key fingerprint: 427F 11FD 0FAA 4B08 0123  F01C DDFA 1A3E 3687 9494
 
-    gpg> fpr
+gpg> trust
-    pub   4096R/36879494 2010-04-01 Qubes Master Signing Key
+pub  4096R/36879494  created: 2010-04-01  expires: never       usage: SC
-     Primary key fingerprint: 427F 11FD 0FAA 4B08 0123  F01C DDFA 1A3E 3687 9494
+                     trust: unknown       validity: unknown
+[ unknown] (1). Qubes Master Signing Key
 
-    gpg> trust
+Please decide how far you trust this user to correctly verify other users' keys
-    pub  4096R/36879494  created: 2010-04-01  expires: never       usage: SC
+(by looking at passports, checking fingerprints from different sources, etc.)
-                         trust: unknown       validity: unknown
-    [ unknown] (1). Qubes Master Signing Key
 
-    Please decide how far you trust this user to correctly verify other users' keys
+   1 = I don't know or won't say
-    (by looking at passports, checking fingerprints from different sources, etc.)
+   2 = I do NOT trust
+   3 = I trust marginally
+   4 = I trust fully
+   5 = I trust ultimately
+   m = back to the main menu
 
-      1 = I don't know or won't say
+Your decision? 5
-      2 = I do NOT trust
+Do you really want to set this key to ultimate trust? (y/N) y
-      3 = I trust marginally
-      4 = I trust fully
-      5 = I trust ultimately
-      m = back to the main menu
 
-    Your decision? 5
+pub  4096R/36879494  created: 2010-04-01  expires: never       usage: SC
-    Do you really want to set this key to ultimate trust? (y/N) y
+                     trust: ultimate      validity: unknown
+[ unknown] (1). Qubes Master Signing Key
+Please note that the shown key validity is not necessarily correct
+unless you restart the program.
 
-    pub  4096R/36879494  created: 2010-04-01  expires: never       usage: SC
+gpg> q
-                         trust: ultimate      validity: unknown
+```
-    [ unknown] (1). Qubes Master Signing Key
-    Please note that the shown key validity is not necessarily correct
-    unless you restart the program.
-    
-    gpg> q
 
 Now, when you import any of the legitimate Qubes developer keys and Release Signing Keys used to sign ISOs, RPMs, TGZs, Git tags, and Git commits, they will already be trusted in virtue of being signed by the Qubes Master Signing Key.
 
@@ -192,47 +199,56 @@ Before proceeding to the next step, make sure the Qubes Master Signing Key is in
 (Note: We have already verified the authenticity of the key, so this final check is not about security.
 Rather, it's just a sanity check to make sure that we've imported the key into our keyring correctly.)
 
-    $ gpg2 -k "Qubes Master Signing Key"
+```
-    pub   rsa4096 2010-04-01 [SC]
+$ gpg2 -k "Qubes Master Signing Key"
-          427F11FD0FAA4B080123F01CDDFA1A3E36879494
+pub   rsa4096 2010-04-01 [SC]
-    uid           [ultimate] Qubes Master Signing Key
+      427F11FD0FAA4B080123F01CDDFA1A3E36879494
+uid           [ultimate] Qubes Master Signing Key
+```
 
 If you don't see the Qubes Master Signing Key here with a trust level of "ultimate," go back and follow the instructions in this section carefully.
 
-
 ### 2. Get the Release Signing Key
 
 The filename of the Release Signing Key for your version is usually `qubes-release-X-signing-key.asc`, where `X` is the major version number of your Qubes release.
 There are several ways to get the Release Signing Key for your Qubes release.
 
- - If you have access to an existing Qubes installation, the release keys are available in dom0 in `/etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*`.
+- If you have access to an existing Qubes installation, the release keys are available in dom0 in `/etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*`.
-   These can be [copied][copy-from-dom0] into other VMs for further use.
+  These can be [copied][copy-from-dom0] into other VMs for further use.
-   In addition, every other VM contains the release key corresponding to that installation's release in `/etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*`.
+  In addition, every other VM contains the release key corresponding to that installation's release in `/etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*`.
-   If you wish to use one of these keys, make sure to import it into your keyring, e.g.:
+  If you wish to use one of these keys, make sure to import it into your keyring, e.g.:
 
-       $ gpg2 --import /etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*
+    ```
+    $ gpg2 --import /etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*
+    ```
 
- - Fetch it with GPG:
+- Fetch it with GPG:
 
-       $ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --fetch-keys https://keys.qubes-os.org/keys/qubes-release-X-signing-key.asc
+    ```shell_session
+    $ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --fetch-keys https://keys.qubes-os.org/keys/qubes-release-X-signing-key.asc
+    ```
 
- - Download it as a file.
+- Download it as a file.
-   You can find the Release Signing Key for your Qubes version on the [Downloads] page.
+  You can find the Release Signing Key for your Qubes version on the [Downloads] page.
-   You can also download all the currently used developers' signing keys, Release Signing Keys, and the Qubes Master Signing Key from the [Qubes Security Pack] and the [Qubes OS Keyserver].
+  You can also download all the currently used developers' signing keys, Release Signing Keys, and the Qubes Master Signing Key from the [Qubes Security Pack] and the [Qubes OS Keyserver].
-   Once you've downloaded your Release Signing Key, import it with GPG:
+  Once you've downloaded your Release Signing Key, import it with GPG:
 
-       $ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --import ./qubes-release-X-signing-key.asc 
+    ```shell_session
+    $ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --import ./qubes-release-X-signing-key.asc
+    ```
 
 The Release Signing Key should be signed by the Qubes Master Signing Key:
 
-    $ gpg2 --check-signatures "Qubes OS Release X Signing Key"
+```shell_session
-    pub   rsa4096 2017-03-06 [SC]
+$ gpg2 --check-signatures "Qubes OS Release X Signing Key"
-          5817A43B283DE5A9181A522E1848792F9E2795E9
+pub   rsa4096 2017-03-06 [SC]
-    uid           [  full  ] Qubes OS Release X Signing Key
+      5817A43B283DE5A9181A522E1848792F9E2795E9
-    sig!3        1848792F9E2795E9 2017-03-06  Qubes OS Release X Signing Key
+uid           [  full  ] Qubes OS Release X Signing Key
-    sig!         DDFA1A3E36879494 2017-03-08  Qubes Master Signing Key
+sig!3        1848792F9E2795E9 2017-03-06  Qubes OS Release X Signing Key
+sig!         DDFA1A3E36879494 2017-03-08  Qubes Master Signing Key
 
-    gpg: 2 good signatures
+gpg: 2 good signatures
+```
 
 This is just an example, so the output you receive will not look exactly the same.
 What matters is the line that shows that this key is signed by the Qubes Master Signing Key with a `sig!` prefix.
@@ -242,14 +258,15 @@ A `sig-` prefix would indicate a bad signature and `sig%` would mean that gpg en
 It is not necessary to independently verify the authenticity of the Release Signing Key, since you already verified the authenticity of the Qubes Master Signing Key.
 Before proceeding to the next step, make sure the Release Signing Key is in your keyring:
 
-    $ gpg2 -k "Qubes OS Release"
+```
-    pub   rsa4096 2017-03-06 [SC]
+$ gpg2 -k "Qubes OS Release"
-          5817A43B283DE5A9181A522E1848792F9E2795E9
+pub   rsa4096 2017-03-06 [SC]
-    uid           [  full  ] Qubes OS Release X Signing Key
+      5817A43B283DE5A9181A522E1848792F9E2795E9
+uid           [  full  ] Qubes OS Release X Signing Key
+```
 
 If you don't see the correct Release Signing Key here, go back and follow the instructions in this section carefully.
 
-
 ### 3. Verify your Qubes ISO
 
 Every Qubes ISO is released with a detached PGP signature file, which you can find on the [Downloads] page alongside the ISO.
@@ -260,20 +277,20 @@ Download both the ISO and its signature file.
 Put both of them in the same directory, then navigate to that directory.
 Now, you can verify the ISO by executing this GPG command in the directory that contains both files:
 
-    $ gpg2 -v --verify Qubes-RX-x86_64.iso.asc Qubes-RX-x86_64.iso
+```shell_session
-    gpg: armor header: Version: GnuPG v1
+$ gpg2 -v --verify Qubes-RX-x86_64.iso.asc Qubes-RX-x86_64.iso
-    gpg: Signature made Tue 08 Mar 2016 07:40:56 PM PST using RSA key ID 03FA5082
+gpg: armor header: Version: GnuPG v1
-    gpg: using PGP trust model
+gpg: Signature made Tue 08 Mar 2016 07:40:56 PM PST using RSA key ID 03FA5082
-    gpg: Good signature from "Qubes OS Release X Signing Key"
+gpg: using PGP trust model
-    gpg: binary signature, digest algorithm SHA256
+gpg: Good signature from "Qubes OS Release X Signing Key"
+gpg: binary signature, digest algorithm SHA256
+```
 
 This is just an example, so the output you receive will not look exactly the same.
 What matters is the line that says `Good signature from "Qubes OS Release X Signing Key"`.
 This confirms that the signature on the ISO is good.
 
-
+## How to Verify Qubes ISO Digests
-How to Verify Qubes ISO Digests
--------------------------------
 
 Each Qubes ISO is also accompanied by a plain text file ending in `.DIGESTS`.
 This file contains the output of running several different cryptographic hash functions on the ISO in order to obtain alphanumeric outputs known as "digests" or "hash values."
@@ -286,47 +303,51 @@ The digest filename is always the same as the ISO filename followed by `.DIGESTS
 Since the digest file is a plain text file, you can open it with any text editor.
 Inside, you should find text that looks similar to this:
 
-    -----BEGIN PGP SIGNED MESSAGE-----
+```
-    Hash: SHA256
+-----BEGIN PGP SIGNED MESSAGE-----
+Hash: SHA256
 
-    3c951138b8b9867d8657f173c1b58b82 *Qubes-RX-x86_64.iso
+3c951138b8b9867d8657f173c1b58b82 *Qubes-RX-x86_64.iso
-    1fc9508160d7c4cba6cacc3025165b0f996c843f *Qubes-RX-x86_64.iso
+1fc9508160d7c4cba6cacc3025165b0f996c843f *Qubes-RX-x86_64.iso
-    6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a *Qubes-RX-x86_64.iso
+6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a *Qubes-RX-x86_64.iso
-    de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe *Qubes-RX-x86_64.iso
+de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe *Qubes-RX-x86_64.iso
-    -----BEGIN PGP SIGNATURE-----
+-----BEGIN PGP SIGNATURE-----
-    Version: GnuPG v2
+Version: GnuPG v2
 
-    iQIcBAEBCAAGBQJX4XO/AAoJEMsRyh0D+lCCL9sP/jlZ26zhvlDEX/eaA/ANa/6b
+iQIcBAEBCAAGBQJX4XO/AAoJEMsRyh0D+lCCL9sP/jlZ26zhvlDEX/eaA/ANa/6b
-    Dpsh/sqZEpz1SWoUxdm0gS+anc8nSDoCQSMBxnafuBbmwTChdHI/P7NvNirCULma
+Dpsh/sqZEpz1SWoUxdm0gS+anc8nSDoCQSMBxnafuBbmwTChdHI/P7NvNirCULma
-    9nw+EYCsCiNZ9+WCeroR8XDFSiDjvfkve0R8nwfma1XDqu1bN2ed4n/zNoGgQ8w0
+9nw+EYCsCiNZ9+WCeroR8XDFSiDjvfkve0R8nwfma1XDqu1bN2ed4n/zNoGgQ8w0
-    t5LEVDKCVJ+65pI7RzOSMbWaw+uWfGehbgumD7a6rfEOqOTONoZOjJJTnM0+NFJF
+t5LEVDKCVJ+65pI7RzOSMbWaw+uWfGehbgumD7a6rfEOqOTONoZOjJJTnM0+NFJF
-    Qz5yBg+0FQYc7FmfX+tY801AwSyevj3LKGqZN1GVcU9hhoHH7f2BcbdNk9I5WHHq
+Qz5yBg+0FQYc7FmfX+tY801AwSyevj3LKGqZN1GVcU9hhoHH7f2BcbdNk9I5WHHq
-    doKMnZtcdyadQGwMNB68Wu9+0CWsXvk6E00QfW69M4d6w0gbyoJyUL1uzxgixb5O
+doKMnZtcdyadQGwMNB68Wu9+0CWsXvk6E00QfW69M4d6w0gbyoJyUL1uzxgixb5O
-    qodxrqeitXQSZZvU4kom5zlSjqZs4dGK+Ueplpkr8voT8TSWer0Nbh/VMfrNSt1z
+qodxrqeitXQSZZvU4kom5zlSjqZs4dGK+Ueplpkr8voT8TSWer0Nbh/VMfrNSt1z
-    0/j+e/KMjor7XxehR+XhNWa2YLjA5l5H9rP+Ct/LAfVFp4uhsAnYf0rUskhCStxf
+0/j+e/KMjor7XxehR+XhNWa2YLjA5l5H9rP+Ct/LAfVFp4uhsAnYf0rUskhCStxf
-    Zmtqz4FOw/iSz0Os+IVcnRcyTYWh3e9XaW56b9J/ou0wlwmJ7oJuEikOHBDjrUph
+Zmtqz4FOw/iSz0Os+IVcnRcyTYWh3e9XaW56b9J/ou0wlwmJ7oJuEikOHBDjrUph
-    2a8AM+QzNmnc0tDBWTtT2frXcotqL+Evp/kQr5G5pJM/mTR5EQm7+LKSl7yCPoCj
+2a8AM+QzNmnc0tDBWTtT2frXcotqL+Evp/kQr5G5pJM/mTR5EQm7+LKSl7yCPoCj
-    g8JqGYYptgkxjQdX3YAy9VDsCJ/6EkFc2lkQHbgZxjXqyrEMbgeSXtMltZ7cCqw1
+g8JqGYYptgkxjQdX3YAy9VDsCJ/6EkFc2lkQHbgZxjXqyrEMbgeSXtMltZ7cCqw1
-    3N/6YZw1gSuvBlTquP27
+3N/6YZw1gSuvBlTquP27
-    =e9oD
+=e9oD
-    -----END PGP SIGNATURE-----
+-----END PGP SIGNATURE-----
+```
 
 Four digests have been computed for this ISO.
 The hash functions used, in order from top to bottom, are MD5, SHA1, SHA256, and SHA512.
 One way to verify that the ISO you downloaded matches any of these hash values is by using the respective `*sum` programs:
 
-    $ md5sum -c Qubes-RX-x86_64.iso.DIGESTS
+```shell_session
-    Qubes-RX-x86_64.iso: OK
+$ md5sum -c Qubes-RX-x86_64.iso.DIGESTS
-    md5sum: WARNING: 23 lines are improperly formatted
+ Qubes-RX-x86_64.iso: OK
-    $ sha1sum -c Qubes-RX-x86_64.iso.DIGESTS
+md5sum: WARNING: 23 lines are improperly formatted
-    Qubes-RX-x86_64.iso: OK
+$ sha1sum -c Qubes-RX-x86_64.iso.DIGESTS
-    sha1sum: WARNING: 23 lines are improperly formatted
+Qubes-RX-x86_64.iso: OK
-    $ sha256sum -c Qubes-RX-x86_64.iso.DIGESTS
+sha1sum: WARNING: 23 lines are improperly formatted
-    Qubes-RX-x86_64.iso: OK
+$ sha256sum -c Qubes-RX-x86_64.iso.DIGESTS
-    sha256sum: WARNING: 23 lines are improperly formatted
+Qubes-RX-x86_64.iso: OK
-    $ sha512sum -c Qubes-RX-x86_64.iso.DIGESTS
+sha256sum: WARNING: 23 lines are improperly formatted
-    Qubes-RX-x86_64.iso: OK
+$ sha512sum -c Qubes-RX-x86_64.iso.DIGESTS
-    sha512sum: WARNING: 23 lines are improperly formatted
+Qubes-RX-x86_64.iso: OK
+sha512sum: WARNING: 23 lines are improperly formatted
+```
 
 The `OK` response tells us that the hash value for that particular hash function matches.
 The program also warns us that there are 23 improperly formatted lines, but this is to be expected.
@@ -336,14 +357,16 @@ Therefore, it is safe to ignore these warning lines.
 
 Another way is to use `openssl` to compute each hash value, then compare them to the contents of the digest file.:
 
-    $ openssl dgst -md5 Qubes-RX-x86_64.iso
+```shell_session
-    MD5(Qubes-RX-x86_64.iso)= 3c951138b8b9867d8657f173c1b58b82
+$ openssl dgst -md5 Qubes-RX-x86_64.iso
-    $ openssl dgst -sha1 Qubes-RX-x86_64.iso
+MD5(Qubes-RX-x86_64.iso)= 3c951138b8b9867d8657f173c1b58b82
-    SHA1(Qubes-RX-x86_64.iso)= 1fc9508160d7c4cba6cacc3025165b0f996c843f
+$ openssl dgst -sha1 Qubes-RX-x86_64.iso
-    $ openssl dgst -sha256 Qubes-RX-x86_64.iso
+SHA1(Qubes-RX-x86_64.iso)= 1fc9508160d7c4cba6cacc3025165b0f996c843f
-    SHA256(Qubes-RX-x86_64.iso)= 6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a
+$ openssl dgst -sha256 Qubes-RX-x86_64.iso
-    $ openssl dgst -sha512 Qubes-RX-x86_64.iso
+SHA256(Qubes-RX-x86_64.iso)= 6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a
-    SHA512(Qubes-RX-x86_64.iso)= de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe
+$ openssl dgst -sha512 Qubes-RX-x86_64.iso
+SHA512(Qubes-RX-x86_64.iso)= de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe
+```
 
 (Notice that the outputs match the values from the digest file.)
 
@@ -351,25 +374,25 @@ However, it is possible that an attacker replaced `Qubes-RX-x86_64.iso` with a m
 Therefore, we should also verify the authenticity of the listed hash values.
 Since `Qubes-RX-x86_64.iso.DIGESTS` is a clearsigned PGP file, we can use GPG to verify it from the command line:
 
- 1. [Get the Qubes Master Signing Key and verify its authenticity][QMSK]
+1. [Get the Qubes Master Signing Key and verify its authenticity][QMSK]
- 2. [Get the Release Signing Key][RSK]
+2. [Get the Release Signing Key][RSK]
- 3. Verify the signature in the digest file:
+3. Verify the signature in the digest file:
 
-        $ gpg2 -v --verify Qubes-RX-x86_64.iso.DIGESTS 
+    ```shell_session
-        gpg: armor header: Hash: SHA256
+    $ gpg2 -v --verify Qubes-RX-x86_64.iso.DIGESTS
-        gpg: armor header: Version: GnuPG v2
+    gpg: armor header: Hash: SHA256
-        gpg: original file name=''
+    gpg: armor header: Version: GnuPG v2
-        gpg: Signature made Tue 20 Sep 2016 10:37:03 AM PDT using RSA key ID 03FA5082
+    gpg: original file name=''
-        gpg: using PGP trust model
+    gpg: Signature made Tue 20 Sep 2016 10:37:03 AM PDT using RSA key ID 03FA5082
-        gpg: Good signature from "Qubes OS Release X Signing Key"
+    gpg: using PGP trust model
-        gpg: textmode signature, digest algorithm SHA256
+    gpg: Good signature from "Qubes OS Release X Signing Key"
+    gpg: textmode signature, digest algorithm SHA256
+    ```
 
 The signature is good.
 If our copy of the `Qubes OS Release X Signing Key` is being validated by the authentic Qubes Master Signing Key (see [above][QMSK]), we can be confident that these hash values came from the Qubes devs.
 
-
+## How to Verify Qubes Repos
-How to Verify Qubes Repos
--------------------------
 
 Whenever you use one of the [Qubes repositories], you should verify the PGP signature in a tag on the latest commit or on the latest commit itself.
 (One or both may be present, but only one is required.)
@@ -379,19 +402,27 @@ Instead, ask the person who pushed the unsigned commits to sign them.
 
 To verify a signature on a Git tag:
 
-    $ git tag -v <tag name>
+```shell_session
+$ git tag -v <tag name>
+```
 
 or
 
-    $ git verify-tag <tag name>
+```shell_session
+$ git verify-tag <tag name>
+```
 
 To verify a signature on a Git commit:
 
-    $ git log --show-signature <commit ID>
+```shell_session
+$ git log --show-signature <commit ID>
+```
 
 or
 
-    $ git verify-commit <commit ID>
+```shell_session
+$ git verify-commit <commit ID>
+```
 
 You should always perform this verification on a trusted local machine with properly validated keys (which are available in the [Qubes Security Pack]) rather than relying on a third party, such as GitHub.
 While the GitHub interface may claim that a commit has a verified signature from a member of the Qubes team, this is only trustworthy if GitHub has performed the signature check correctly, the account identity is authentic, the user's key has not been replaced by an admin, GitHub's servers have not been compromised, and so on.
@@ -399,68 +430,56 @@ Since there's no way for you to be certain that all such conditions hold, you're
 
 Also see: [Distrusting the Infrastructure]
 
-
+## Troubleshooting FAQ
-Troubleshooting FAQ
--------------------
-
 
 ### Why am I getting "Can't check signature: public key not found"?
 
 You don't have the correct [Release Signing Key][RSK].
 
-
 ### Why am I getting "BAD signature from 'Qubes OS Release X Signing Key'"?
 
 The problem could be one or more of the following:
 
- - You're trying to verify the wrong file(s).
+- You're trying to verify the wrong file(s).
-   Read this page again carefully.
+  Read this page again carefully.
- - You're using the wrong GPG command.
+- You're using the wrong GPG command.
-   Follow the examples in [Verify your Qubes ISO][signature file] carefully.
+  Follow the examples in [Verify your Qubes ISO][signature file] carefully.
- - The ISO or [signature file] is bad (e.g., incomplete or corrupt download).
+- The ISO or [signature file] is bad (e.g., incomplete or corrupt download).
-   Try downloading the signature file again from a different source, then try verifying again.
+  Try downloading the signature file again from a different source, then try verifying again.
-   If you still get the same result, try downloading the ISO again from a different source, then try verifying again.
+  If you still get the same result, try downloading the ISO again from a different source, then try verifying again.
-
 
 ### Why am I getting "bash: gpg2: command not found"?
 
 You don't have `gpg2` installed.
 Please install it using the method appropriate for your environment (e.g., via your package manager).
 
-
 ### Why am I getting "No such file or directory"?
 
 Your working directory does not contain the required files.
 Go back and follow the instructions more carefully, making sure that you put all required files in the same directory *and* navigate to that directory.
 
-
 ### Why am I getting "can't open signed data `Qubes-RX-x86_64.iso' / can't hash datafile: file open error"?
 
 The correct ISO is not in your working directory.
 
-
 ### Why am I getting "can't open `Qubes-RX-x86_64.iso.asc' / verify signatures failed: file open error"?
 
 The correct [signature file] is not in your working directory.
 
-
 ### Why am I getting "no valid OpenPGP data found"?
 
 Either you don't have the correct [signature file], or you inverted the arguments to `gpg2`.
 ([The signature file goes first.][signature file])
 
-
 ### Why am I getting "WARNING: This key is not certified with a trusted signature! There is no indication that the signature belongs to the owner."?
 
 Either you don't have the [Qubes Master Signing Key][QMSK], or you didn't [set its trust level correctly][QMSK].
 
-
 ### Why am I getting "X signature not checked due to a missing key"?
 
 You don't have the keys that created those signatures in your keyring.
 For present purposes, you don't need them as long as you have the [Qubes Master Signing Key][QMSK] and the [Release Signing Key][RSK] for your Qubes version.
 
-
 ### Why am I seeing additional signatures on a key with "[User ID not found]" or from a revoked key?
 
 This is just a basic part of how OpenPGP works.
@@ -468,43 +487,35 @@ Anyone can sign anyone else's public key and upload the signed public key to key
 Everyone is also free to revoke their own keys at any time (assuming they possess or can create a revocation certificate).
 This has no impact on verifying Qubes ISOs, code, or keys.
 
-
 ### Why am I getting "verify signatures failed: unexpected data"?
 
 You're not verifying against the correct [signature file].
 
-
 ### Why am I getting "not a detached signature"?
 
 You're not verifying against the correct [signature file].
 
-
 ### Why am I getting "CRC error; [...] no signature found [...]"?
 
 You're not verifying against the correct [signature file], or the signature file has been modified.
 Try downloading it again or from a different source.
 
-
 ### Do I have to verify the ISO against both the [signature file] and the [digest file]?
 
 No, either method is sufficient by itself.
 
-
 ### Why am I getting "no properly formatted X checksum lines found"?
 
 You're not checking the correct [digest file].
 
-
 ### Why am I getting "WARNING: X lines are improperly formatted"?
 
 Read [How to Verify Qubes ISO Digests][digest file] again.
 
-
 ### Why am I getting "WARNING: 1 listed file could not be read"?
 
 The correct ISO is not in your working directory.
 
-
 ### I have another problem that isn't mentioned here.
 
 Carefully read this page again to be certain that you didn't skip any steps.
@@ -513,7 +524,6 @@ If your question is about GPG, please see the [GPG documentation].
 Still have question?
 Please see [Help, Support, Mailing Lists, and Forum] for places where you can ask!
 
-
 [website-trust]: /faq/#should-i-trust-this-website
 [Distrusting the Infrastructure]: /faq/#what-does-it-mean-to-distrust-the-infrastructure
 [verifying repos]: #how-to-verify-qubes-repos
@@ -535,4 +545,3 @@ Please see [Help, Support, Mailing Lists, and Forum] for places where you can as
 [GPG documentation]: https://www.gnupg.org/documentation/
 [Help, Support, Mailing Lists, and Forum]: /support/
 [except dom0]: https://github.com/QubesOS/qubes-issues/issues/2544
-

project-security/xsa.md

@@ -16,9 +16,9 @@ Under the "Is Qubes Affected?" column, there are two possible values: **Yes** or
 * **Yes** means that the *security* of Qubes OS *is* affected.
 * **No** means that the *security* of Qubes OS is *not* affected.
 
-
 Important Notes
 ---------------
+
 * For the purpose of this tracker, we do *not* classify mere [denial-of-service (DoS) attacks][DoS] as affecting the *security* of Qubes OS.
   Therefore, if an XSA pertains *only* to DoS attacks against Qubes, the value in the "Is Qubes Affected?" column will be **No**.
 * For simplicity, we use the present tense ("is affected") throughout this page, but this does **not** necessarily mean that up-to-date Qubes installations are *currently* affected by any particular XSA.

user/advanced-configuration/awesome.md

@@ -19,7 +19,9 @@ redirect_from:
 
 awesome can be installed with the standard dom0 installation mechanisms.
 
-    $ sudo qubes-dom0-update awesome
+```shell_session
+$ sudo qubes-dom0-update awesome
+```
 
 That's it. After logging out, you can select awesome in the login manager.
 
@@ -27,7 +29,9 @@ That's it. After logging out, you can select awesome in the login manager.
 
 To [contribute code](/doc/contributing/) you may clone the awesome repository as follows:
 
-    $ git clone https://github.com/QubesOS/qubes-desktop-linux-awesome
+```shell_session
+$ git clone https://github.com/QubesOS/qubes-desktop-linux-awesome
+```
 
 For build instructions please check the repository _README_.
 
@@ -66,6 +70,7 @@ In particular the following events are not meant to cause a focus change:
 * mouse move without click (sloppy focus)
 
 For the below example other requests from applications to the window manager are meant to be ignored in general as well, e.g.:
+
 * windows shouldn't be able to maximize themselves without the user giving a respective command to the WM (simple test: Firefox F11 next to another window)
 * windows shouldn't be able to change their size themselves
 * windows shouldn't be able to modify their borders in any way
@@ -184,4 +189,3 @@ client.disconnect_signal("request::tag", ewmh.tag)
 ```
 
 The signal names may change across awesome versions.
-

user/advanced-configuration/bind-dirs.md

@@ -49,8 +49,10 @@ From now on any files within the `/var/lib/tor` folder will persist across reboo
 You can make make many files or folders persist, simply by making multiple entries in the `50_user.conf` file, each on a separate line.
 For example, if you added the file `/etc/tor/torrc` to the `binds` variable, any modifications to *that* file will persist across reboots.
 
-       binds+=( '/var/lib/tor' )
+```
-       binds+=( '/etc/tor/torrc' )
+binds+=( '/var/lib/tor' )
+binds+=( '/etc/tor/torrc' )
+```
 
 ## Other Configuration Folders ##
 
@@ -68,7 +70,6 @@ Creation of the files and folders in `/rw/bind-dirs` should be automatic the fir
 If you want to circumvent this process, you can create the relevant file structure under `/rw/bind-dirs` and make any changes at the same time that you perform the configuration, before reboot.
 Note that you must create the full folder structure under `/rw/bind-dirs` - e.g you would have to create `/rw/bind-dirs/var/lib/tor`
 
-
 ## Limitations ##
 
 * Files that exist in the TemplateVM root image cannot be deleted in the TemplateBasedVMs root image using bind-dirs.sh.

user/advanced-configuration/config-files.md

@@ -19,7 +19,7 @@ These files are placed in `/rw`, which survives a VM restart.
 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 runs at VM startup.
+- `/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:
 
@@ -34,10 +34,10 @@ The scripts here all run as root.
     echo '127.0.0.1 example.com' >> /etc/hosts
     ~~~
 
--   `/rw/config/qubes-ip-change-hook` - script runs in NetVM after every external IP change and on "hardware" link status change.
+- `/rw/config/qubes-ip-change-hook` - script runs in NetVM after every external IP change and on "hardware" link status change.
 
--   In ProxyVMs (or AppVMs with `qubes-firewall` service enabled), scripts placed in the following directories will be executed in the listed order followed by `qubes-firewall-user-script` at start up.
+- In ProxyVMs (or AppVMs with `qubes-firewall` service enabled), scripts placed in the following directories will be executed in the listed order followed by `qubes-firewall-user-script` at start up.
-    Good place to write custom firewall rules.
+  Good place to write custom firewall rules.
 
     ~~~
     /etc/qubes/qubes-firewall.d
@@ -45,11 +45,12 @@ The scripts here all run as root.
     /rw/config/qubes-firewall-user-script
     ~~~
 
--   `/rw/config/suspend-module-blacklist` - list of modules (one per line) to be unloaded before system goes to sleep.
+- `/rw/config/suspend-module-blacklist` - list of modules (one per line) to be unloaded before system goes to sleep.
-    The file is used only in a VM with PCI devices attached.
+  The file is used only in a VM with PCI devices attached.
-    Intended for use with problematic device drivers.
+  Intended for use with problematic device drivers.
 
 - In NetVMs/ProxyVMs, scripts placed in `/rw/config/network-hooks.d` will be ran when configuring Qubes interfaces. For each script, the `command`, `vif`, `vif_type` and `ip` is passed as arguments (see `/etc/xen/scripts/vif-route-qubes`). For example, consider a PV AppVM `work` with IP `10.137.0.100` and `sys-firewall` as NetVM. Assuming it's Xen domain id is arbitrary `12` then, the following script located at `/rw/config/network-hooks.d/hook-100.sh` in `sys-firewall`:
+
     ~~~
     #!/bin/bash
 
@@ -76,7 +77,6 @@ Note that scripts need to be executable (`chmod +x`) to be used.
 
 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.
 
-
 GUI and audio configuration in dom0
 -----------------------------------
 
@@ -115,31 +115,31 @@ VM: {
 
 Currently supported settings:
 
--   `allow_fullscreen` - allow VM to request its windows to go fullscreen (without any colorful frame).
+- `allow_fullscreen` - allow VM to request its windows to go fullscreen (without any colorful frame).
 
     **Note:** Regardless of this setting, you can always put a window into fullscreen mode in Xfce4 using the trusted window manager by right-clicking on a window's title bar and selecting "Fullscreen".
     This functionality should still be considered safe, since a VM window still can't voluntarily enter fullscreen mode.
     The user must select this option from the trusted window manager in dom0.
     To exit fullscreen mode from here, press `alt` + `space` to bring up the title bar menu again, then select "Leave Fullscreen".
 
--   `allow_utf8_titles` - allow the use of UTF-8 in window titles; otherwise, non-ASCII characters are replaced by an underscore.
+- `allow_utf8_titles` - allow the use of UTF-8 in window titles; otherwise, non-ASCII characters are replaced by an underscore.
 
--   `secure_copy_sequence` and `secure_paste_sequence` - key sequences used to trigger secure copy and paste.
+- `secure_copy_sequence` and `secure_paste_sequence` - key sequences used to trigger secure copy and paste.
 
--   `audio_low_latency` - force low-latency audio mode (about 40ms compared to 200-500ms by default).
+- `audio_low_latency` - force low-latency audio mode (about 40ms compared to 200-500ms by default).
-     Note that this will cause much higher CPU usage in dom0. It's enabled by
+  Note that this will cause much higher CPU usage in dom0. It's enabled by
-		 default, disabling it may save CPU in dom0.
+  default, disabling it may save CPU in dom0.
 
 - `trayicon_mode` - defines the trayicon coloring mode. Options are
       - `bg` - color full icon background to the VM color
       - `border1` - add 1px border at the icon edges
       - `border2` - add 1px border 1px from the icon edges
       - `tint` - tinttint icon to the VM color,  can be used with additional
-		     modifiers (you can enable multiple of them)
+         modifiers (you can enable multiple of them)
       - `tint+border1,tint+border2` - same as tint, but also add a border
       - `tint+saturation50` - same as tint, but reduce icon saturation by 50%
       - `tint+whitehack` - same as tint, but change white pixels (0xffffff) to
-		     almost-white (0xfefefe)
+         almost-white (0xfefefe)
 
 - `log level` - defines the log options logs can take. It can
    have a value of 0 (only errors), 1 (some basic messages), and 2 (debug).

user/advanced-configuration/disposablevm-customization.md

@@ -12,18 +12,21 @@ redirect_from:
 
 # DisposableVM Customization
 
-
 ## Introduction
 
 A [DisposableVM](/doc/disposablevm) can be based on any [TemplateBasedVM](/doc/glossary/#templatebasedvm).
 You can also choose to use different [DisposableVM Templates](/doc/glossary/#disposablevm-template) for different DisposableVMs.
 To prepare an AppVM to be a DisposableVM Template, you need to set `template_for_dispvms` property, for example:
 
-    [user@dom0 ~]$ qvm-prefs fedora-26-dvm template_for_dispvms True
+```shell_session
+[user@dom0 ~]$ qvm-prefs fedora-26-dvm template_for_dispvms True
+```
 
 Additionally, if you want to have menu entries for starting applications in DisposableVM 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
+```shell_session
+[user@dom0 ~]$ qvm-features fedora-26-dvm appmenus-dispvm 1
+```
 
 Note: application shortcuts that existed before setting this feature will not be updated automatically. Please go the the "Applications" tab in the qube's "Settings" dialog and unselect all existing shortcuts by clicking "<<", then click "OK" and close the dialog. Give it a few seconds time and then reopen and re-select all the shortcuts you want to see in the menu. See [this page](/doc/managing-appvm-shortcuts) for background information.
 
@@ -35,25 +38,27 @@ In particular, the *default* DisposableVM Template is important because it is us
 This means that it will have access to everything that you open with this feature.
 For this reason, it is strongly recommended that you base the default DisposableVM Template on a trusted TemplateVM and refrain from making any risky customizations to it.
 
-
 ## Creating a new DisposableVM Template
 
 In Qubes 4.0, you're no longer restricted to a single DisposableVM Template. Instead, you can create as many as you want. Whenever you start a new DisposableVM, you can choose to base it on whichever DisposableVM Template you like.
 To create new DisposableVM Template, lets say `custom-disposablevm-template`, based on `debian-9` template, use following commands:
 
-    [user@dom0 ~]$ qvm-create --template debian-9 --label red custom-disposablevm-template
+```shell_session
-    [user@dom0 ~]$ qvm-prefs custom-disposablevm-template template_for_dispvms True
+[user@dom0 ~]$ qvm-create --template debian-9 --label red custom-disposablevm-template
-    [user@dom0 ~]$ qvm-features custom-disposablevm-template appmenus-dispvm 1
+[user@dom0 ~]$ qvm-prefs custom-disposablevm-template template_for_dispvms True
+[user@dom0 ~]$ qvm-features custom-disposablevm-template appmenus-dispvm 1
+```
 
 Additionally you may want to set it as default DisposableVM Template:
 
-    [user@dom0 ~]$ qubes-prefs default_dispvm custom-disposablevm-template
+```shell_session
+[user@dom0 ~]$ qubes-prefs default_dispvm custom-disposablevm-template
+```
 
 The above default is used whenever a qube request starting a new DisposableVM and do not specify which one (for example `qvm-open-in-dvm` tool). This can be also set in qube settings and will affect service calls from that qube. See [qrexec documentation](/doc/qrexec/#specifying-vms-tags-types-targets-etc) for details.
 
 If you wish to use a [Minimal TemplateVM](/doc/templates/minimal/) as a DisposableVM Template, please see the [Minimal TemplateVM](/doc/templates/minimal/) page.
 
-
 ## Customization of DisposableVM
 
 _**Note:** If you are trying to customize Tor Browser in a Whonix DisposableVM, please consult the [Whonix documentation](https://www.whonix.org/wiki/Tor_Browser/Advanced_Users#DVM_Template_Customization)._
@@ -61,17 +66,18 @@ _**Note:** If you are trying to customize Tor Browser in a Whonix DisposableVM,
 It is possible to change the settings for each new DisposableVM.
 This can be done by customizing the DisposableVM Template on which it is based:
 
-1.  Start a terminal in the `fedora-26-dvm` qube (or another DisposableVM Template) by running the following command in a dom0 terminal. (If you enable `appmenus-dispvm` feature (as explained at the top), applications menu for this VM (`fedora-26-dvm`) will be "Disposable: fedora-26-dvm" (instead of "Domain: fedora-26-dvm") and entries there will start new DisposableVM based on that VM (`fedora-26-dvm`). Not in that VM (`fedora-26-dvm`) itself).
+1. Start a terminal in the `fedora-26-dvm` qube (or another DisposableVM Template) by running the following command in a dom0 terminal. (If you enable `appmenus-dispvm` feature (as explained at the top), applications menu for this VM (`fedora-26-dvm`) will be "Disposable: fedora-26-dvm" (instead of "Domain: fedora-26-dvm") and entries there will start new DisposableVM 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
+    ```shell_session
+    [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:
+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 Firefox's default startup settings and homepage.
-    -   Changing default editor, image viewer. In Debian-based templates this can be done with the `mimeopen` command.
+    - Changing default editor, image viewer. In Debian-based templates this can be done with the `mimeopen` command.
-    -   Changing the DisposableVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DisposableVM, you can choose your desired ProxyVM manually (by changing the newly-started DisposableVMs settings). This is useful if you sometimes wish to use a DisposableVM with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DisposableVM.
+    - Changing the DisposableVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DisposableVM, you can choose your desired ProxyVM manually (by changing the newly-started DisposableVMs settings). This is useful if you sometimes wish to use a DisposableVM with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DisposableVM.
-
-4.  Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal).
 
+4. Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal).
 
 ## Using static DisposableVMs for sys-*
 
@@ -130,7 +136,6 @@ qvm-prefs sys-firewall netvm sys-net2
 qubes-prefs clockvm sys-net2
 ~~~
 
-
 ## Adding programs to DisposableVM Application Menu
 
 For added convenience, arbitrary programs can be added to the Application Menu of the DisposableVM. 
@@ -139,27 +144,27 @@ In order to do that, select "Qube settings" entry in selected base AppVM, go to
 
 Note that currently only applications whose main process keeps running until you close the application (i.e. do not start a background process instead) will work. One of known examples of incompatible applications is GNOME Terminal (shown on the list as "Terminal"). Choose different terminal emulator (like XTerm) instead.
 
-
 ## Create Custom sys-net sys-firewall and sys-usb DisposableVMs
 
 Users have the option of creating customized DisposableVMs for the `sys-net`, `sys-firewall` and `sys-usb` VMs. In this configuration, a fresh VM instance is created each time a DisposableVM is launched. Functionality is near-identical to the default VMs created following a new Qubes’ installation, except the user benefits from a non-persistent filesystem.
 
 Functionality is not limited, users can:
 
-   * Set custom firewall rule sets and run Qubes VPN scripts. 
+- Set custom firewall rule sets and run Qubes VPN scripts. 
-   * Set DisposableVMs to autostart at system boot.
+- Set DisposableVMs to autostart at system boot.
-   * Attach PCI devices with the `--persistent` option. 
+- Attach PCI devices with the `--persistent` option. 
 
 Using DisposableVMs in this manner is ideal for untrusted qubes which require persistent PCI devices, such as USB VMs and NetVMs.
 
 >_**Note:**_ Users who want customized VPN or firewall rule sets must create a separate DisposableVM Template for use by each DisposableVM. If DisposableVM Template customization is not needed, then a single DisposableVM Template is used as a template for all DisposableVMs.
 
-
 ### Create and configure the DisposableVM Template on which the DisposableVM will be based
 
 1. Create the DisposableVM Template:
 
-       [user@dom0 ~]$ qvm-create --class AppVM --label gray <DisposableVM-Template-Name>
+    ```shell_session
+    [user@dom0 ~]$ qvm-create --class AppVM --label gray <DisposableVM-Template-Name>
+    ```
 
 2. _(optional)_ In the DisposableVM Template, add custom firewall rule sets, Qubes VPN scripts, etc.
 
@@ -167,46 +172,65 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe
     
 3. Set the DisposableVM Template as template for DisposableVMs:
 
-       [user@dom0 ~]$ qvm-prefs <DisposableVM-Template-Name> template_for_dispvms true
+    ```shell_session
-
+    [user@dom0 ~]$ qvm-prefs <DisposableVM-Template-Name> template_for_dispvms true
+    ```
 
 ### Create the sys-net DisposableVM
 
 1. Create `sys-net` DisposableVM based on the DisposableVM Template:
 
-       [user@dom0 ~]$ qvm-create --template <DisposableVM-Template-Name> --class DispVM --label red disp-sys-net
+    ```shell_session
+    [user@dom0 ~]$ qvm-create --template <DisposableVM-Template-Name> --class DispVM --label red disp-sys-net
+    ```
 
 2. Set `disp-sys-net` virtualization mode to [hvm](/doc/hvm/):
 
-       [user@dom0 ~]$ qvm-prefs disp-sys-net virt_mode hvm
+    ```shell_session
+    [user@dom0 ~]$ qvm-prefs disp-sys-net virt_mode hvm
+    ```
 
 3. Set `disp-sys-net` to provide network for other VMs:
 
-       [user@dom0 ~]$ qvm-prefs disp-sys-net provides_network true
+    ```shell_session
+    [user@dom0 ~]$ qvm-prefs disp-sys-net provides_network true
+    ```
 
 4. Set `disp-sys-net` NetVM to none:
 
-       [user@dom0 ~]$ qvm-prefs disp-sys-net netvm ""
+    ```shell_session
+    [user@dom0 ~]$ qvm-prefs disp-sys-net netvm ""
+    ```
 
 5. List all available PCI devices to determine the correct _backend:BDF_ address(es) to assign to `disp-sys-net`:
 
-       [user@dom0 ~]$ qvm-pci
+    ```shell_session
+    [user@dom0 ~]$ qvm-pci
+    ```
 
 6. Attach the network PCI device(s) to `disp-sys-net` (finding and assigning PCI devices can be found [here](/doc/pci-devices/):
 
-       [user@dom0 ~]$ qvm-pci attach --persistent disp-sys-net <backend>:<bdf>
+    ```shell_session
+    [user@dom0 ~]$ qvm-pci attach --persistent disp-sys-net <backend>:<bdf>
+    ```
 
 7. _(recommended)_ Set `disp-sys-net` to start automatically when Qubes boots:
 
-       [user@dom0 ~]$ qvm-prefs disp-sys-net autostart true
+    ```shell_session
+    [user@dom0 ~]$ qvm-prefs disp-sys-net autostart true
+    ```
 
 8. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-net is not itself a DisposableVM template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the DisposableVM template):
 
-       [user@dom0 ~]$ qvm-features disp-sys-net appmenus-dispvm ''
+    ```shell_session
+    [user@dom0 ~]$ qvm-features disp-sys-net appmenus-dispvm ''
+    ```
 
 9. _(optional)_ Set `disp-sys-net` as the dom0 time source:
 
-       [user@dom0 ~]$ qubes-prefs clockvm disp-sys-net
+    ```shell_session
+    [user@dom0 ~]$ qubes-prefs clockvm disp-sys-net
+    ```
 
 10. _(recommended)_ Allow templates to be updated via `disp-sys-net`. In dom0, edit `/etc/qubes-rpc/policy/qubes.UpdatesProxy` to change the target from `sys-net` to `disp-sys-net`.
 
@@ -214,110 +238,147 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe
 
 1. Create `sys-firewall` DisposableVM:
 
-       [user@dom0 ~]$ qvm-create --template <DisposableVM-Template-Name> --class DispVM --label green disp-sys-firewall
+    ```shell_session
+    [user@dom0 ~]$ qvm-create --template <DisposableVM-Template-Name> --class DispVM --label green disp-sys-firewall
+    ```
 
 2. Set `disp-sys-firewall` to provide network for other VMs:
 
-       [user@dom0 ~]$ qvm-prefs disp-sys-firewall provides_network true
+    ```shell_session
+    [user@dom0 ~]$ qvm-prefs disp-sys-firewall provides_network true
+    ```
 
 3. Set `disp-sys-net` as the NetVM for `disp-sys-firewall`:
 
-       [user@dom0 ~]$ qvm-prefs disp-sys-firewall netvm disp-sys-net
+    ```shell_session
+    [user@dom0 ~]$ qvm-prefs disp-sys-firewall netvm disp-sys-net
+    ```
 
 4. Set `disp-sys-firewall` as NetVM for other AppVMs:
 
-       [user@dom0 ~]$ qvm-prefs <vm_name> netvm disp-sys-firewall
+    ```shell_session
+    [user@dom0 ~]$ qvm-prefs <vm_name> netvm disp-sys-firewall
+    ```
 
 5. _(recommended)_ Set `disp-sys-firewall` to auto-start when Qubes boots:
 
-       [user@dom0 ~]$ qvm-prefs disp-sys-firewall autostart true
+    ```shell_session
+    [user@dom0 ~]$ qvm-prefs disp-sys-firewall autostart true
+    ```
 
 6. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-firewall is not itself a DisposableVM template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the DisposableVM template):
 
-       [user@dom0 ~]$ qvm-features disp-sys-firewall appmenus-dispvm ''
+    ```shell_session
+    [user@dom0 ~]$ qvm-features disp-sys-firewall appmenus-dispvm ''
+    ```
 
 7. _(optional)_ Set `disp-sys-firewall` as the default NetVM:
 
-       [user@dom0 ~]$ qubes-prefs default_netvm disp-sys-firewall
+    ```shell_session
-
+    [user@dom0 ~]$ qubes-prefs default_netvm disp-sys-firewall
+    ```
 
 ### Create the sys-usb DisposableVM
 
 1. Create the `disp-sys-usb`:
 
-       [user@dom0 ~]$ qvm-create --template <disposablevm-template-name> --class DispVM --label red disp-sys-usb
+    ```shell_session
+    [user@dom0 ~]$ qvm-create --template <disposablevm-template-name> --class DispVM --label red disp-sys-usb
+    ```
 
 2. Set the `disp-sys-usb` virtualization mode to hvm:
 
-       [user@dom0 ~]$ qvm-prefs disp-sys-usb virt_mode hvm
+    ```shell_session
+    [user@dom0 ~]$ qvm-prefs disp-sys-usb virt_mode hvm
+    ```
 
 3. Set `disp-sys-usb` NetVM to none:
 
-       [user@dom0 ~]$ qvm-prefs disp-sys-usb netvm ""
+    ```shell_session
+    [user@dom0 ~]$ qvm-prefs disp-sys-usb netvm ""
+    ```
 
 4. List all available PCI devices:
 
-       [user@dom0 ~]$ qvm-pci
+    ```shell_session
+    [user@dom0 ~]$ qvm-pci
+    ```
 
 5. Attach the USB controller to the `disp-sys-usb`:
+   >_**Note:**_ Most of the commonly used USB controllers (all Intel integrated controllers) require the `-o no-strict-reset=True` option to be set. Instructions detailing how this option is set can be found [here](/doc/pci-devices/#no-strict-reset).
 
-     >_**Note:**_ Most of the commonly used USB controllers (all Intel integrated controllers) require the `-o no-strict-reset=True` option to be set. Instructions detailing how this option is set can be found [here](/doc/pci-devices/#no-strict-reset).
+    ```shell_session
-
+    [user@dom0 ~]$ qvm-pci attach --persistent disp-sys-usb <backined>:<bdf>
-       [user@dom0 ~]$ qvm-pci attach --persistent disp-sys-usb <backined>:<bdf>
+    ```
 
 6. _(optional)_ Set `disp-sys-usb` to auto-start when Qubes boots:
 
-       [user@dom0 ~]$ qvm-prefs disp-sys-usb autostart true
+    ```shell_session
+    [user@dom0 ~]$ qvm-prefs disp-sys-usb autostart true
+    ```
 
 7. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-usb is not itself a DisposableVM template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the DisposableVM template):
 
-       [user@dom0 ~]$ qvm-features disp-sys-usb appmenus-dispvm ''
+    ```shell_session
+    [user@dom0 ~]$ qvm-features disp-sys-usb appmenus-dispvm ''
+    ```
 
 8. Users should now follow instructions on [How to hide USB controllers from dom0](/doc/usb-qubes/#how-to-hide-all-usb-controllers-from-dom0).
 
 9. At this point, your mouse may not work.
    Edit the `qubes.InputMouse` policy file in dom0, which is located here:
 
-       /etc/qubes-rpc/policy/qubes.InputMouse
+    ```
+    /etc/qubes-rpc/policy/qubes.InputMouse
+    ```
 
    Add a line like this to the top of the file:
 
-       disp-sys-usb dom0 allow,user=root
+    ```
-
+    disp-sys-usb dom0 allow,user=root
+    ```
 
 ### Starting the DisposableVMs
 
 Prior to starting the new VMs, users should ensure that no other VMs such as the old `sys-net` and `sys-usb` VMs are running. This is because no two VMs can share the same PCI device while both running. It is recommended that users detach the PCI devices from the old VMs without deleting them. This will allow users to reattach the PCI devices if the newly created DisposableVMs fail to start. 
 
-   Detach PCI device from VM:
+Detach PCI device from VM:
-
-    [user@dom0~]$ qvm-pci detach <vm_name> <backend>:<bdf>
 
+```shell_session
+[user@dom0~]$ qvm-pci detach <vm_name> <backend>:<bdf>
+```
 
 ### Troubleshooting
 
 If the `disp-sys-usb` does not start, it could be due to a PCI passthrough problem. For more details on this issue along with possible solutions, users can look [here](/doc/pci-troubleshooting/#pci-passthrough-issues).
 
-
 ## Deleting DisposableVMs
 
 While working in a DisposableVM, you may want to open a document in another DisposableVM.
 For this reason, the property `default_dispvm` may be set to the name of your DisposableVM in a number of VMs:
 
-    [user@dom0 ~]$ qvm-prefs workvm | grep default_dispvm
+```shell_session
-    default_dispvm        -  custom-disposablevm-template
+[user@dom0 ~]$ qvm-prefs workvm | grep default_dispvm
+default_dispvm        -  custom-disposablevm-template
+```
 
 This will prevent the deletion of the DisposableVM Template. In order to fix this you need to unset the `default_dispvm` property:
 
-    [user@dom0 ~]$ qvm-prefs workvm default_dispvm ""
+```shell_session
+[user@dom0 ~]$ qvm-prefs workvm default_dispvm ""
+```
 
 You can then delete the DisposableVM Template:
 
-    [user@dom0 ~]$ qvm-remove custom-disposablevm-template
+```shell_session
-    This will completely remove the selected VM(s)
+[user@dom0 ~]$ qvm-remove custom-disposablevm-template
-      custom-disposablevm-template
+This will completely remove the selected VM(s)
+  custom-disposablevm-template
+```
+
       
 If you still encounter the issue, you may have forgot to clean an entry. Looking at the system logs will help you:
 
-    [user@dom0 ~]$ journalctl | tail
+```shell_session
-
+[user@dom0 ~]$ journalctl | tail
+```

user/advanced-configuration/gui-configuration.md

@@ -52,4 +52,3 @@ EndSection
 ## GUI Troubleshooting
 
 See [GUI Troubleshooting](/doc/gui-troubleshooting) for issues relating to the Qubes graphical user interface and how to fix them.
-

user/advanced-configuration/i3.md

@@ -15,7 +15,9 @@ i3 is part of the stable repository (as of Qubes R3.1) and can be installed by
 using the [dom0 update mechanism](/doc/software-update-dom0/). To install the i3
 window manager and the its Qubes specific configuration:
 
-    $ sudo qubes-dom0-update i3 i3-settings-qubes
+```shell_session
+$ sudo qubes-dom0-update i3 i3-settings-qubes
+```
 
 The Qubes-specific configuration (package `i3-settings-qubes`) can be installed
 optionally in case you would prefer writing your own configuration (see
@@ -43,7 +45,9 @@ installed through the package manager.
 
 Clone the i3-qubes repository here:
 
-    $ git clone https://github.com/QubesOS/qubes-desktop-linux-i3
+```shell_session
+$ git clone https://github.com/QubesOS/qubes-desktop-linux-i3
+```
 
 In this case, the most interesting file is probably
 `i3/0001-Show-qubes-domain-in-non-optional-colored-borders.patch` It's the patch
@@ -59,15 +63,19 @@ it.
 You'll need to install the build dependencies, which are listed in
 build-deps.list. You can verify them and then install them with:
 
-    $ sudo dnf install -y $(cat build-deps.list)
+```shell_session
+$ sudo dnf install -y $(cat build-deps.list)
+```
 
 This used to be more complicated, but I finally redid this and use the same
 buildsystem that's used by Qubes OS for XFCE. It's just a Makefile that helps
 you get the sources and start off the build:
 
-    $ make get-sources
+```shell_session
-    $ make verify-sources
+$ make get-sources
-    $ make rpms
+$ make verify-sources
+$ make rpms
+```
 
 ### Installing
 
@@ -79,17 +87,23 @@ next step.
 
 Now in dom0, copy in the rpm:
 
-    $ qvm-run --pass-io <src_domain> 'cat </path/to/rpm_in_src_domain>' > i3.rpm
+```shell_session
+$ qvm-run --pass-io <src_domain> 'cat </path/to/rpm_in_src_domain>' > i3.rpm
+```
 
 Now that the rpm is in dom0 we can proceed with installing it. i3 has some
 dependencies that we can easily install with:
 
-    $ sudo qubes-dom0-update perl-AnyEvent-I3 xorg-x11-apps \\
+```shell_session
-        rxvt-unicode xcb-util-wm perl-JSON-XS xcb-util-cursor \\
+$ sudo qubes-dom0-update perl-AnyEvent-I3 xorg-x11-apps \\
-        dzen2 dmenu xorg-x11-fonts-misc libev
+    rxvt-unicode xcb-util-wm perl-JSON-XS xcb-util-cursor \\
+    dzen2 dmenu xorg-x11-fonts-misc libev
+```
 
 After that you can just install the generated rpm like any other local package:
 
-    $ sudo yum localinstall i3.rpm
+```shell_session
+$ sudo yum localinstall i3.rpm
+```
 
 Log out, select i3, then log in again.

user/advanced-configuration/installing-contributed-packages.md

@@ -9,7 +9,6 @@ permalink: /doc/installing-contributed-packages/
 _This page is for users who wish to install contributed packages.
 If you want to contribute a package, please see [package contributions]._
 
-
 Qubes OS contributed packages are available under the [QubesOS-contrib] GitHub Project.
 This is a place where our community can [contribute Qubes OS related packages, additions and various customizations][package contributions].
 
@@ -19,20 +18,28 @@ If you want to install one of these packages, first you need to enable the repos
 
 In dom0, use `qubes-dom0-update`:
 
-    sudo qubes-dom0-update qubes-repo-contrib
+```bash_session
+sudo qubes-dom0-update qubes-repo-contrib
+```
 
 In a Fedora-based template, use `dnf`:
 
-    sudo dnf install qubes-repo-contrib
+```bash_session
+sudo dnf install qubes-repo-contrib
+```
 
 In a Debian-based template, use `apt`:
 
-    sudo apt update && sudo apt install qubes-repo-contrib
+```bash_session
+sudo apt update && sudo apt install qubes-repo-contrib
+```
 
 The new repository definition will be in the usual location for your distro, and it will follow the naming pattern `qubes-contrib-*`, depending on your Qubes release and whether it is in dom0 or a TemplateVM.
 For example, in a Fedora TemplateVM on Qubes 4.0, the new repository definition would be:
 
-    /etc/yum.repos.d/qubes-contrib-vm-r4.0.repo
+```
+/etc/yum.repos.d/qubes-contrib-vm-r4.0.repo
+```
 
 ## Installing packages
 
@@ -42,10 +49,11 @@ After you've installed the repositories, you can install contributed packages.
 
 For example, to install `qvm-screenshot-tool` in dom0:
 
-    sudo qubes-dom0-update --clean qvm-screenshot-tool
+```bash_session
+sudo qubes-dom0-update --clean qvm-screenshot-tool
+```
 
 Please see the package's README for specific installation and setup instructions.
 
 [package contributions]: /doc/package-contributions/
 [QubesOS-contrib]: https://github.com/QubesOS-contrib/
-

user/advanced-configuration/kde.md

@@ -15,30 +15,32 @@ Prior to R3.2, KDE was the default desktop environment in Qubes. Beginning with
 R3.2, however, [XFCE is the new default desktop environment](/doc/releases/3.2/release-notes/). Nonetheless, it is
 still possible to install KDE by issuing this command in dom0:
 
-    $ sudo qubes-dom0-update @kde-desktop-qubes
+```shell_session
+$ sudo qubes-dom0-update @kde-desktop-qubes
+```
 
 You can also change your default login manager (lightdm) to the new KDE default: sddm
 
- * first you need to edit the `/etc/sddm.conf` to make sure if the custom X parameter is set according to Qubes needs:
+* first you need to edit the `/etc/sddm.conf` to make sure if the custom X parameter is set according to Qubes needs:
 
-~~~
+    ~~~
    [XDisplay]
    ServerArguments=-nolisten tcp -background none
-~~~
+    ~~~
 
- * disable the lightdm service:
+* disable the lightdm service:
 
-~~~  
+    ~~~
    $ sudo systemctl disable lightdm
-~~~  
+    ~~~
 
- * enable the sddm service:
+* enable the sddm service:
 
-~~~
+    ~~~
     $ sudo systemctl enable sddm
-~~~
+    ~~~
 
- * reboot
+* reboot
 
 If you encounter performance issues with KDE, try switching back to LightDM.
 
@@ -77,12 +79,12 @@ Removal
 If you decide to remove KDE do **not** use `dnf remove @kde-desktop-qubes`. You will almost certainly break your system.
 
 The safest way to remove (most of) KDE is:
+
 ~~~
 sudo dnf remove kdelibs plasma-workspace
 ~~~
 
-
 Mailing List Threads
 --------------------
 
- * [Nalu's KDE customization thread](https://groups.google.com/d/topic/qubes-users/KhfzF19NG1s/discussion)
+* [Nalu's KDE customization thread](https://groups.google.com/d/topic/qubes-users/KhfzF19NG1s/discussion)

user/advanced-configuration/managing-vm-kernel.md

@@ -6,8 +6,7 @@ redirect_from:
 - /en/doc/managing-vm-kernel/
 ---
 
-VM kernel managed by dom0
+# VM kernel managed by dom0
-=========================
 
 By default, VMs kernels are provided by dom0.
 (See [here][dom0-kernel-upgrade] for information about upgrading kernels in dom0.)
@@ -58,8 +57,7 @@ nopat
 [user@dom0 ~]$ qvm-prefs -s work kernelopts "nopat apparmor=1 security=apparmor"
 ~~~
 
-Installing different kernel using Qubes kernel package
+## Installing different kernel using Qubes kernel package
-----------------------------------
 
 VM kernels are packages by Qubes team in `kernel-qubes-vm` packages.
 Generally, the system will keep the three newest available versions.
@@ -150,8 +148,7 @@ Installation of the new package is unaffected by this event.
 
 The newly installed package is set as the default VM kernel.
 
-Installing different VM kernel based on dom0 kernel
+## Installing different VM kernel based on dom0 kernel
----------------------------------------------------
 
 It is possible to package a kernel installed in dom0 as a VM kernel.
 This makes it possible to use a VM kernel which is not packaged by Qubes team.
@@ -217,20 +214,18 @@ mke2fs 1.42.12 (29-Aug-2014)
 --> Done.
 ~~~
 
-Kernel files structure
+## Kernel files structure
------------------------
 
 Kernel for a VM is stored in `/var/lib/qubes/vm-kernels/KERNEL_VERSION` directory (`KERNEL_VERSION` replaced with actual version). Qubes 4.x supports the following files there:
 
-- `vmlinuz` - kernel binary (may not be a Linux kernel)
+* `vmlinuz` - kernel binary (may not be a Linux kernel)
-- `initramfs` - initramfs for the kernel to load
+* `initramfs` - initramfs for the kernel to load
-- `modules.img` - ext4 filesystem image containing Linux kernel modules (to be mounted at `/lib/modules`); additionally it should contain a copy of `vmlinuz` and `initramfs` in its root directory (for loading by qemu inside stubdomain)
+* `modules.img` - ext4 filesystem image containing Linux kernel modules (to be mounted at `/lib/modules`); additionally it should contain a copy of `vmlinuz` and `initramfs` in its root directory (for loading by qemu inside stubdomain)
-- `default-kernelopts-common.txt` - default kernel options, in addition to those specified with `kernelopts` qube property (can be disabled with `no-default-kernelopts` feature)
+* `default-kernelopts-common.txt` - default kernel options, in addition to those specified with `kernelopts` qube property (can be disabled with `no-default-kernelopts` feature)
 
 All the files besides `vmlinuz` are optional in Qubes R4.1 or newer. In Qubes R4.0, `vmlinuz` and `initramfs` are both required to be present.
 
-Using kernel installed in the VM
+## Using kernel installed in the VM
---------------------------------
 
 Both debian-9 and fedora-26 templates already have grub and related tools preinstalled so if you want to use one of the distribution kernels, all you need to do is clone either template to a new one, then:
 
@@ -278,6 +273,7 @@ If you require `PV` mode, install `grub2-xen` in dom0 and change the template's
 Booting to a kernel inside the template is not supported under `PVH`.
 
 ### Installing kernel in Debian VM
+
 #### Distribution kernel
 
 Apply the following instruction in a Debian TemplateVM or in a Debian StandaloneVM.
@@ -292,7 +288,6 @@ sudo apt install linux-image-amd64 linux-headers-amd64 grub2 qubes-kernel-vm-sup
 
 If you are doing that on a qube based on "Debian Minimal" template, a grub gui will popup during the installation, asking you where you want to install the grub loader. You must select /dev/xvda (check the box using the space bar, and validate your choice with "Enter".)
 
-
 You can safely ignore this error message:
 `grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map`
 
@@ -320,43 +315,50 @@ Start the VM.
 The process of using Qubes VM kernel with distribution kernel is complete.
 
 #### Custom kernel
+
 Any kernel can be installed. Just make sure to install kernel headers as well.
 
 If you are building the kernel manually, do this using `dkms` and `initramfs-tools`.
 
 Run DKMS. Replace this <kernel-version> with actual kernel version.
 
-    sudo dkms autoinstall -k <kernel-version>
+```bash_session
+sudo dkms autoinstall -k <kernel-version>
+```
 
 For example.
 
-    sudo dkms autoinstall -k 4.19.0-6-amd64
+```bash_session
+sudo dkms autoinstall -k 4.19.0-6-amd64
+```
 
 Update initramfs.
 
-    sudo update-initramfs -u
+```bash_session
+sudo update-initramfs -u
+```
 
 The output should look like this:
 
-	$ sudo dkms autoinstall -k 3.16.0-4-amd64
+```shell_session
+$ sudo dkms autoinstall -k 3.16.0-4-amd64
 
-	u2mfn:
+u2mfn:
-	Running module version sanity check.
+Running module version sanity check.
-	 - Original module
+  - Original module
-	   - No original module exists within this kernel
+    - No original module exists within this kernel
-	 - Installation
+  - Installation
-	   - Installing to /lib/modules/3.16.0-4-amd64/updates/dkms/
+    - Installing to /lib/modules/3.16.0-4-amd64/updates/dkms/
 
-	depmod....
+depmod....
 
-	DKMS: install completed.
+  DKMS: install completed.
-	$ sudo update-initramfs -u
+$ sudo update-initramfs -u
-	update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64
+update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64
+```
 
 #### Troubleshooting
 
 In case of problems, visit the [VM Troubleshooting guide](/doc/vm-troubleshooting/#vm-kernel-troubleshooting) to learn how to access the VM console, view logs and fix a VM kernel installation.
 
-
 [dom0-kernel-upgrade]: /doc/software-update-dom0/#kernel-upgrade
-

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

@@ -24,33 +24,34 @@ Decrypting the Disk
 -----------------
 
 1. Find the disk to be accessed:
-	1. Open a Linux terminal in either dom0 or the AppVM the disk was passed through to and enter `lsblk`, which will result in an output similar to the following.
+    1. Open a Linux terminal in either dom0 or the AppVM the disk was passed through to and enter `lsblk`, which will result in an output similar to the following.
-	   In this example, the currently booted Qubes system is installed on `sda` and the qubes system to be accessed is on `nvme0n1p2`.
+        In this example, the currently booted Qubes system is installed on `sda` and the qubes system to be accessed is on `nvme0n1p2`.
-```
+
-	sda                                                                   8:0    0 111.8G  0 disk
+        ```
-	├─sda1                                                                8:1    0   200M  0 part  /boot/efi
+        sda                                                                   8:0    0 111.8G  0 disk
-	├─sda2                                                                8:2    0     1G  0 part  /boot
+        ├─sda1                                                                8:1    0   200M  0 part  /boot/efi
-	└─sda3                                                                8:3    0 110.6G  0 part
+        ├─sda2                                                                8:2    0     1G  0 part  /boot
-	  └─luks-fed62fc2-2674-266d-2667-2667259cbdec                       253:0    0 110.6G  0 crypt
+        └─sda3                                                                8:3    0 110.6G  0 part
-		├─qubes_dom0-pool00_tmeta                                       253:1    0    88M  0 lvm
+          └─luks-fed62fc2-2674-266d-2667-2667259cbdec                       253:0    0 110.6G  0 crypt
-		│ └─qubes_dom0-pool00-tpool                                     253:3    0  84.4G  0 lvm
+            ├─qubes_dom0-pool00_tmeta                                       253:1    0    88M  0 lvm
-		│   ├─qubes_dom0-root                                           253:4    0  84.4G  0 lvm   /
+            │ └─qubes_dom0-pool00-tpool                                     253:3    0  84.4G  0 lvm
-		│   ├─qubes_dom0-pool00                                         253:6    0  84.4G  0 lvm
+            │   ├─qubes_dom0-root                                           253:4    0  84.4G  0 lvm   /
-		│   ├─qubes_dom0-vm--fedora--30--dvm--private--1576749131--back 253:7    0     2G  0 lvm
+            │   ├─qubes_dom0-pool00                                         253:6    0  84.4G  0 lvm
-		├─qubes_dom0-pool00_tdata                                       253:2    0  84.4G  0 lvm
+            ├─qubes_dom0-vm--fedora--30--dvm--private--1576749131--back 253:7    0     2G  0 lvm
-		│ └─qubes_dom0-pool00-tpool                                     253:3    0  84.4G  0 lvm
+            ├─qubes_dom0-pool00_tdata                                       253:2    0  84.4G  0 lvm
-		│   ├─qubes_dom0-root                                           253:4    0  84.4G  0 lvm   /
+            │ └─qubes_dom0-pool00-tpool                                     253:3    0  84.4G  0 lvm
-		│   ├─qubes_dom0-pool00                                         253:6    0  84.4G  0 lvm
+            │   ├─qubes_dom0-root                                           253:4    0  84.4G  0 lvm   /
-		│   ├─qubes_dom0-vm--fedora--30--dvm--private--1576749131--back 253:7    0     2G  0 lvm
+            │   ├─qubes_dom0-pool00                                         253:6    0  84.4G  0 lvm
-		└─qubes_dom0-swap                                               253:5    0     4G  0 lvm   [SWAP]
+            │   ├─qubes_dom0-vm--fedora--30--dvm--private--1576749131--back 253:7    0     2G  0 lvm
-	sdb                                                                   8:16   0 447.1G  0 disk
+            └─qubes_dom0-swap                                               253:5    0     4G  0 lvm   [SWAP]
-	├─sdb1                                                                8:17   0   549M  0 part
+        sdb                                                                   8:16   0 447.1G  0 disk
-	└─sdb2                                                                8:18   0 446.6G  0 part
+        ├─sdb1                                                                8:17   0   549M  0 part
-	sr0                                                                  11:0    1  1024M  0 rom
+        └─sdb2                                                                8:18   0 446.6G  0 part
-	nvme0n1                                                             259:0    0 465.8G  0 disk
+        sr0                                                                  11:0    1  1024M  0 rom
-	├─nvme0n1p1                                                         259:1    0     1G  0 part
+        nvme0n1                                                             259:0    0 465.8G  0 disk
-	└─nvme0n1p2                                                         259:2    0 464.8G  0 part
+        ├─nvme0n1p1                                                         259:1    0     1G  0 part
-```
+        └─nvme0n1p2                                                         259:2    0 464.8G  0 part
+        ```
 
 2. Decrypt the disk using the command `cryptsetup luksOpen /dev/<disk>`.
 
@@ -58,13 +59,13 @@ Accessing LVM Logical Volumes
 -----------------------------
 
 3. If using an AppVM or standard Linux, LVM should automatically discover the Qubes LVM configuration. In this case, continue to step 4.
-	1. Qubes uses the default name `qubes_dom0` for it's LVM VG.
+    1. Qubes uses the default name `qubes_dom0` for it's LVM VG.
-	   This will conflict with the name of the VG of the currently installed system.
+       This will conflict with the name of the VG of the currently installed system.
-	   To read both, you will have to rename the VG.
+       To read both, you will have to rename the VG.
-	   *Note:* If this is not reversed, the Qubes install being accessed will not be bootable.
+       *Note:* If this is not reversed, the Qubes install being accessed will not be bootable.
-	2. Find the UUID of the vg to be accessed using the command `vgdisplay`.
+    2. Find the UUID of the vg to be accessed using the command `vgdisplay`.
-	   This will be the VG named `qubes_dom0` which is not marked active.
+       This will be the VG named `qubes_dom0` which is not marked active.
-	3. The command `vgrename <UUID> other_install` will rename the VG.
+    3. The command `vgrename <UUID> other_install` will rename the VG.
 4. Run the command `vgscan` to add any new VGs to the device list.
 
 Mounting the disk
@@ -72,12 +73,12 @@ Mounting the disk
 
 5. Find the disk to be accessed. The `lsblk` command above may be of use. The following rules apply by default:
 
-| Disk name           			| Data type     	| Explination   			    			  |
+| Disk name                     | Data type         | Explanation                                 |
 | ----------------------------- | ----------------- | ------------------------------------------- |
-| other\_install/root     		| dom0 root 		| The root partition of dom0. 			 	  |
+| other\_install/root           | dom0 root         | The root partition of dom0.                 |
-| other\_install/<vm>-private   | VM  				| The /rw partition of the named VM. 		  |
+| other\_install/<vm>-private   | VM                | The /rw partition of the named VM.          |
-| other\_install/<vm>-root      | templateVM root 	| The root partition of the named TemplateVM. |
+| other\_install/<vm>-root      | templateVM root   | The root partition of the named TemplateVM. |
-| other\_install/pool00\_tmeta     	| LVM Metadata 		| The metadata LV of this disk. 			  |
+| other\_install/pool00\_tmeta  | LVM Metadata      | The metadata LV of this disk.               |
 
 6. Mount the disk using the command `mount /dev/other_install/<lv name> <mountpoint>`.
    *Note:* Any compromised data which exists in the volume to be mounted will be accessible here.
@@ -87,11 +88,10 @@ At this point, all files are available in the chosen mountpoint.
 
 Reverting Changes
 -----------------------------------------
+
 Any changes which were made to the system in the above steps will need to be reverted before the disk will properly boot.
 However, LVM will not allow an VG to be renamed to a name already in use.
 Thes steps must occur either in an AppVM or using recovery media.
 
 1. Unmount any disks that were accessed.
 2. Rename the VG back to qubes\_dom0 using the command `vgrename other_install qubes_dom0`.
-
-

user/advanced-configuration/resize-disk-image.md

@@ -11,8 +11,7 @@ redirect_from:
 - /wiki/ResizeRootDiskImage/
 ---
 
-Resizing Disk Images
+## Resizing Disk Images
------------------
 
 By default Qubes uses thin volumes for the disk images.
 This means that space is not actually allocated for the volume until it is used.
@@ -24,8 +23,7 @@ You should keep an eye on the disk-space widget to see how much free space you a
 It is easy to increase the size of disk images.
 There are risks attached to reducing the size of an image, and in general you should not need to do this.
 
-Increasing the size of Disk Images
+## Increasing the size of 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.
 In most cases, the GUI tool Qube Settings (available for every qube from the Start menu, and also in the Qube Manager) will allow you to easily increase maximum disk image size.
@@ -45,7 +43,9 @@ Maximum size which can be assigned through Qube Settings is 1048576 MiB - if you
 ~~~
 qvm-volume extend <vm_name>:root <size>
 ~~~
+
 OR
+
 ~~~
 qvm-volume extend <vm_name>:private <size>
 ~~~
@@ -58,17 +58,17 @@ It is recommended that you restart (or start and then shutdown, if it is not run
 
 If you are **not** using Linux in the qube, you will also need to:
 
-1.  Start the template.
+1. Start the template.
-2.  Resize the filesystem using OS appropriate tools.
+2. Resize the filesystem using OS appropriate tools.
-3.  Verify available space in the template using `df -h` or OS specific tools.
+3. Verify available space in the template using `df -h` or OS specific tools.
-4.  Shutdown the template.
+4. Shutdown the template.
 
-#### Windows 7 ####
+#### Windows 7
 
-1.  Click Start
+1. Click Start
-2.  type "diskmgmt.msc" - this takes you to Disk Management
+2. type "diskmgmt.msc" - this takes you to Disk Management
-3.  Right-click on your existing volume, select "Extend Volume..."
+3. Right-click on your existing volume, select "Extend Volume..."
-4.  Click through the wizard.
+4. Click through the wizard.
 
 No reboot required.
 
@@ -87,8 +87,7 @@ Qubes will automatically grow the filesystem for you on all AppVMs with Qubes pa
 Otherwise, 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 `resize2fs` to make this space available.
 
-Decreasing the size of Disk Images
+## Decreasing the size of Disk Images
-----------------------------------
 
 The number shown for "storage max size" does not mean that the storage is really using that amount. In most cases you need not worry about the size shown.
 If you have increased the max size, and do not need it, then you *can*  reduce the allocated size, but there is a risk of data loss.
@@ -96,10 +95,10 @@ Remember you really dont need to do this.
 
 You can create a new qube, copy your files in to the new qube, and delete the old qube. (Simple and effective.)
 
-
 Or you can take the risk of reducing the size of the disk.
 For example, to reduce the private storage of qube1 to 1GiB:
 Open a terminal in dom0:
+
 ```
 qvm-shutdown qube1
 sudo lvresize --size 1024M /dev/qubes_dom0/vm-qube1-private
@@ -108,8 +107,3 @@ sudo lvresize --size 1024M /dev/qubes_dom0/vm-qube1-private
 If you have a SSD see [here][fstrim] for information on using fstrim.
 
 [fstrim]: /doc/disk-trim
-
-
-
-
-

user/advanced-configuration/rpc-policy.md

@@ -58,4 +58,3 @@ Further details about how this system works can be found in [Qrexec: command exe
 For more information, see the bulletin [here](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-038-2018.txt).*)
 
 [qrexec3]: /doc/qrexec3/
-

user/advanced-configuration/salt.md

@@ -85,10 +85,10 @@ The module used defines which parameters can be passed to it.
 There is a list of [officially available states][salt-doc-states].
 There are many very useful states:
 
-* For [managing files][salt-doc-states-file]: Use this to create files or 
+- For [managing files][salt-doc-states-file]: Use this to create files or
   directories and change them (append lines, replace text, set their content etc.)
-* For [installing and uninstalling][salt-doc-states-pkg] packages.
+- For [installing and uninstalling][salt-doc-states-pkg] packages.
-* For [executing shell commands][salt-doc-states-cmd].
+- For [executing shell commands][salt-doc-states-cmd].
 
 With these three states you can define most of the configuration of a VM.
 
@@ -157,19 +157,27 @@ with a `.` in their name.
 Now, because we use custom extensions to manage top files (instead of just
 enabling them all), to enable a particular top file you should issue command:
 
-    $ qubesctl top.enable my-new-vm
+```
+$ qubesctl top.enable my-new-vm
+```
 
 To list all enabled top files:
 
-    $ qubesctl top.enabled
+```
+$ qubesctl top.enabled
+```
 
 And to disable one:
 
-    $ qubesctl top.disable my-new-vm
+```
+$ qubesctl top.disable my-new-vm
+```
 
 To apply the states to dom0 and all VMs:
 
-    $ qubesctl --all state.highstate
+```
+$ qubesctl --all state.highstate
+```
 
 (More information on the `qubesctl` command further down.)
 
@@ -228,7 +236,6 @@ If you do so, then you need to pass additional arguments to the `qubesctl` tool:
       --app              Target all AppVMs
       --all              Target all non-disposable VMs (TemplateVMs and AppVMs)
 
-
 To apply a state to all templates, call `qubesctl --templates state.highstate`.
 
 The actual configuration is applied using `salt-ssh` (running over `qrexec`
@@ -273,14 +280,14 @@ Let's start with a quick example:
 It uses the Qubes-specific `qvm.present` state, which ensures that the domain is
 present (if not, it creates it).
 
-* The `name` flag informs Salt that the domain should be named `salt-test` (not 
+- The `name` flag informs Salt that the domain should be named `salt-test` (not
   `my new and shiny VM`).
-* The `template` flag informs Salt which template should be used for the domain.
+- The `template` flag informs Salt which template should be used for the domain.
-* The `label` flag informs Salt what color the domain should be.
+- The `label` flag informs Salt what color the domain should be.
-* The `mem` flag informs Salt how much RAM should be allocated to the domain.
+- The `mem` flag informs Salt how much RAM should be allocated to the domain.
-* The `vcpus` flag informs Salt how many Virtual CPUs should be allocated to the 
+- The `vcpus` flag informs Salt how many Virtual CPUs should be allocated to the
   domain
-* The `proxy` flag informs Salt that the domain should be a ProxyVM.
+- The `proxy` flag informs Salt that the domain should be a ProxyVM.
 
 As you will notice, the options are the same (or very similar) to those used in
 `qvm-prefs`.
@@ -297,11 +304,15 @@ without the `.sls` extension.
 
 To enable the particular top file you should issue the command:
 
-    $ qubesctl top.enable my-new-vm
+```
+$ qubesctl top.enable my-new-vm
+```
 
 To apply the state:
 
-    $ qubesctl state.highstate
+```
+$ qubesctl state.highstate
+```
 
 ### Example of Configuring a VM's System from Dom0
 
@@ -321,11 +332,15 @@ Then the appropriate top file (`/srv/salt/mc-everywhere.top`):
 
 Now you need to enable the top file:
 
-    $ qubesctl top.enable mc-everywhere
+```
+$ qubesctl top.enable mc-everywhere
+```
 
 And apply the configuration:
 
-    $ qubesctl --all state.highstate
+```
+$ qubesctl --all state.highstate
+```
 
 ## All Qubes-specific States
 
@@ -369,15 +384,16 @@ Ensures the specified domain is running:
       qvm.running:
         - name: salt-test4
 
-
 ## Virtual Machine Formulae
 
 You can use these formulae to download, install, and configure VMs in Qubes.
 These formulae use pillar data to define default VM names and configuration details.
 The default settings can be overridden in the pillar data located in:
+
 ```
 /srv/pillar/base/qvm/init.sls
 ```
+
 In dom0, you can apply a single state with `sudo qubesctl state.sls STATE_NAME`.
 For example, `sudo qubesctl state.sls qvm.personal` will create a `personal` VM (if it does not already exist) with all its dependencies (TemplateVM, `sys-firewall`, and `sys-net`).
 
@@ -472,16 +488,18 @@ Updates dom0
 
 Updates domUs. Example to update all TemplateVMs:
 
-    sudo qubesctl --skip-dom0 --templates state.sls update.qubes-vm
+```
+sudo qubesctl --skip-dom0 --templates state.sls update.qubes-vm
+```
 
 Useful options:
 
- - `--max-concurrency` --- Limits how many templates are updated at the same time.
+- `--max-concurrency` --- Limits how many templates are updated at the same time.
-   Adjust to your available RAM.
+  Adjust to your available RAM.
-   The default is 4, and the GUI updater sets it to 1.
+  The default is 4, and the GUI updater sets it to 1.
- - `--targets=vm1,vm2,...` --- Limit to specific VMs, instead of all of them.
+- `--targets=vm1,vm2,...` --- Limit to specific VMs, instead of all of them.
-   (Use instead of `--templates` or `--standalones`.)
+  (Use instead of `--templates` or `--standalones`.)
- - `--show-output` --- Show an update summary instead of just OK/FAIL.
+- `--show-output` --- Show an update summary instead of just OK/FAIL.
 
 For other options, see `qubesctl --help`.
 
@@ -495,10 +513,10 @@ Additional pillar data is available to ease targeting configurations (for exampl
 
 VM type. Possible values:
 
- - `admin` - Administration domain (`dom0`)
+- `admin` - Administration domain (`dom0`)
- - `template` - Template VM
+- `template` - Template VM
- - `standalone` - Standalone VM
+- `standalone` - Standalone VM
- - `app` - Template based AppVM
+- `app` - Template based AppVM
 
 ### `qubes:template`
 
@@ -508,7 +526,6 @@ Template name on which a given VM is based (if any).
 
 VM which provides network to the given VM
 
-
 ## Debugging
 
 The output for each VM is logged in `/var/log/qubes/mgmt-VM_NAME.log`.
@@ -521,8 +538,10 @@ If the log does not contain useful information:
    executed in the management VM.
 5. Get the last two lines:
 
+    ```shell_session
     $ export PATH="/usr/lib/qubes-vm-connector/ssh-wrapper:$PATH"
     $ salt-ssh "$target_vm" $salt_command
+    ```
 
   Adjust $target_vm (VM_NAME) and $salt_command (state.highstate).
 6. Execute them, fix problems, repeat.
@@ -534,7 +553,9 @@ If the log does not contain useful information:
 The fedora-24-minimal package is missing the `sudo` package.
 You can install it via:
 
-    $ qvm-run -p -u root fedora-24-minimal-template 'dnf install -y sudo'
+```shell_session
+$ qvm-run -p -u root fedora-24-minimal-template 'dnf install -y sudo'
+```
 
 The `-p` will cause the execution to wait until the package is installed.
 Having the `-p` flag is important when using a state with `cmd.run`.
@@ -550,13 +571,13 @@ The solution is to shut down the updateVM between each install:
 
 ## Further Reading
 
-* [Salt documentation][salt-doc]
+- [Salt documentation][salt-doc]
-* [Salt states][salt-doc-states] ([files][salt-doc-states-file], [commands][salt-doc-states-cmd], 
+- [Salt states][salt-doc-states] ([files][salt-doc-states-file], [commands][salt-doc-states-cmd],
   [packages][salt-doc-states-pkg], [ordering][salt-doc-states-order])
-* [Top files][salt-doc-top]
+- [Top files][salt-doc-top]
-* [Jinja templates][jinja]
+- [Jinja templates][jinja]
-* [Qubes specific modules][salt-qvm-doc]
+- [Qubes specific modules][salt-qvm-doc]
-* [Formulas for default Qubes VMs][salt-virtual-machines-states]
+- [Formulas for default Qubes VMs][salt-virtual-machines-states]
 
 [salt-doc]: https://docs.saltstack.com/en/latest/
 [salt-qvm-doc]: https://github.com/QubesOS/qubes-mgmt-salt-dom0-qvm/blob/master/README.rst

user/advanced-configuration/secondary-storage.md

@@ -8,13 +8,12 @@ redirect_from:
 - /wiki/SecondaryStorage/
 ---
 
-Storing AppVMs on Secondary Drives
+# Storing AppVMs on Secondary Drives
-==================================
 
 Suppose you have a fast but small primary SSD and a large but slow secondary HDD.
 You want to store a subset of your AppVMs on the HDD.
 
-## Instructions ##
+## Instructions
 
 Qubes 4.0 is more flexible than earlier versions about placing different VMs on different disks.
 For example, you can keep templates on one disk and AppVMs on another, without messy symlinks.
@@ -24,70 +23,94 @@ See also [this example](https://www.linux.com/blog/how-full-encrypt-your-linux-s
 
 First, collect some information in a dom0 terminal:
 
-    sudo pvs
+```
-    sudo lvs
+sudo pvs
+sudo lvs
+```
 
 Take note of the VG and thin pool names for your HDD, then register it with Qubes:
 
-    # <pool_name> is a freely chosen pool name
+```shell_session
-    # <vg_name> is LVM volume group name
+# <pool_name> is a freely chosen pool name
-    # <thin_pool_name> is LVM thin pool name
+# <vg_name> is LVM volume group name
-    qvm-pool --add <pool_name> lvm_thin -o volume_group=<vg_name>,thin_pool=<thin_pool_name>,revisions_to_keep=2
+# <thin_pool_name> is LVM thin pool name
+qvm-pool --add <pool_name> lvm_thin -o volume_group=<vg_name>,thin_pool=<thin_pool_name>,revisions_to_keep=2
+```
 
 Now, you can create qubes in that pool:
 
-    qvm-create -P <pool_name> --label red <vmname>
+```
+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> <sourceVMname> <cloneVMname>
+```
-    qvm-remove <sourceVMname>
+qvm-clone -P <pool_name> <sourceVMname> <cloneVMname>
+qvm-remove <sourceVMname>
+```
 
 If that was a template, or other qube referenced elsewhere (NetVM or such), you will need to adjust those references manually after moving.
 For example:
 
-    qvm-prefs <appvmname_based_on_old_template> template <new_template_name>
+```
+qvm-prefs <appvmname_based_on_old_template> template <new_template_name>
+```
 
 In theory, you can still use file-based disk images ("file" pool driver), but it lacks some features such as you won't be able to do backups without shutting down the qube.
 
-### Example HDD setup ###
+### Example HDD setup
 
 Assuming the secondary hard disk is at /dev/sdb (it will be completely erased), you can set it up for encryption by doing in a dom0 terminal (use the same passphrase as the main Qubes disk to avoid a second password prompt at boot):
 
-    sudo cryptsetup luksFormat --hash=sha512 --key-size=512 --cipher=aes-xts-plain64 --verify-passphrase /dev/sdb
+```
-    sudo blkid /dev/sdb
+sudo cryptsetup luksFormat --hash=sha512 --key-size=512 --cipher=aes-xts-plain64 --verify-passphrase /dev/sdb
+sudo blkid /dev/sdb
+```
 
 Note the device's UUID (in this example "b209..."), we will use it as its luks name for auto-mounting at boot, by doing:
 
-    sudo nano /etc/crypttab
+```
+sudo nano /etc/crypttab
+```
 
 And adding this line (change both "b209..." for your device's UUID from blkid) to crypttab:
 
-    luks-b20975aa-8318-433d-8508-6c23982c6cde UUID=b20975aa-8318-433d-8508-6c23982c6cde none
+```
+luks-b20975aa-8318-433d-8508-6c23982c6cde UUID=b20975aa-8318-433d-8508-6c23982c6cde none
+```
 
 Reboot the computer so the new luks device appears at /dev/mapper/luks-b209... and we can then create its pool, by doing this on a dom0 terminal (substitute the b209... UUIDs with yours):
 
 First create the physical volume
 
-    sudo pvcreate /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde 
+```
+sudo pvcreate /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde
+```
 
 Then create the LVM volume group, we will use for example "qubes" as the <vg_name>:
 
-    sudo vgcreate qubes /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde 
+```
+sudo vgcreate qubes /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde
+```
 
 And then use "poolhd0" as the <thin_pool_name> (LVM thin pool name):
 
-    sudo lvcreate -T -n poolhd0 -l +100%FREE qubes
+```
+sudo lvcreate -T -n poolhd0 -l +100%FREE qubes
+```
 
 Finally we will tell Qubes to add a new pool on the just created thin pool
 
-    qvm-pool --add poolhd0_qubes lvm_thin -o volume_group=qubes,thin_pool=poolhd0,revisions_to_keep=2
+```
+qvm-pool --add poolhd0_qubes lvm_thin -o volume_group=qubes,thin_pool=poolhd0,revisions_to_keep=2
+```
 
 By default VMs will be created on the main Qubes disk (i.e. a small SSD), to create them on this secondary HDD do the following on a dom0 terminal:
 
-    qvm-create -P poolhd0_qubes --label red unstrusted-hdd
+```
-
+qvm-create -P poolhd0_qubes --label red unstrusted-hdd
+```
 
 [Qubes Backup]: /doc/BackupRestore/
 [TemplateVM]: /doc/Templates/
-

user/advanced-configuration/usb-qubes.md

@@ -16,7 +16,6 @@ If during installation you enabled the creation of a USB-qube, your system shoul
 
 **Caution:** If you want to use a USB-keyboard, please beware of the possibility to lock yourself out! To avoid this problem [enable your keyboard for login]!
 
-
 ## Creating and Using a USB qube ##
 
 **Warning:** This has the potential to prevent you from connecting a keyboard to Qubes via USB.
@@ -29,31 +28,32 @@ The USB controller may be assigned on the **Devices** tab of a qube's settings p
 For guidance on finding the correct USB controller, see the [according passage on PCI-devices][usb-controller].
 You can create a USB qube using the management stack by performing the following steps as root in dom0:
 
-    sudo qubesctl state.sls qvm.sys-usb
+```
+sudo qubesctl state.sls qvm.sys-usb
+```
 
 Alternatively, you can create a USB qube manually as follows:
 
- 1.  Read the [PCI Devices] page to learn how to list and identify your USB controllers.
+1. Read the [PCI Devices] page to learn how to list and identify your USB controllers.
-     Carefully check whether you have a USB controller that would be appropriate to assign to a USB qube.
+   Carefully check whether you have a USB controller that would be appropriate to assign to a USB qube.
-     Note that it should be free of input devices, programmable devices, and any other devices that must be directly available to dom0.
+   Note that it should be free of input devices, programmable devices, and any other devices that must be directly available to dom0.
-     If you find a free controller, note its name and proceed to step 2.
+   If you find a free controller, note its name and proceed to step 2.
- 2.  Create a new qube.
+2. Create a new qube.
-     Give it an appropriate name and color label (recommended: `sys-usb`, red).
+   Give it an appropriate name and color label (recommended: `sys-usb`, red).
- 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 that you identified in step 1 in the "Available" list.
+   Find the USB controller that you identified in step 1 in the "Available" list.
-     Move it to the "Selected" list by highlighting it and clicking the single arrow `>` button.
+   Move it to the "Selected" list by highlighting it and clicking the single arrow `>` button.
 
-     **Caution:** By assigning a USB controller to a USB qube, it will no longer be available to dom0.
+   **Caution:** By assigning a USB controller to a USB qube, it will no longer be available to dom0.
-     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.
+   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.
 
- 4.  Click `OK`.
+4. Click `OK`.
-     Restart the qube.
+   Restart the qube.
- 5.  Recommended: Check the box on the "Basic" tab which says "Start VM automatically on boot".
+5. Recommended: Check the box on the "Basic" tab which says "Start VM automatically on boot".
-     (This will help to mitigate attacks in which someone forces your system to reboot, then plugs in a malicious USB device.)
+   (This will help to mitigate attacks in which someone forces your system to reboot, then plugs in a malicious USB device.)
 
 If the USB qube will not start, please have a look at the [faq].
 
-
 ## Enable a USB keyboard for login ##
 
 **Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding!
@@ -62,12 +62,13 @@ If you use USB keyboard, automatic USB qube creation during installation is disa
 Additional steps are required to avoid locking you out from the system.
 Those steps are not performed by default, because of risk explained in [Security Warning about USB Input Devices].
 
-
 ### Automatic setup ###
 
 To allow USB keyboard usage (including early boot for LUKS passphrase), make sure you have the latest `qubes-mgmt-salt-dom0-virtual-machines` package (simply [install dom0 updates]) and execute in dom0:
 
-    sudo qubesctl state.sls qvm.usb-keyboard
+```
+sudo qubesctl state.sls qvm.usb-keyboard
+```
 
 The above command will take care of all required configuration, including creating USB qube if not present.
 Note that it will expose dom0 to USB devices while entering LUKS passphrase.
@@ -77,17 +78,20 @@ To undo these changes, please follow the section on [**Removing a USB qube**][re
 
 If you wish to perform only a subset of this configuration (for example do not enable USB keyboard during boot), see manual instructions below.
 
-
 ### Manual setup ###
 
 In order to use a USB keyboard, you must first attach it to a USB qube, then give that qube permission to pass keyboard input to dom0.
 Edit the `qubes.InputKeyboard` policy file in dom0, which is located here:
 
-    /etc/qubes-rpc/policy/qubes.InputKeyboard
+```
+/etc/qubes-rpc/policy/qubes.InputKeyboard
+```
 
 Add a line like this one to the top of the file:
 
-    sys-usb dom0 allow
+```
+sys-usb dom0 allow
+```
 
 (Change `sys-usb` to your desired USB qube.)
 
@@ -95,14 +99,15 @@ You can now use your USB keyboard to login and for LUKS decryption during boot.
 
 For a confirmation dialog each time the USB keyboard is connected, *which will effectively disable your USB keyboard for login and LUKS decryption*, change this line to:
 
-    sys-usb dom0 ask,default_target=dom0
+```
+sys-usb dom0 ask,default_target=dom0
+```
 
 *Don't do that if you want to unlock your device with a USB keyboard!*
 
 Additionally, if you want to use USB keyboard to enter LUKS passphrase, it is incompatible with [hiding USB controllers from dom0].
 You need to revert that procedure (remove `rd.qubes.hide_all_usb` option from files mentioned there) and employ alternative protection during system boot - disconnect other devices during startup.
 
-
 ## Auto Enabling A USB Mouse ##
 
 **Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding.
@@ -111,21 +116,26 @@ Handling a USB mouse isn't as critical as handling a keyboard, since you can log
 
 If you want to attach the USB mouse automatically anyway, you have to edit the `qubes.InputMouse` policy file in dom0, located at:
 
-    /etc/qubes-rpc/policy/qubes.InputMouse
+```
+/etc/qubes-rpc/policy/qubes.InputMouse
+```
 
 The first line should read similar to:
 
-    sys-usb dom0 ask,default_target=dom0
+```
+sys-usb dom0 ask,default_target=dom0
+```
 
 which will ask for conformation each time a USB mouse is attached. If the file is empty or does not exist, maybe something went wrong during setup, try to rerun `qubesctl state.sls qvm.sys-usb` in dom0.
 
 In case you are absolutely sure you do not want to confirm mouse access from `sys-usb` to `dom0`, you may add the following line on top of the file:
 
-    sys-usb dom0 allow
+```
+sys-usb dom0 allow
+```
 
 (Change `sys-usb` to your desired USB qube.)
 
-
 ## How to hide all USB controllers from dom0 ##
 
 (Note: `rd.qubes.hide_all_usb` is set automatically if you opt to create a USB qube during installation.
@@ -149,49 +159,47 @@ If dom0 cannot read your USB AEM device, AEM will hang.
 
 The procedure to hide all USB controllers from dom0 is as follows:
 
- * GRUB2
+* GRUB2
 
- 1. Open the file `/etc/default/grub` in dom0.
+  1. Open the file `/etc/default/grub` in dom0.
- 2. Find the line that begins with `GRUB_CMDLINE_LINUX`.
+  2. Find the line that begins with `GRUB_CMDLINE_LINUX`.
- 3. Add `rd.qubes.hide_all_usb` to that line.
+  3. Add `rd.qubes.hide_all_usb` to that line.
- 4. Save and close the file.
+  4. Save and close the file.
- 5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
+  5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
- 6. Reboot.
+  6. Reboot.
 
- * EFI
+* EFI
- 
- 1. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0.
- 2. Find the lines that begin with `kernel=`. There may be more than one.
- 3. Add `rd.qubes.hide_all_usb` to those lines.
- 4. Save and close the file.
- 5. Reboot.
 
+  1. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0.
+  2. Find the lines that begin with `kernel=`. There may be more than one.
+  3. Add `rd.qubes.hide_all_usb` to those lines.
+  4. Save and close the file.
+  5. Reboot.
 
 ## Removing a USB qube ##
 
 **Warning:** This procedure will result in your USB controller(s) being attached directly to dom0.
 
- * GRUB2
+* GRUB2
 
- 1. Shut down the USB qube.
+  1. Shut down the USB qube.
- 2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
+  2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
- 3. Open the file `/etc/default/grub` in dom0.
+  3. Open the file `/etc/default/grub` in dom0.
- 4. Find the line(s) that begins with `GRUB_CMDLINE_LINUX`.
+  4. Find the line(s) that begins with `GRUB_CMDLINE_LINUX`.
- 5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it.
+  5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it.
- 6. Save and close the file.
+  6. Save and close the file.
- 7. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
+  7. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
- 8. Reboot.
+  8. Reboot.
 
- * EFI
+* EFI
- 
- 1. Shut down the USB qube.
- 2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
- 3. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0.
- 4. Find the line(s) that begins with `kernel=`.
- 5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it.
- 6. Save and close the file.
- 7. Reboot.
 
+  1. Shut down the USB qube.
+  2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
+  3. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0.
+  4. Find the line(s) that begins with `kernel=`.
+  5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it.
+  6. Save and close the file.
+  7. Reboot.
 
 [remove your USB-qube]: #removing-a-usb-qube
 [security implications]: /doc/device-handling-security/#usb-security

user/common-tasks/backup-emergency-restore-v2.md

@@ -21,7 +21,7 @@ any GNU/Linux system with the following procedure.
 **Note:** In the following example, the backup file is assumed to be both
 encrypted and compressed.
 
-1.  Untar the main backup file.
+1. Untar the main backup file.
 
     ~~~
     [user@restore ~]$ tar -i -xvf qubes-backup-2013-12-26-123456
@@ -41,7 +41,7 @@ encrypted and compressed.
     dom0-home/dom0user.000.hmac
     ~~~
 
-2.  Verify the integrity of the `private.img` file which houses your data.
+2. Verify the integrity of the `private.img` file which houses your data.
 
     ~~~
     [user@restore ~]$ cd vm1/
@@ -59,7 +59,7 @@ encrypted and compressed.
   complete list of supported message digest algorithms can be found with
   `openssl list-message-digest-algorithms`.
 
-3.  Decrypt the `private.img` file.
+3. Decrypt the `private.img` file.
 
     ~~~
     [user@restore vm1]$ openssl enc -d -pass pass:your_passphrase -aes-256-cbc -in private.img.000 -out private.img.dec.000
@@ -79,7 +79,7 @@ encrypted and compressed.
   list of supported cipher algorithms can be found with `openssl
   list-cipher-algorithms`.
 
-4.  Decompress the decrypted `private.img` file.
+4. Decompress the decrypted `private.img` file.
 
     ~~~
     [user@restore vm1]$ zforce private.img.dec.*
@@ -89,7 +89,7 @@ encrypted and compressed.
   **Note:** If your backup was compressed with a program other than `gzip`, you
   must substitute the correct compression program.
 
-5.  Untar the decrypted and decompressed `private.img` file.
+5. Untar the decrypted and decompressed `private.img` file.
 
     ~~~
     [user@restore vm1]$ tar -M -xvf private.img.dec.000
@@ -98,7 +98,7 @@ encrypted and compressed.
 
     **Note:** For multi-part files, a script is required:
 
-    1.  Create a `new-volume-script`:
+    1. Create a `new-volume-script`:
 
         ~~~
         #!/bin/sh
@@ -107,11 +107,11 @@ encrypted and compressed.
         echo $name.$suffix >&$TAR_FD
         ~~~
 
-    2.  `chmod +x new-volume-script`.
+    2. `chmod +x new-volume-script`.
-    3.  `tar --new-volume-script=./new-volume-script -xvf private.img.dec.000`.
+    3. `tar --new-volume-script=./new-volume-script -xvf private.img.dec.000`.
         (The `--new-volume-script` option enables multi-volume untaring.)
 
-6.  Mount the private.img file and access your data.
+6. Mount the private.img file and access your data.
 
     ~~~
     [user@restore vm1]$ sudo mkdir /mnt/img
@@ -123,6 +123,4 @@ encrypted and compressed.
   **Note:** You may wish to store a plain text copy of these instructions with
   your Qubes backups in the event that you fail to recall the above procedure
   while this web page is inaccessible. You may obtain a plaintext version of
-  this file in Git repository housing all the documentation at:
+  this file in Git repository housing all the documentation on [Github](https://github.com/QubesOS/qubes-doc.git)
-
-    https://github.com/QubesOS/qubes-doc.git

user/common-tasks/backup-emergency-restore-v3.md

@@ -137,4 +137,3 @@ any GNU/Linux system with the following procedure.
     repository:
 
         https://github.com/QubesOS/qubes-doc.git
-

user/common-tasks/backup-emergency-restore-v4.md

@@ -18,7 +18,6 @@ mind. No special Qubes-specific tools are required to access data backed up by
 Qubes. In the event a Qubes system is unavailable, you can access your data on
 any GNU/Linux system with the following procedure.
 
-
 Required `scrypt` Utility
 -------------------------
 
@@ -71,7 +70,6 @@ any GNU/Linux system.
 
         [user@restore ~]$ alias scrypt="scrypt-*/usr/bin/scrypt"
 
-
 Emergency Recovery Instructions
 -------------------------------
 
@@ -185,4 +183,3 @@ Emergency Recovery Instructions
 [get and verify the Release 4 Signing Key]: /security/verifying-signatures/#2-get-the-release-signing-key
 [Emergency Backup Recovery without Qubes (v2)]: /doc/backup-emergency-restore-v2/
 [Emergency Backup Recovery without Qubes (v3)]: /doc/backup-emergency-restore-v3/
-

user/common-tasks/backup-restore.md

@@ -83,7 +83,6 @@ Creating a backup
    This step is optional but strongly recommended.
    A backup is useless if you can't restore your data from it, and you can't be sure that your backup is good until you try to restore.
 
-
 Restoring from a backup
 -----------------------
 
@@ -101,10 +100,10 @@ This brings up the **Qubes Restore VMs** window.
    Once you've located the backup file, double-click it or select it and hit **OK**.
 
 3. There are three options you may select when restoring from a backup:
-   1.  **ignore missing templates and net VMs**: If any of the VMs in your backup depended upon a NetVM or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway and set them to use the default NetVM and system default template.
+   1. **ignore missing templates and net VMs**: If any of the VMs in your backup depended upon a NetVM or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway and set them to use the default NetVM and system default template.
-   2.  **ignore username mismatch**: This option applies only to the restoration of dom0's home directory.
+   2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory.
    If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway.
-   3.  **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data.
+   3. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data.
    However, it does not currently detect if it is missing data as long as it is a correctly structured, non-corrupted backup file.
    See [issue #3498](https://github.com/QubesOS/qubes-issues/issues/3498) for more details.
 
@@ -128,8 +127,7 @@ If the contents from the dom0 backup were instead to overwrite the existing file
 However, if you do wish to move all files from the dom0 backup out of the subdirectory into your current dom0 home directory (overwriting any existing files in the process), you may do so by following the instructions [here](https://stackoverflow.com/questions/20192070/how-to-move-all-files-including-hidden-files-into-parent-directory-via).
 Just remember that this can cause unexpected and desired configuration changes in dom0, depending on exactly which files you're adding and replacing.
 
-
+Emergency backup recovery without qubes
-Emergency backup recovery without Qubes
 ---------------------------------------
 
 The Qubes backup system has been designed with emergency disaster recovery in mind.
@@ -138,10 +136,9 @@ In the event a Qubes system is unavailable, you can access your data on any GNU/
 
 Refer to the following for emergency restore of a backup created on:
 
- * [Qubes R4 or newer](/doc/backup-emergency-restore-v4/)
+- [Qubes R4 or newer](/doc/backup-emergency-restore-v4/)
- * [Qubes R3](/doc/backup-emergency-restore-v3/)
+- [Qubes R3](/doc/backup-emergency-restore-v3/)
- * [Qubes R2 or older](/doc/backup-emergency-restore-v2/)
+- [Qubes R2 or older](/doc/backup-emergency-restore-v2/)
-
 
 Migrating between two physical machines
 ---------------------------------------
@@ -154,18 +151,17 @@ Choosing a backup passphrase
 
 Here are some things to consider when selecting a passphrase for your backups:
 
- * If you plan to store the backup for a long time or on third-party servers, you should make sure to use a very long, high-entropy passphrase. 
+- If you plan to store the backup for a long time or on third-party servers, you should make sure to use a very long, high-entropy passphrase.
  (Depending on the decryption passphrase you use for your system drive, this may necessitate selecting a stronger passphrase.
  If your system drive decryption passphrase is already sufficiently strong, it may not.)
- * An adversary who has access to your backups may try to substitute one backup for another. 
+- An adversary who has access to your backups may try to substitute one backup for another.
  For example, when you attempt to retrieve a recent backup, the adversary may instead give you a very old backup containing a compromised VM.
  If you're concerned about this type of attack, you may wish to use a different passphrase for each backup, e.g., by appending a number or date to the passphrase.
- * If you're forced to enter your system drive decryption passphrase in plain view of others (where it can be shoulder-surfed), then you may want to use a different passphrase for your backups (even if your system drive decryption passphrase is already maximally strong).
+- If you're forced to enter your system drive decryption passphrase in plain view of others (where it can be shoulder-surfed), then you may want to use a different passphrase for your backups (even if your system drive decryption passphrase is already maximally strong).
  On the other hand, if you're careful to avoid shoulder-surfing and/or have a passphrase that's difficult to detect via shoulder-surfing, then this may not be a problem for you.
 
 Notes
 -----
 
- * For the technical details of the backup system, please refer to [this thread](https://groups.google.com/d/topic/qubes-devel/TQr_QcXIVww/discussion).
+- For the technical details of the backup system, please refer to [this thread](https://groups.google.com/d/topic/qubes-devel/TQr_QcXIVww/discussion).
- * If working with symlinks, note the issues described in [this thread](https://groups.google.com/d/topic/qubes-users/EITd1kBHD30/discussion).
+- If working with symlinks, note the issues described in [this thread](https://groups.google.com/d/topic/qubes-users/EITd1kBHD30/discussion).
-

user/common-tasks/block-devices.md

@@ -9,14 +9,13 @@ redirect_from:
 - /wiki/StickMounting/
 ---
 
-# Block (Storage) Devices #
+# Block (Storage) Devices
 
 *This page is part of [device handling in qubes].*
 
 If you don't know what a "block device" is, just think of it as a fancy way to say "something that stores data".
 
-
+## Using The GUI to Attach a Drive
-## Using The GUI to Attach a Drive ##
 
 (**Note:** In the present context, the term "USB drive" denotes any [USB mass storage device][mass-storage].
 In addition to smaller flash memory sticks, this includes things like USB external hard drives.)
@@ -39,15 +38,16 @@ Click on one and your USB drive will be attached!
 However, it often means the AppVM won't detect the new partition and you will need to manually mount it inside the AppVM.
 See below for more detailed steps.
 
-
+## Block Devices in VMs
-## Block Devices in VMs ##
 
 If not specified otherwise, block devices will show up as `/dev/xvdi*` in a linux VM, where `*` may be the partition-number.
 If a block device isn't automatically mounted after attaching, open a terminal in the VM and execute:
 
-    cd ~
+```
-    mkdir mnt
+cd ~
-    sudo mount /dev/xvdi2 mnt
+mkdir mnt
+sudo mount /dev/xvdi2 mnt
+```
 
 where `xvdi2` needs to be replaced with the partition you want to mount.
 This will make your drive content accessible under `~/mnt`.
@@ -58,8 +58,7 @@ If several different block-devices are attached to a single VM, the last letter
 
 To specify this device node name, you need to use the command line tool and its [`frontend-dev`-option][frontend-dev].
 
-
+## Command Line Tool Guide
-## Command Line Tool Guide ##
 
 The command-line tool you may use to mount whole USB drives or their partitions is `qvm-block`, a shortcut for `qvm-device block`.
 
@@ -69,76 +68,89 @@ So make sure you have the drive available in the sourceVM, then list the availab
 In case of a USB-drive, make sure it's attached to your computer.
 If you don't see anything that looks like your drive, run `sudo udevadm trigger --action=change` in your USB-qube (typically `sys-usb`)
 
- 1. In a dom0 console (running as a normal user), list all available block devices:
+1. In a dom0 console (running as a normal user), list all available block devices:
 
-        qvm-block
+    ```
+    qvm-block
+    ```
 
     This will list all available block devices in your system across all VMs.
     The name of the qube hosting the block device is displayed before the colon in the device ID.
     The string after the colon is the ID of the device used within the qube, like so:
 
-        sourceVM:sdb     Cruzer () 4GiB
+    ```
-        sourceVM:sdb1    Disk () 2GiB
+    sourceVM:sdb     Cruzer () 4GiB
+    sourceVM:sdb1    Disk () 2GiB
+    ```
 
- 2. Assuming your block device is attached to `sys-usb` and its device node is `sdb`, we attach the device to a qube with the name `work` like so:
+2. Assuming your block device is attached to `sys-usb` and its device node is `sdb`, we attach the device to a qube with the name `work` like so:
 
-        qvm-block attach work sys-usb:sdb
+    ```
+    qvm-block attach work sys-usb:sdb
+    ```
 
     This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc.
 
     You may also mount one partition at a time by using the same command with the partition number, e.g. `sdb1`.
 
- 3. The block device is now attached to the qube.
+3. The block device is now attached to the qube.
-    If using a default qube, you may open the Nautilus file manager in the qube, and your drive should be visible in the **Devices** panel on the left.
+   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.
-    If you've attached a single partition (e.g. `sdb2` instead of `sdb` in our example), you may need to manually mount before it becomes visible:
+   If you've attached a single partition (e.g. `sdb2` instead of `sdb` in our example), you may need to manually mount before it becomes visible:
 
-        cd ~
+    ```
-        mkdir mnt
+    cd ~
-        sudo mount /dev/xvdi mnt
+    mkdir mnt
+    sudo mount /dev/xvdi mnt
+    ```
 
-
+4. When you finish using the block device, click the eject button or right-click and select **Unmount**.
- 4. When you finish using the block device, click the eject button or right-click and select **Unmount**.
 
     If you've manually mounted a single partition in the above step, use:
 
-        sudo umount mnt
+    ```
+    sudo umount mnt
+    ```
 
- 5. In a dom0 console, detach the device
+5. In a dom0 console, detach the device
 
-        qvm-block detach work sys-usb:sdb
+    ```
+    qvm-block detach work sys-usb:sdb
+    ```
 
- 6.  You may now remove the device or attach it to another qube.
+6. You may now remove the device or attach it to another qube.
 
-
+## Recovering From Premature Device Destruction
-## Recovering From Premature Device Destruction ##
 
 If the you fail to detach the device before it's destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), [there will be problems][premature removal].
 
 To recover from this error state, in dom0 run
 
-    virsh detach-disk targetVM xvdi
+```
+virsh detach-disk targetVM xvdi
+```
 
 (where `targetVM` is to be replaced with the VM name you attached the device to and `xvdi` is to be replaced with the used [frontend device node][frontend-dev].)
 
 However, if the block device originated in dom0, you will have to refer to the next section.
 
-
+### What if I removed the device before detaching it from the VM?
-### What if I removed the device before detaching it from the VM? ###
 
 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.
 The easiest way to recover from such a situation is to reboot the qube to which the device was attached.
 If this isn't an option, you can manually recover from the situation by following these steps:
 
- 1. Physically connect the device back.
+1. Physically connect the device back.
-    You can use any device as long as it 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` command.
+2. Attach the device manually to the same VM using the `xl block-attach` command.
-    It is important to use the same "frontend" device name (by default, `xvdi`).
+   It is important to use the same "frontend" device name (by default, `xvdi`).
-    You can get it from the `qvm-block` listing:
+   You can get it from the `qvm-block` listing:
 
-        [user@dom0 ~]$ qvm-block
+    ```shell_session
-        sys-usb:sda DataTraveler_2.0 () 246 MiB (attached to 'testvm' as 'xvdi')
+    [user@dom0 ~]$ qvm-block
-        [user@dom0 ~]$ sudo xl block-attach testvm phy:/dev/sda backend=sys-usb xvdi
+    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 output of `qvm-block`.
     In order:
@@ -148,21 +160,22 @@ If this isn't an option, you can manually recover from the situation by followin
     * `backend=sys-usb` - name of source qube, can be omitted in the 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 `qvm-block -d` command.
+3. Now properly detach the device, either using Qubes VM Manager or the `qvm-block -d` command.
 
-
+## Attaching a File
-## Attaching a File ##
 
 To attach a file as block device to another qube, first turn it into a loopback device inside the sourceVM.
 
- 1. In the linux sourceVM run
+1. In the linux sourceVM run
 
-        sudo losetup -f --show /path/to/file
+    ```
+    sudo losetup -f --show /path/to/file
+    ```
 
     [This command][losetup] will create the device node `/dev/loop0` or, if that is already in use, increase the trailing integer until that name is still available.
     Afterwards it prints the device-node-name it found.
 
- 2. If you want to use the GUI, you're done.
+2. If you want to use the GUI, you're done.
     Click the Device Manager ![device manager icon] and select the `loop0`-device to attach it to another qube.
 
     If you rather use the command line, continue:
@@ -170,26 +183,30 @@ To attach a file as block device to another qube, first turn it into a loopback
     In dom0, run `qvm-block` to display known block devices.
     The newly created loop device should show up:
 
-        ~]$ qvm-block
+    ```shell_session
-        BACKEND:DEVID  DESCRIPTION  USED BY
+    ~]$ qvm-block
-        sourceVM:loop0 /path/to/file
+    BACKEND:DEVID  DESCRIPTION  USED BY
+    sourceVM:loop0 /path/to/file
+    ```
 
- 3. Attach the `loop0`-device using qvm-block as usual:
+3. Attach the `loop0`-device using qvm-block as usual:
 
-        qvm-block a targetVM sourceVM:loop0
+    ```
+    qvm-block a targetVM sourceVM:loop0
+    ```
 
- 4. After detaching, destroy the loop-device inside the sourceVM as follows:
+4. After detaching, destroy the loop-device inside the sourceVM as follows:
 
-        sudo losetup -d /dev/loop0
+    ```
+    sudo losetup -d /dev/loop0
+    ```
 
-
+## Additional Attach Options
-## Additional Attach Options ##
 
 Attaching a block device through the command line offers additional customisation options, specifiable via the `--option`/`-o` option.
 (Yes, confusing wording, there's an [issue for that](https://github.com/QubesOS/qubes-issues/issues/4530).)
 
-
+### frontend-dev
-### frontend-dev ###
 
 This option allows you to specify the name of the device node made available in the targetVM.
 This defaults to `xvdi` or, if already occupied, the first available device node name in alphabetical order.
@@ -197,12 +214,13 @@ This defaults to `xvdi` or, if already occupied, the first available device node
 
 usage example:
 
-    qvm-block a work sys-usb:sda1 -o frontend-dev=xvdz
+```
+qvm-block a work sys-usb:sda1 -o frontend-dev=xvdz
+```
 
 This command will attach the partition `sda1` to `work` as `/dev/xvdz`.
 
-
+### read-only
-### read-only ###
 
 Attach device in read-only mode.
 Protects the block device in case you don't trust the targetVM.
@@ -211,28 +229,31 @@ If the device is a read-only device, this option is forced true.
 
 usage example:
 
-    qvm-block a work sys-usb:sda1 -o read-only=true
+```
+qvm-block a work sys-usb:sda1 -o read-only=true
+```
 
 There exists a shortcut to set read-only `true`, `--ro`:
 
-    qvm-block a work sys-usb:sda1 --ro
+```
+qvm-block a work sys-usb:sda1 --ro
+```
 
 The two commands are equivalent.
 
-
+### devtype
-### devtype ###
 
 Usually, a block device is attached as disk.
 In case you need to attach a block device as cdrom, this option allows that.
 
 usage example:
 
-    qvm-block a work sys-usb:sda1 -o devtype=cdrom
+```
+qvm-block a work sys-usb:sda1 -o devtype=cdrom
+```
 
 This option accepts `cdrom` and `disk`, default is `disk`.
 
-
-
 [device handling in qubes]: /doc/device-handling/
 [mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class
 [device manager icon]:/attachment/wiki/Devices/media-removable.png
@@ -242,4 +263,3 @@ This option accepts `cdrom` and `disk`, default is `disk`.
 [losetup]: https://linux.die.net/man/8/losetup
 [USB]:/doc/usb-devices/
 [1082]: https://github.com/QubesOS/qubes-issues/issues/1082
-

user/common-tasks/copy-from-dom0.md

@@ -20,7 +20,9 @@ Since dom0 is special, the processes are different from [copying and pasting tex
 
 To copy a file from dom0 to a VM, simply use `qvm-copy-to-vm`:
 
-    qvm-copy-to-vm <target_vm> <file>
+```
+qvm-copy-to-vm <target_vm> <file>
+```
 
 The file will arrive in the target VM in the `/home/user/QubesIncoming/dom0/` directory.
 
@@ -71,9 +73,12 @@ If you are determined to copy some files to dom0 anyway, you can use the followi
 (If you want to copy text, first save it into a text file.)
 Run this command in a dom0 terminal:
 
-    qvm-run --pass-io <src-vm> 'cat /path/to/file_in_src_domain' > /path/to/file_name_in_dom0
+```
+qvm-run --pass-io <src-vm> 'cat /path/to/file_in_src_domain' > /path/to/file_name_in_dom0
+```
 
 Note that you can use the same method to copy files from dom0 to domUs (if, for some reason, 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'
+```
-
+cat /path/to/file_in_dom0 | qvm-run --pass-io <dest-vm> 'cat > /path/to/file_name_in_appvm'
+```

user/common-tasks/device-handling.md

@@ -9,7 +9,7 @@ redirect_from:
 - /wiki/ExternalDeviceMountPoint/
 ---
 
-# Device Handling #
+# Device Handling
 
 This is an overview of device handling in Qubes OS.
 For specific devices ([block], [USB] and [PCI] devices), please visit their respective pages.
@@ -107,13 +107,11 @@ DEVICE_CLASS however is required.
 **SYNOPSIS**:
 `qvm-device DEVICE_CLASS {action} [action-specific arguments] [options]`
 
-
+## Actions
-## Actions ##
 
 Actions are applicable to every DEVICE_CLASS and expose some additional options.
 
-
+### Listing Devices
-### Listing Devices ###
 
 The `list` action lists known devices in the system.
 `list` accepts VM-names to narrow down listed devices.
@@ -121,16 +119,15 @@ Devices available in, as well as attached to the named VMs will be listed.
 
 `list` accepts two options:
 
- - `--all` - equivalent to specifying every VM name after `list`.
+- `--all` - equivalent to specifying every VM name after `list`.
 No VM-name implies `--all`.
- - `--exclude` - exclude VMs from `--all`.
+- `--exclude` - exclude VMs from `--all`.
 Requires `--all`.
 
 **SYNOPSIS**
 `qvm-device DEVICE_CLASS {list|ls|l} [--all [--exclude VM [VM [...]]] | VM [VM [...]]]`
 
-
+### Attaching Devices
-### Attaching Devices ###
 
 The `attach` action assigns an exposed device to a VM.
 This makes the device available in the VM it's attached to.
@@ -139,15 +136,14 @@ Required argument are targetVM and sourceVM:deviceID.
 
 `attach` accepts two options:
 
- - `--persistent` - attach device on targetVM-boot.
+- `--persistent` - attach device on targetVM-boot.
 If the device is unavailable (physically missing or sourceVM not started), booting the targetVM fails.
- - `--option`, `-o` - set additional options specific to DEVICE_CLASS.
+- `--option`, `-o` - set additional options specific to DEVICE_CLASS.
 
 **SYNOPSIS**
 `qvm-device DEVICE_CLASS {attach|at|a} targetVM sourceVM:deviceID [options]`
 
-
+### Detaching Devices
-### Detaching Devices ###
 
 The `detach` action removes an assigned device from a targetVM.
 It won't be available afterwards anymore.
@@ -160,7 +156,6 @@ If no specific `sourceVM:deviceID` combination is given, *all devices of that DE
 **SYNOPSIS**
 `qvm-device DEVICE_CLASS {detach|dt|d} targetVM [sourceVM:deviceID]`
 
-
 [block]:/doc/block-devices/
 [USB]:/doc/usb-devices/
 [PCI]:/doc/pci-devices/
@@ -168,4 +163,3 @@ If no specific `sourceVM:deviceID` combination is given, *all devices of that DE
 [device manager icon]: /attachment/wiki/Devices/media-removable.png
 [eject icon]: /attachment/wiki/Devices/media-eject.png
 [i4692]: https://github.com/QubesOS/qubes-issues/issues/4692
-

user/common-tasks/disposablevm.md

@@ -9,7 +9,7 @@ redirect_from:
 - /wiki/DisposableVMs/
 ---
 
-# DisposableVMs #
+# DisposableVMs
 
 A DisposableVM (previously known as a "DispVM") is a lightweight VM that can be created quickly and will disappear when closed.
 DisposableVMs are usually created in order to host a single application, like a viewer, editor, or web browser.
@@ -24,23 +24,21 @@ While running, DisposableVMs will appear in Qubes VM Manager with the name `disp
 
 This diagram provides a general example of how DisposableVMs can be used to safely open untrusted links and attachments in DisposableVMs. See [this article](https://blog.invisiblethings.org/2010/06/01/disposable-vms.html) for more on why one would want to use a DisposableVM.
 
-
+## Security
-## Security ##
 
 If a [DisposableVM Template] becomes compromised, then any DisposableVM based on that DisposableVM Template could be compromised.
 In particular, the *default* DisposableVM Template is important because it is used by the "Open in DisposableVM" feature.
 This means that it will have access to everything that you open with this feature.
 For this reason, it is strongly recommended that you base the default DisposableVM Template on a trusted TemplateVM.
 
-### DisposableVMs and Local Forensics ###
+### DisposableVMs and Local Forensics
 
 At this time, DisposableVMs should not be relied upon to circumvent local forensics, as they do not run entirely in RAM.
 For details, see [this thread](https://groups.google.com/d/topic/qubes-devel/QwL5PjqPs-4/discussion).
 
 When it is essential to avoid leaving any trace, consider using [Tails](https://tails.boum.org/).
 
-
+## DisposableVMs and Networking
-## DisposableVMs and Networking ##
 
 Similarly to how AppVMs are based on their underlying [TemplateVM](/doc/glossary/#templatevm), DisposableVMs are based on their underlying [DisposableVM Template](/doc/glossary/#disposablevm-template).
 R4.0 introduces the concept of multiple DisposableVM Templates, whereas R3.2 was limited to only one.
@@ -50,7 +48,9 @@ If you have included the Whonix option in your install, there will also be a `wh
 
 You can set any AppVM to have the ability to act as a DisposableVM Template with:
 
-    qvm-prefs <vmname> template_for_dispvms True
+```
+qvm-prefs <vmname> template_for_dispvms True
+```
 
 The default system wide DisposableVM Template can be changed with `qubes-prefs default_dispvm`.
 By combining the two, choosing `Open in DisposableVM` from inside an AppVM will open the document in a DisposableVM based on the default DisposableVM Template you specified.
@@ -59,7 +59,9 @@ You can change this behaviour for individual VMs: in the Application Menu, open
 Here you can edit the "Default DisposableVM" setting to specify which DisposableVM Template will be used to launch DisposableVMs from that VM.
 This can also be changed from the command line with:
 
-    qvm-prefs <VM> default_dispvm <DISPOSABLEVM_TEMPLATE>
+```
+qvm-prefs <VM> default_dispvm <DISPOSABLEVM_TEMPLATE>
+```
 
 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 DisposableVM Template to use itself, so DisposableVMs launched from within the AppVM/DisposableVM Template would inherit the same settings.
@@ -80,14 +82,17 @@ Different DisposableVM Templates with individual NetVM settings can be added to
 **Important Notes:**
 Some DisposableVM Templates will automatically create a menu item to launch a DVM, if you do not see an entry and want to add one please use the command:
 
-    qvm-features <DISPOSABLEVM> appmenus-dispvm 1
+```
+qvm-features <DISPOSABLEVM> appmenus-dispvm 1
+```
 
 To launch a DisposableVM Template from the command line, in dom0 please type the following:
 
-    qvm-run --dispvm=<DISPOSABLEVM_TEMPLATE> --service qubes.StartApp+NameOfApp
+```
+qvm-run --dispvm=<DISPOSABLEVM_TEMPLATE> --service qubes.StartApp+NameOfApp
+```
 
-
+## Opening a file in a DisposableVM via GUI
-## Opening a file in a DisposableVM via GUI ##
 
 In an AppVM's file manager, right click on the file you wish to open in a DisposableVM, then choose "View in DisposableVM" or "Edit in DisposableVM".
 Wait a few seconds and the default application for this file type should appear displaying the file content.
@@ -98,7 +103,7 @@ If you have edited the file and saved the changes, the changed file will be save
 ![r4.0-open-in-dispvm-1.png](/attachment/wiki/DisposableVms/r4.0-open-in-dispvm-1.png) ![r4.0-open-in-dispvm-2.png](/attachment/wiki/DisposableVms/r4.0-open-in-dispvm-2.png)
 
 
-## Opening a fresh web browser instance in a new DisposableVM ##
+## Opening a fresh web browser instance in a new DisposableVM
 
 Sometimes it is desirable to open an instance of Firefox within a new fresh DisposableVM.
 This can be done easily using the Start Menu: just go to **Application Menu -\> DisposableVM -\> DisposableVM:Firefox web browser**.
@@ -108,7 +113,7 @@ Once you close the viewing application the whole DisposableVM will be destroyed.
 ![r4.0-open-in-dispvm-3.png](/attachment/wiki/DisposableVms/r4.0-open-in-dispvm-3.png)
 
 
-## Opening a file in a DisposableVM via command line (from AppVM) ##
+## Opening a file in a DisposableVM via command line (from AppVM)
 
 Use the `qvm-open-in-dvm` command from a terminal in your AppVM:
 
@@ -118,8 +123,7 @@ Use the `qvm-open-in-dvm` command from a terminal in your AppVM:
 
 Note that the `qvm-open-in-dvm` process will not exit until you close the application in the DisposableVM.
 
-
+## Starting an arbitrary program in a DisposableVM from an AppVM
-## Starting an arbitrary program in a DisposableVM from an AppVM ##
 
 Sometimes it can be useful to start an arbitrary program in a DisposableVM.
 The DisposableVM will stay running so long as the process which started the DisposableVM has not exited.
@@ -132,8 +136,7 @@ Starting an arbitrary program can be done from an AppVM by running
 
 The created DisposableVM 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 DisposableVM via command line from dom0
-## Starting an arbitrary application in a DisposableVM via command line from dom0 ##
 
 The Application Launcher has shortcuts for opening a terminal and a web browser in dedicated DisposableVMs, since these are very common tasks.
 The DisposableVM will stay running so long as the process which started the DisposableVM has not exited.
@@ -147,8 +150,7 @@ $ qvm-run --dispvm=<DISPOSABLEVM_TEMPLATE> --service qubes.StartApp+xterm
 The label color will be inherited from `<DISPOSABLEVM_TEMPLATE>`.
 (The DisposableVM Application Launcher shortcut used for starting programs runs a very similar command to the one above.)
 
-
+### Opening a link in a DisposableVM based on a non-default DisposableVM Template from a qube
-### Opening a link in a DisposableVM based on a non-default DisposableVM Template from a qube ###
 
 Suppose that the default DisposableVM Template for your `email` qube has no networking (e.g., so that untrusted attachments can't phone home).
 However, sometimes you want to open email links in DisposableVMs.
@@ -164,9 +166,11 @@ This will create a new DisposableVM based on `<ONLINE_DISPOSABLEVM_TEMPLATE>`, o
 #### Example of RPC policies to allow this behavior
 
 In dom0, add the following line at the beginning of the file `/etc/qubes-rpc/policy/qubes.OpenURL`
+
 ~~~
 @anyvm @dispvm:<ONLINE_DISPOSABLEVM_TEMPLATE> allow
 ~~~
+
 This line means:
 - FROM: Any VM
 - TO: A DisposableVM based on `<ONLINE_DISPOSABLEVM_TEMPLATE>`
@@ -176,13 +180,11 @@ In other words, any VM will be allowed to create a new DisposableVM based on `<O
 
 More information about RPC policies for DisposableVMs can be found [here][qrexec].
 
-
+## Customizing DisposableVMs
-## Customizing DisposableVMs ##
 
 You can change the template used to generate the DisposableVMs, and change settings used in the DisposableVM savefile.
 These changes will be reflected in every new DisposableVM based on that template.
 Full instructions can be found [here](/doc/disposablevm-customization/).
 
-
 [DisposableVM Template]: /doc/glossary/#disposablevm-template
 [qrexec]: /doc/qrexec/#qubes-rpc-administration

user/common-tasks/full-screen-mode.md

@@ -70,4 +70,3 @@ global: {
 ~~~
 
 Be sure to restart the VM(s) after modifying this file, for the changes to take effect.
-

user/common-tasks/getting-started.md

@@ -27,10 +27,10 @@ So, creating a large number of qubes is cheap: each one needs only as much disk
 
 If you've installed Qubes OS using the default options, a few qubes have already been created for you:
 
- - work
+- work
- - personal
+- personal
- - untrusted
+- untrusted
- - vault
+- vault
 
 Each qube, apart from having a distinct name, is also assigned a **label**, which is one of several predefined colors.
 The trusted window manager uses these colors in order to draw colored borders around the windows of applications running in each qube.
@@ -57,31 +57,29 @@ Dom0 shouldn't be used for anything else.
 In particular, [you should never run user applications in dom0][dom0-precautions].
 (That's what your qubes are for!)
 
-
 GUI and command-line tools
 --------------------------
 
 All aspects of Qubes OS can be controlled using command-line tools run in a dom0 terminal.
 Opening a terminal in dom0 can be done in several ways:
 
- - Go to the Application Launcher and click **Terminal Emulator**.
+- Go to the Application Launcher and click **Terminal Emulator**.
- - Press `Alt+F3`, type `xfce terminal` and press Enter twice.
+- Press `Alt+F3`, type `xfce terminal` and press Enter twice.
- - Right-click on the desktop and select **Open Terminal Here**.
+- Right-click on the desktop and select **Open Terminal Here**.
 
 Various command-line tools are described as part of this guide, and the whole reference can be found [here][tools].
 
 Alternatively, you can use a suite of GUI tools, most of which are available through desktop widgets:
 
- - The **Domains Widget** allows you to manage running qubes, turn them on and off, and monitor memory usage.
+- The **Domains Widget** allows you to manage running qubes, turn them on and off, and monitor memory usage.
- - The **Devices Widget** allows you to attach and detach devices -- such as USB drives and cameras -- to qubes.
+- The **Devices Widget** allows you to attach and detach devices -- such as USB drives and cameras -- to qubes.
- - The **Disk Space Widget** will notify you if you're ever running out of disk space.
+- The **Disk Space Widget** will notify you if you're ever running out of disk space.
- - The **Updates Widget** will inform you when template updates are available.
+- The **Updates Widget** will inform you when template updates are available.
 
 ![q40_widgets.png](/attachment/wiki/GettingStarted/r4.0-q40_widgets.png)
 
 For an overview of the entire system, you can use the **Qube Manager** (go to the Application Launcher → System Tools → Qube Manager), which displays the states of all the qubes in your system.
 
-
 Starting apps
 -------------
 
@@ -100,15 +98,18 @@ If you'd like to add more, enter the qube's **Qube Settings** and add them on th
 
 To start apps from the terminal in dom0, type:
 
-    $ qvm-run <qube_name> <app_command> [arguments]
+```shell_session
+$ qvm-run <qube_name> <app_command> [arguments]
+```
 
 e.g.:
 
-    $ qvm-run untrusted firefox
+```shell_session
+$ qvm-run untrusted firefox
+```
 
 This command will start the qube if it is not already running.
 
-
 Adding, removing, and listing qubes
 -----------------------------------
 
@@ -117,10 +118,9 @@ If you need to add or remove qubes, simply use the Qube Manager's **Add** and **
 
 You can also add, remove, and list qubes from the command line using the following tools:
 
- - `qvm-create`
+- `qvm-create`
- - `qvm-remove`
+- `qvm-remove`
- - `qvm-ls`
+- `qvm-ls`
-
 
 How many qubes do I need?
 -------------------------
@@ -136,7 +136,6 @@ You'll also be able to easily [copy][copy-files] any files you need to the newly
 Still not sure?
 You might find it helpful to read [this article][partitioning], which describes how one of the Qubes OS architects partitions her digital life into security domains.
 
-
 Important tasks
 ---------------
 
@@ -149,12 +148,12 @@ The [Qubes backup system] allows you to do this securely and easily.
 Here are some other tasks you're likely to want to perform.
 (A full list is available in the [Common Tasks] section of the documentation.)
 
- * [Copying and Pasting Text Between Domains][copy-paste]
+- [Copying and Pasting Text Between Domains][copy-paste]
- * [Copying and Moving Files Between Domains][copy-files]
+- [Copying and Moving Files Between Domains][copy-files]
- * [Copying from (and to) dom0]
+- [Copying from (and to) dom0]
- * [Fullscreen Mode]
+- [Fullscreen Mode]
- * [DisposableVMs]
+- [DisposableVMs]
- * [Device Handling] (block, USB, and PCI devices)
+- [Device Handling] (block, USB, and PCI devices)
 
 If you encounter any problems, please visit the [Help, Support, and Mailing Lists] page.
 

user/common-tasks/optical-discs.md

@@ -22,4 +22,3 @@ To access an optical disc via USB follow the [typical procedure for attaching a
 Typically this would be `sr0`.
 For example, if `sys-usb` has device `3-2` attached to the `work` qube's `sr0`, you would mount it with `mount /dev/sr0 /mnt/removable`.
 You could also write to a disc with `wodim -v dev=/dev/sr0 -eject /home/user/Qubes.iso`.
-

user/common-tasks/pci-devices.md

@@ -9,7 +9,7 @@ redirect_from:
 - /wiki/AssigningDevices/
 ---
 
-# PCI Devices #
+# PCI Devices
 
 *This page is part of [device handling in qubes].*
 
@@ -19,8 +19,7 @@ You may end up with an unusable system by attaching the wrong PCI device to a VM
 PCI passthrough should be safe by default, but non-default options may be required.
 Please make sure you carefully read and understand the **[security considerations]** before deviating from default behavior.
 
-
+## Introduction
-## Introduction ##
 
 Unlike other devices ([USB], [block], mic), PCI devices need to be attached on VM-bootup.
 Similar to how you can't attach a new sound-card after your computer booted (and expect it to work properly), attaching PCI devices to already booted VMs isn't supported.
@@ -37,53 +36,56 @@ While PCI device can only be used by one powered on VM at a time, it *is* possib
 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 now attached), 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.
 
-
+## Attaching Devices Using the GUI
-## Attaching Devices Using the GUI ##
 
 The qube settings for a VM offers the "Devices"-tab.
 There you can attach PCI-devices to a qube.
 
- 1. To reach the settings of any qube either
+1. To reach the settings of any qube either
 
-     - Press Alt+F3 to open the application finder, type in the VM name, select the "![appmenu]\[VM-name\]: Qube Settings" menu entry and press enter or click "Launch"!
+   - Press Alt+F3 to open the application finder, type in the VM name, select the "![appmenu]\[VM-name\]: Qube Settings" menu entry and press enter or click "Launch"!
-     - Select the VM in Qube Manager and click the settings-button or right-click the VM and select `Qube settings`.
+   - Select the VM in Qube Manager and click the settings-button or right-click the VM and select `Qube settings`.
-     - Click the Domain Manager, hover the VM you want to attach a device to and select "settings" in the additional menu. (only running VMs!)
+   - Click the Domain Manager, hover the VM you want to attach a device to and select "settings" in the additional menu. (only running VMs!)
 
- 2. Select the "Devices" tab on the top bar.
+2. Select the "Devices" tab on the top bar.
- 3. Select a device you want to attach to the qube and click the single arrow right! (`>`)
+3. Select a device you want to attach to the qube and click the single arrow right! (`>`)
- 4. You're done.
+4. You're done.
-    If everything worked out, once the qube boots (or reboots if it's running) it will start with the pci device attached.
+   If everything worked out, once the qube boots (or reboots if it's running) it will start with the pci device attached.
- 5. In case it doesn't work out, first try disabling memory-balancing in the settings ("Advanced" tab).
+5. In case it doesn't work out, first try disabling memory-balancing in the settings ("Advanced" tab).
-    If that doesn't help, read on to learn how to disable the strict reset requirement!
+   If that doesn't help, read on to learn how to disable the strict reset requirement!
 
-
+## `qvm-pci` Usage
-## `qvm-pci` Usage ##
 
 The `qvm-pci` tool allows PCI attachment and detachment.
 It's a shortcut for [`qvm-device pci`][qvm-device].
 
 To figure out what device to attach, first list the available PCI devices by running (as user) in dom0:
 
-    qvm-pci
+```
+qvm-pci
+```
 
 This will show you the `backend:BDF` (Bus_Device.Function) 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 attach, then attach it like this:
 
-    qvm-pci attach targetVM sourceVM:[BDF] --persistent
+```
+qvm-pci attach targetVM sourceVM:[BDF] --persistent
+```
 
 Since PCI devices have to be attached on bootup, attaching has to happen with the `--persistant` option.
 
 For example, if `00_1a.0` is the BDF of the device you want to attach to the "work" domain, you would do this:
 
-    qvm-pci attach work dom0:00_1a.0 --persistent
+```
+qvm-pci attach work dom0:00_1a.0 --persistent
+```
 
-
+## Possible Issues
-## Possible Issues ##
 
 Visit the [PCI Troubleshooting guide](/doc/pci-troubleshooting/) to see issues that may arise due to PCI devices and how to troubleshoot them.
 
-## Additional Attach Options ##
+## Additional Attach Options
 
 Attaching a PCI device through the commandline offers additional options, specifiable via the `--option`/`-o` option.
 (Yes, confusing wording, there's an [issue for that](https://github.com/QubesOS/qubes-issues/issues/4530).)
@@ -91,28 +93,29 @@ Attaching a PCI device through the commandline offers additional options, specif
 `qvm-pci` exposes two additional options.
 Both are intended to fix device or driver specific issues, but both come with [heavy security implications][security considerations]! **Make sure you understand them before continuing!**
 
-
+### no-strict-reset
-### no-strict-reset ###
 
 Do not require PCI device to be reset before attaching it to another VM.
 This may leak usage data even without malicious intent!
 
 usage example:
 
-    qvm-pci a work dom0:00_1a.0 --persistent -o no-strict-reset=true
+```
+qvm-pci a work dom0:00_1a.0 --persistent -o no-strict-reset=true
+```
 
-
+### permissive
-### permissive ###
 
 Allow write access to full PCI config space instead of whitelisted registers.
 This increases attack surface and possibility of [side channel attacks].
 
 usage example:
 
-    qvm-pci a work dom0:00_1a.0 --persistent -o permissive=true
+```
+qvm-pci a work dom0:00_1a.0 --persistent -o permissive=true
+```
 
-
+## Bringing PCI Devices Back to dom0
-## Bringing PCI Devices Back to dom0 ##
 
 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.
 
@@ -122,20 +125,21 @@ A device which was previously attached to a VM less trusted than dom0 (which, in
 
 In order to re-enable the device in dom0, either:
 
- *  Reboot the physical machine. (Best practice)
+- Reboot the physical machine. (Best practice)
 
 or
 
- *  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. 
+- 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.
-    Replace `<BDF>` with your full device, for example `0000:00:1c.2`:
+  Replace `<BDF>` with your full device, for example `0000:00:1c.2`:
 
-        echo <BDF> > /sys/bus/pci/drivers/pciback/unbind
+    ```
-        MODALIAS=`cat /sys/bus/pci/devices/<BDF>/modalias`
+    echo <BDF> > /sys/bus/pci/drivers/pciback/unbind
-        MOD=`modprobe -R $MODALIAS | head -n 1`
+    MODALIAS=`cat /sys/bus/pci/devices/<BDF>/modalias`
-        echo <BDF> > /sys/bus/pci/drivers/$MOD/bind
+    MOD=`modprobe -R $MODALIAS | head -n 1`
-
+    echo <BDF> > /sys/bus/pci/drivers/$MOD/bind
-    It is **strongly discouraged to reattach PCI devices to dom0**, especially if they don't support resetting!
+    ```
 
+It is **strongly discouraged to reattach PCI devices to dom0**, especially if they don't support resetting!
 
 [device handling in qubes]: /doc/device-handling/
 [security considerations]: /doc/device-handling-security/#pci-security
@@ -145,4 +149,3 @@ or
 [domain manager icon]: /attachment/wiki/Devices/qubes-logo-icon.png
 [qvm-device]: /doc/device-handling/#general-qubes-device-widget-behavior-and-handling
 [side channel attacks]: https://en.wikipedia.org/wiki/Side-channel_attack
-

user/common-tasks/software-update-dom0.md

@@ -42,13 +42,17 @@ In order to update dom0 from the command line, start a console in dom0 and then
 
 To check and install updates for dom0 software:
 
-    $ sudo qubes-dom0-update
+```
+$ sudo qubes-dom0-update
+```
 
 ## How to install a specific package
 
 To install additional packages in dom0 (usually not recommended):
 
-    $ sudo qubes-dom0-update anti-evil-maid
+```
+$ sudo qubes-dom0-update anti-evil-maid
+```
 
 You may also pass the `--enablerepo=` option in order to enable optional repositories (see yum configuration in dom0).
 However, this is only for advanced users who really understand what they are doing.
@@ -58,7 +62,7 @@ You can also pass commands to `dnf` using `--action=...`.
 
 **WARNING:** Downgrading a package can expose your system to security vulnerabilities.
 
-1.  Download an older version of the package:
+1. Download an older version of the package:
 
     ~~~
     sudo qubes-dom0-update package-version
@@ -66,7 +70,7 @@ You can also pass commands to `dnf` using `--action=...`.
 
     Dnf will say that there is no update, but the package will nonetheless be downloaded to dom0.
 
-2.  Downgrade the package:
+2. Downgrade the package:
 
     ~~~
     sudo dnf downgrade package-version
@@ -76,7 +80,7 @@ You can also pass commands to `dnf` using `--action=...`.
 
 You can re-install in a similar fashion to downgrading.
 
-1.  Download the package:
+1. Download the package:
 
     ~~~
     sudo qubes-dom0-update package
@@ -84,7 +88,7 @@ You can re-install in a similar fashion to downgrading.
 
     Dnf will say that there is no update, but the package will nonetheless be downloaded to dom0.
 
-2.  Re-install the package:
+2. Re-install the package:
 
     ~~~
     sudo dnf reinstall package
@@ -97,17 +101,19 @@ You can re-install in a similar fashion to downgrading.
 
 If you've installed a package such as anti-evil-maid, you can remove it with the following command:
 
-    sudo dnf remove anti-evil-maid
+```
+sudo dnf remove anti-evil-maid
+```
 
 ## Testing repositories
 
 There are three Qubes dom0 [testing] repositories:
 
-* `qubes-dom0-current-testing` -- testing packages that will eventually land in the stable
+- `qubes-dom0-current-testing` -- testing packages that will eventually land in the stable
   (`current`) repository
-* `qubes-dom0-security-testing` -- a subset of `qubes-dom0-current-testing` that contains packages
+- `qubes-dom0-security-testing` -- a subset of `qubes-dom0-current-testing` that contains packages
   that qualify as security fixes
-* `qubes-dom0-unstable` -- packages that are not intended to land in the stable (`qubes-dom0-current`)
+- `qubes-dom0-unstable` -- packages that are not intended to land in the stable (`qubes-dom0-current`)
   repository; mostly experimental debugging packages
 
 To temporarily enable any of these repos, use the `--enablerepo=<repo-name>` option.
@@ -135,12 +141,14 @@ This section describes upgrading the kernel in dom0 and domUs.
 The packages `kernel` and `kernel-latest` are for dom0.
 
 In the `current` repository:
- - `kernel`: an older LTS kernel that has passed Qubes [testing] (the default dom0 kernel)
+
- - `kernel-latest`: the latest release from kernel.org that has passed Qubes [testing] (useful for [troubleshooting newer hardware])
+- `kernel`: an older LTS kernel that has passed Qubes [testing] (the default dom0 kernel)
+- `kernel-latest`: the latest release from kernel.org that has passed Qubes [testing] (useful for [troubleshooting newer hardware])
 
 In the `current-testing` repository:
- - `kernel`: the latest LTS kernel from kernel.org at the time it was built.
+
- - `kernel-latest`: the latest release from kernel.org at the time it was built.
+- `kernel`: the latest LTS kernel from kernel.org at the time it was built.
+- `kernel-latest`: the latest release from kernel.org at the time it was built.
 
 ### domU
 
@@ -160,11 +168,13 @@ from the update command), you may need to manually rebuild the EFI or grub confi
 your system uses.
 
 *EFI*: Replace the example version numbers with the one you are upgrading to.
+
 ~~~
 sudo dracut -f /boot/efi/EFI/qubes/initramfs-4.14.35-1.pvops.qubes.x86_64.img 4.14.35-1.pvops.qubes.x86_64
 ~~~
 
 *Grub2*
+
 ~~~
 sudo grub2-mkconfig -o /boot/grub2/grub.cfg
 ~~~
@@ -183,16 +193,20 @@ The procedure varies depending on if you are booting with UEFI or grub.
 On the next kernel update, the default will revert to the newest.
 
 *EFI*
+
 ~~~
 sudo nano /boot/efi/EFI/qubes/xen.cfg
 ~~~
+
 In the `[global]` section at the top, change the `default=` line to match one of the three boot entries listed below.
 For example,
+
 ~~~
 default=4.19.67-1.pvops.qubes.x86_64
 ~~~
 
 *Grub2*
+
 ~~~
 sudo nano /etc/default/grub
 [update the following two lines, add if needed]
@@ -201,12 +215,13 @@ GRUB_SAVEDEFAULT=true
 [save and exit nano]
 sudo grub2-mkconfig -o /boot/grub2/grub.cfg
 ~~~
+
 Then, reboot.
 Once the grub menu appears, choose "Advanced Options for Qubes (with Xen hypervisor)".
 Next, the top menu item (for example, "Xen hypervisor, version 4.8.5-9.fc25").
 Select the kernel you want as default, and it will be remembered for next boot.
 
-## Updating over Tor ###
+## Updating over Tor
 
 Requires installed [Whonix](/doc/privacy/whonix/).
 
@@ -215,8 +230,9 @@ See the UpdateVM setting.
 Choose your desired Whonix-Gateway ProxyVM from the list.
 For example: sys-whonix.
 
-    Qubes VM Manager -> System -> Global Settings -> UpdateVM -> sys-whonix
+`
-
+Qubes VM Manager -> System -> Global Settings -> UpdateVM -> sys-whonix
+`
 
 [dom0]: /doc/glossary/#dom0
 [Updating Qubes OS]: /doc/updating-qubes-os/
@@ -225,4 +241,3 @@ For example: sys-whonix.
 [troubleshooting newer hardware]: /doc/newer-hardware-troubleshooting/
 [Managing VM kernel]: /doc/managing-vm-kernel/
 [installing contributed packages]: /doc/installing-contributed-packages/
-

user/common-tasks/software-update-domu.md

@@ -15,23 +15,21 @@ Updating [domUs], especially [TemplateVMs] and [StandaloneVMs][StandaloneVM] are
 It is very import to keep domUs up-to-date with the latest [security] updates.
 Updating these VMs also allows you to receive various non-security bug fixes and enhancements both from the Qubes OS Project and from your upstream distro maintainer.
 
-
 ## Installing software in TemplateVMs
 
 To permanently install new software in a TemplateVM:
 
- 1. Start the TemplateVM.
+1. Start the TemplateVM.
- 2. Start either a terminal (e.g. `gnome-terminal`) or a dedicated software management application, such as `gpk-application`.
+2. Start either a terminal (e.g. `gnome-terminal`) or a dedicated software management application, such as `gpk-application`.
- 3. Install software as normally instructed inside that operating system (e.g. `sudo dnf install <PACKAGE_NAME>` on Fedora, `sudo apt install <PACKAGE_NAME>` on Debian).
+3. Install software as normally instructed inside that operating system (e.g. `sudo dnf install <PACKAGE_NAME>` on Fedora, `sudo apt install <PACKAGE_NAME>` on Debian).
- 4. Shut down the TemplateVM.
+4. Shut down the TemplateVM.
- 5. Restart all [TemplateBasedVMs] based on the TemplateVM so the changes can take effect.
+5. Restart all [TemplateBasedVMs] based on the TemplateVM so the changes can take effect.
- 6. (Optional) In the relevant [TemplateBasedVMs]' **Qube Settings**, go to the **Applications** tab, select the new application(s) from the list, and press OK.
+6. (Optional) In the relevant [TemplateBasedVMs]' **Qube Settings**, go to the **Applications** tab, select the new application(s) from the list, and press OK.
     These new shortcuts will appear in the Applications Menu.
     (If you encounter problems, see [here][shortcuts] for troubleshooting.)
 
 ![[The Applications tab in Qube Settings](/attachment/wiki/ManagingAppVmShortcuts/r4.1-dom0-appmenu-select.png)](/attachment/wiki/ManagingAppVmShortcuts/r4.1-dom0-appmenu-select.png)
 
-
 ## Updating software in TemplateVMs
 
 The recommended way to update your TemplateVMs is to use the **Qubes Update** tool.
@@ -43,7 +41,6 @@ You can also update TemplateVMs individually.
 In the Qube Manager, select the desired TemplateVM, then click **Update qube**.
 Advanced users can execute the standard update command for that operating system from the command line, e.g. `dnf update` in Fedora and `apt-get update` in Debian.
 
-
 ## Testing repositories
 
 If you wish to install updates that are still in [testing], you must enable the appropriate testing repositories.
@@ -52,9 +49,9 @@ If you wish to install updates that are still in [testing], you must enable the
 
 There are three Qubes VM testing repositories (where `*` denotes the Release):
 
-* `qubes-vm-*-current-testing` -- testing packages that will eventually land in the stable (`current`) repository
+- `qubes-vm-*-current-testing` -- testing packages that will eventually land in the stable (`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 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
+- `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>` option.
 Example commands:
@@ -67,23 +64,20 @@ sudo dnf upgrade --enablerepo=qubes-vm-*-unstable
 
 To enable or disable any of these repos permanently, change the corresponding `enabled` value to `1` in `/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 (`current`) repository
+- `*-testing` -- testing packages that will eventually land in the stable (`current`) repository
-* `*-securitytesting` -- a subset of `*-testing` that contains packages that qualify as security fixes
+- `*-securitytesting` -- a subset of `*-testing` that contains packages that qualify as security fixes
-* `*-unstable` -- packages that are not intended to land in the stable repository; mostly experimental debugging packages
+- `*-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 `/etc/apt/sources.list.d/qubes-r*.list`.
 
-
 ## Contributed package repository
 
 Please see [installing contributed packages].
 
-
 ## StandaloneVMs
 
 When you create a [StandaloneVM] from a TemplateVM, the StandaloneVM is a complete clone of the TemplateVM, including the entire filesystem.
@@ -92,12 +86,10 @@ Therefore, it will not be updated when the TemplateVM is updated.
 Rather, it must be updated individually.
 The process for installing and updating software in StandaloneVMs is the same as described above for TemplateVMs.
 
-
 ## Advanced
 
 The following sections cover advanced topics pertaining to installing and updating software in domUs.
 
-
 ### RPMFusion for Fedora TemplateVMs
 
 If you would like to enable the [RPM Fusion] repositories, open a Terminal of the TemplateVM and type the following commands, depending on which RPM Fusion repositories you wish to enable (see [RPM Fusion] for details):
@@ -114,7 +106,6 @@ This will permanently enable the RPM Fusion repos.
 If you install software from here, it's important to keep these repos enabled so that you can receiving future updates.
 If you only enable these repos temporarily to install a package the Qubes update mechanism may persistently notify you that updates are available, since it cannot download them.
 
-
 ### Reverting changes to a TemplateVM
 
 Perhaps you've just updated your TemplateVM, and the update broke your template.
@@ -132,7 +123,6 @@ If you want to undo changes to a TemplateVM, there are three basic methods:
    This is appropriate for both misconfigurations and security concerns, and it can preserve your customizations.
    However, it is a bit more complex.
 
-
 #### Root revert
 
 **Important:** This command will roll back any changes made *during the last time the TemplateVM was run, but **not** before.*
@@ -145,25 +135,24 @@ Just make sure to **back up** all of your data and changes first!
 
 2. In a dom0 terminal:
 
+```
         qvm-volume revert <template>:root
-
+```
 
 #### Reinstall the template
 
 Please see [How to Reinstall a TemplateVM].
 
-
 #### Full revert
 
 This is like the simple revert, except:
 
- - You must also revert the private volume with `qvm-volume revert <template>:private`.
+- You must also revert the private volume with `qvm-volume revert <template>:private`.
-   This requires you to have an old revision of the private volume, which does not exist with the current default config.
+  This requires you to have an old revision of the private volume, which does not exist with the current default config.
-   However, if you don't have anything important in the private volume (likely for a TemplateVM), then you can work around this by just resetting the private volume with `qvm-volume import --no-resize <template>:private /dev/null`.
+  However, if you don't have anything important in the private volume (likely for a TemplateVM), then you can work around this by just resetting the private volume with `qvm-volume import --no-resize <template>:private /dev/null`.
-
- - The saved revision of the volumes must be uncompromised.
-   With the default `revisions_to_keep=1` for the root volume, you must **not** have started the template since the compromising action.
 
+- The saved revision of the volumes must be uncompromised.
+  With the default `revisions_to_keep=1` for the root volume, you must **not** have started the template since the compromising action.
 
 ### Temporarily allowing networking for software installation
 
@@ -173,7 +162,6 @@ So it is necessary to modify firewall rules to allow less restrictive internet a
 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
 
 Updates proxy is a service which allows access only from package managers.
@@ -194,7 +182,6 @@ There are two services (`qvm-service`, [service framework]):
 Both the old and new names work.
 The defaults listed above are applied if the service is not explicitly listed in the services tab.
 
-
 #### Technical details
 
 The updates proxy uses RPC/qrexec.
@@ -202,9 +189,9 @@ The proxy is configured in qrexec policy in dom0: `/etc/qubes-rpc/policy/qubes.U
 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):
-```
+
+```shell_session
 # 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
@@ -275,6 +262,7 @@ Shutdown the TemplateVM:
 ```shell_session
 [user@snap-demo-AppVM ~]$ snap install <package>
 ```
+
 When the install is complete you can close the terminal window.
 
 3. Refresh the Applications list for the AppVM.
@@ -283,7 +271,6 @@ Then go to the Applications tab and click "Refresh Applications"
 
 The refresh will take a few minutes; after it's complete the Snap app will appear in the AppVM's list of available applications. At this point the snap will be persistent within the AppVM and will receive updates when the AppVM is running.
 
-
 ### Autostarting Installed Applications
 
 If you want a desktop app to start automatically every time a qube starts you can create a link to it in the `~/.config/autostart` directory of the **AppVM**. This might be useful for Qubes that you set to automatically start on boot or for Qubes that have a set of apps you typically use all day, such as a chat app.
@@ -303,7 +290,7 @@ yelp.desktop
 
 3. Create the autostart directory:
 
-```shell_session
+```
 [user@example-AppVM ~]$ mkdir -p ~/.config/autostart
 ```
 
@@ -315,8 +302,6 @@ yelp.desktop
 
 Note that the app will autostart only when the AppVM starts. If you would like the AppVM to autostart, select the "Start qube automatically on boot" checkbox in the AppVM's Qube Settings.
 
-
-
 [domUs]: /doc/glossary/#domu
 [TemplateVMs]: /doc/templates/
 [StandaloneVM]: /doc/standalone-and-hvm/
@@ -329,4 +314,3 @@ Note that the app will autostart only when the AppVM starts. If you would like t
 [How to Reinstall a TemplateVM]: /doc/reinstall-template/
 [installing contributed packages]: /doc/installing-contributed-packages/
 [shortcuts]: /doc/managing-appvm-shortcuts/
-

user/common-tasks/updating-qubes-os.md

@@ -14,9 +14,9 @@ It is very important to keep your Qubes OS system up-to-date to ensure you have
 
 Fully updating your Qubes OS system means updating:
 
- - [Dom0]
+- [Dom0]
- - [TemplateVMs]
+- [TemplateVMs]
- - [StandaloneVMs] (if you have any)
+- [StandaloneVMs] (if you have any)
 
 You can accomplish this using the **Qubes Update** tool.
 By default, the Qubes Update tool will appear as an icon in the Notification Area when updates are available, but you can also start the tool manually by selecting it in the Applications Menu under "System Tools."
@@ -33,7 +33,6 @@ You can always find out when an operating system reaches EOL from the upstream p
 When this happens, you should make sure to follow the guide to upgrade to a supported version of that operating system (see the [Fedora upgrade guides] and the [Debian upgrade guides]).
 The one exception is dom0, which [doesn't have to be upgraded][dom0-eol].
 
-
 [supported version of Qubes OS]: /doc/supported-versions/#qubes-os
 [Upgrade Guides]: /doc/upgrade/
 [security]: /security/

user/common-tasks/usb-devices.md

@@ -6,7 +6,7 @@ redirect_from:
 - /doc/usb/
 ---
 
-# USB Devices #
+# USB Devices
 
 *This page is part of [device handling in qubes].*
 
@@ -20,18 +20,16 @@ Whenever possible, attach a [block device] instead.
 
 Examples of valid cases for USB-passthrough:
 
- - [microcontroller programming]
+- [microcontroller programming]
- - [external audio devices]
+- [external audio devices]
- - [optical drives] for recording
+- [optical drives] for recording
 
 (If you are thinking to use a two-factor-authentication device, [there is an app for that][qubes u2f proxy].
 But it has some [issues][4661].)
 
+## Attaching And Detaching a USB Device
 
-## Attaching And Detaching a USB Device ##
+### With Qubes Device Manager
-
-
-### With Qubes Device Manager ###
 
 Click the device-manager-icon: ![device manager icon]
 A list of available devices appears.
@@ -49,51 +47,53 @@ Hover on the attached device to display a list of running VMs.
 The one to which your device is connected will have an eject button ![eject icon] next to it.
 Click that and your device will be detached.
 
-
+### With The Command Line Tool
-### With The Command Line Tool ###
 
 In dom0, you can use `qvm-usb` from the commandline to attach and detach devices.
 
 Listing available USB devices:
 
-    [user@dom0 ~]$ qvm-usb
+```shell_session
-    BACKEND:DEVID   DESCRIPTION                    USED BY
+[user@dom0 ~]$ qvm-usb
-    sys-usb:2-4     04ca:300d 04ca_300d
+BACKEND:DEVID   DESCRIPTION                    USED BY
-    sys-usb:2-5     058f:3822 058f_USB_2.0_Camera
+sys-usb:2-4     04ca:300d 04ca_300d
-    sys-usb:2-1     03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
+sys-usb:2-5     058f:3822 058f_USB_2.0_Camera
+sys-usb:2-1     03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
+```
 
 Attaching selected USB device:
 
-    [user@dom0 ~]$ qvm-usb attach work sys-usb:2-5
+```shell_session
-    [user@dom0 ~]$ qvm-usb
+[user@dom0 ~]$ qvm-usb attach work sys-usb:2-5
-    BACKEND:DEVID   DESCRIPTION                    USED BY
+[user@dom0 ~]$ qvm-usb
-    sys-usb:2-4     04ca:300d 04ca_300d
+BACKEND:DEVID   DESCRIPTION                    USED BY
-    sys-usb:2-5     058f:3822 058f_USB_2.0_Camera  work
+sys-usb:2-4     04ca:300d 04ca_300d
-    sys-usb:2-1     03f0:0641 PixArt_Optical_Mouse
+sys-usb:2-5     058f:3822 058f_USB_2.0_Camera  work
+sys-usb:2-1     03f0:0641 PixArt_Optical_Mouse
+```
 
 Now, you can use your USB device (camera in this case) in the `work` qube.
 If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section].
 
 When you finish, detach the device.
 
-    [user@dom0 ~]$ qvm-usb detach work sys-usb:2-5
+```shell_session
-    [user@dom0 ~]$ qvm-usb
+[user@dom0 ~]$ qvm-usb detach work sys-usb:2-5
-    BACKEND:DEVID   DESCRIPTION                    USED BY
+[user@dom0 ~]$ qvm-usb
-    sys-usb:2-4     04ca:300d 04ca_300d
+BACKEND:DEVID   DESCRIPTION                    USED BY
-    sys-usb:2-5     058f:3822 058f_USB_2.0_Camera
+sys-usb:2-4     04ca:300d 04ca_300d
-    sys-usb:2-1     03f0:0641 PixArt_Optical_Mouse
+sys-usb:2-5     058f:3822 058f_USB_2.0_Camera
+sys-usb:2-1     03f0:0641 PixArt_Optical_Mouse
+```
 
+## Maintenance And Customisation
 
-## Maintenance And Customisation ##
+### Creating And Using a USB qube
-
-
-### Creating And Using a USB qube ###
 
 If you've selected to install a usb-qube during system installation, everything is already set up for you in `sys-usb`.
 If you've later decided to create a usb-qube, please follow [this guide][USB-qube howto].
 
-
+### Installation Of `qubes-usb-proxy`
-### Installation Of `qubes-usb-proxy` ###
 
 To use this feature, the `qubes-usb-proxy` package needs to be installed in the templates used for the USB qube and qubes you want to connect USB devices to.
 This section exists for reference or in case something broke and you need to reinstall `qubes-usb-proxy`.
@@ -104,15 +104,13 @@ If you receive this error: `ERROR: qubes-usb-proxy not installed in the VM`, you
 - Fedora: `sudo dnf install qubes-usb-proxy`
 - Debian/Ubuntu: `sudo apt-get install qubes-usb-proxy`
 
-
+### Using USB Keyboards And Other Input Devices
-### Using USB Keyboards And Other Input Devices ###
 
 **Warning:** especially keyboards need to be accepted by default when using them to login! Please make sure you carefully read and understood the **[security considerations]** before continuing!
 
 Mouse and keyboard setup are part of [setting up a USB-qube][keyboard setup].
 
-
+### Finding The Right USB Controller
-### Finding The Right USB Controller ###
 
 Some USB devices are not compatible with the USB pass-through method Qubes employs.
 In situations like these, you can try to pass through the entire USB controller to a qube as PCI device.
@@ -122,12 +120,16 @@ If you have multiple USB controllers, you must first figure out which PCI device
 
 First, find out which USB bus the device is connected to (note that these steps need to be run from a terminal inside your USB qube):
 
-    lsusb
+```
+lsusb
+```
 
 For example, I want to attach a broadband modem to the NetVM.
 In the output of `lsusb` it may be listed as something like:
 
-    Bus 003 Device 003: ID 413c:818d Dell Computer Corp.
+```
+Bus 003 Device 003: ID 413c:818d Dell Computer Corp.
+```
 
 (In this case, the device isn't fully identified)
 
@@ -136,12 +138,15 @@ Check which other devices are connected to the same bus, since *all* of them wil
 
 To find the right controller, follow the usb bus:
 
-    readlink /sys/bus/usb/devices/usb3
+```
-
+readlink /sys/bus/usb/devices/usb3
+```
 
 This should output something like:
 
-    ../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
+```
+../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
+```
 
 Now you see the path and the text between `/pci0000:00/0000:` and `/usb3` i.e. `00:1a.0` is the BDF address. Strip the address and pass it to the [`qvm-pci` tool][qvm-pci] to attach the controller to the targetVM.
 
@@ -149,7 +154,6 @@ For example, On R 4.0 the command would look something like
 
 `qvm-pci attach --persistent personal dom0:00_1a.0`
 
-
 [device handling in qubes]: /doc/device-handling/
 [block device]: /doc/block-devices/
 [security considerations]: /doc/device-handling-security/#usb-security

user/common-tasks/volume-backup-revert.md

@@ -26,7 +26,9 @@ inherits the pool default revisions_to_keep.
 For the private volume associated with a VM named vmname, you may inspect the
 value of revisions_to_keep from the dom0 CLI as follows:
 
-    qvm-volume info vmname:private
+```
+qvm-volume info vmname:private
+```
 
 The output of the above command will also display the "Available revisions
 (for revert)" at the bottom. For a very large volume in a small pool,
@@ -36,10 +38,14 @@ smaller volume for which you would like to have the future option of reverting,
 revisions_to_keep should probably be set to at least 2. To set
 revisions_to_keep for this same VM / volume example:
 
-    qvm-volume config vmname:private revisions_to_keep 2
+```
+qvm-volume config vmname:private revisions_to_keep 2
+```
 
 With the VM stopped, you may revert to an older snapshot of the private volume
 from the the above list of "Available revisions (for revert)", where the last
 item on the list with the largest integer is the most recent snapshot:
 
-    qvm-volume revert vmname:private <revision>
+```
+qvm-volume revert vmname:private <revision>
+```

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

@@ -10,7 +10,6 @@ redirect_from:
 
 In the present context, "custom installation" refers to things like manual partitioning, setting up LVM and RAID, and manual LUKS encryption configuration.
 
-
 ## Installer Defaults
 
 For reference, these are the typical defaults for a single disk with legacy boot:
@@ -58,7 +57,6 @@ Order   Action              Type                    Device              Mount po
 14      Create Format       ext4                    qubes_dom0-root     /
 ~~~
 
-
 ## Typical Partition Schemes
 
 If you want your partition/LVM scheme to look like the Qubes default but with a few tweaks, follow this example.
@@ -75,7 +73,6 @@ sda                                         disk
       └──qubes_dom0-swap                    lvm     [SWAP]
 ~~~
 
-
 ## Encryption Defaults
 
 By default, `cryptsetup 1.7.5` will create a LUKS/dm-crypt volume as follows:
@@ -98,25 +95,28 @@ Default compiled-in device cipher parameters:
 
 This means that, by default, Qubes inherits these upstream defaults:
 
- - AES-128 [[1]][cryptsetup-faq][[2]][dm-crypt][[3]][tomb-238]
+- AES-128 [[1]][cryptsetup-faq][[2]][dm-crypt][[3]][tomb-238]
- - SHA-256
+- SHA-256
- - `/dev/urandom`
+- `/dev/urandom`
- - probably an `iter-time` of one second
+- probably an `iter-time` of one second
 
 If, instead, you'd like to use AES-256, SHA-512, `/dev/random`, and a longer `iter-time`, for example, you can configure encryption manually by following the instructions below.
 
-
 ## Example: Custom LUKS Configuration
 
 Boot into the Qubes installer, then press `ctrl`+`alt`+`F2` to get a virtual console.
 
 1. (Optional) Wipe the disk:
 
-        # dd if=/dev/zero of=/dev/sda bs=1M status=progress && sync
+    ```
+    # dd if=/dev/zero of=/dev/sda bs=1M status=progress && sync
+    ```
 
 2. Create partitions:
 
-        # fdisk /dev/sda
+    ```
+    # fdisk /dev/sda
+    ```
 
    Follow the steps to create two partitions:
    
@@ -125,26 +125,34 @@ Boot into the Qubes installer, then press `ctrl`+`alt`+`F2` to get a virtual con
 
 4. Create LUKS encrypted volume:
 
-        # cryptsetup -v --hash sha512 --cipher aes-xts-plain64 --key-size 512 --use-random --iter-time 10000 --verify-passphrase luksFormat /dev/sda2
+    ```
+    # cryptsetup -v --hash sha512 --cipher aes-xts-plain64 --key-size 512 --use-random --iter-time 10000 --verify-passphrase luksFormat /dev/sda2
+    ```
 
 5. Open encrypted volume:
 
-        # cryptsetup open /dev/sda2 luks
+    ```
+    # cryptsetup open /dev/sda2 luks
+    ```
 
 6. Create LVM volumes:
 
-        # pvcreate /dev/mapper/luks
+    ```
-        # vgcreate qubes_dom0 /dev/mapper/luks
+    # pvcreate /dev/mapper/luks
-        # lvcreate -n swap -L 10G qubes_dom0
+    # vgcreate qubes_dom0 /dev/mapper/luks
-        # lvcreate -T -l +100%FREE qubes_dom0/pool00
+    # lvcreate -n swap -L 10G qubes_dom0
-        # lvcreate -V1G -T qubes_dom0/pool00 -n root
+    # lvcreate -T -l +100%FREE qubes_dom0/pool00
-        # lvextend -L <size_of_pool00> /dev/qubes_dom0/root
+    # lvcreate -V1G -T qubes_dom0/pool00 -n root
+    # lvextend -L <size_of_pool00> /dev/qubes_dom0/root
+    ```
 
 8. Proceed with the installer. You can do that either by pressing `ctrl`+`alt`+`F6`, or by rebooting and restarting the installation.
    At the disk selection screen, select:
 
-        [x] I will configure partitioning.
+    ```
-        [ ] Encrypt my data.
+    [x] I will configure partitioning.
+    [ ] Encrypt my data.
+    ```
 
 9. Decrypt your partition. After decrypting you may assign mount points:
    Open the Unknown list and select `qubes_dom0-root`. Check the reformat box to the right and choose `ext4` as a filesystem. Enter `/` into the Mount Point field at the top.
@@ -152,8 +160,6 @@ Boot into the Qubes installer, then press `ctrl`+`alt`+`F2` to get a virtual con
    The default file systems are ext4 for `/boot` and `/`, and swap for `swap`.
    When you are finished, the Unknown list should go away, and all three mount points should be assigned. Proceed normally with the installation from there.
 
-
 [cryptsetup-faq]: https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions
 [dm-crypt]: https://wiki.archlinux.org/index.php/dm-crypt/Device_encryption
 [tomb-238]: https://github.com/dyne/Tomb/issues/238
-

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

@@ -19,12 +19,11 @@ If you are interested in offering a mirror for Qubes downloads, thank you!
 We greatly appreciate your offer, and we hope these brief instructions are
 helpful in streamlining the process.
 
- * We are happy to provide rsync or HTTP master.
+* We are happy to provide rsync or HTTP master.
- * Our preferred frequency is **once every 24 hours**, but anything up to once
+* Our preferred frequency is **once every 24 hours**, but anything up to once
-   every 6-8 hours is fine.
+  every 6-8 hours is fine.
- * For technical accommodations, please contact [Wojtek] or [Marek].
+* For technical accommodations, please contact [Wojtek] or [Marek].
- * For website updates and fixes, please contact [Andrew].
+* For website updates and fixes, please contact [Andrew].
-
 
 [mirror-list]: /downloads/#mirrors
 [Wojtek]: /team/#wojtek-porczyk

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

@@ -41,44 +41,42 @@ From a Qubes-specific security perspective, each has certain pros and cons.
 
 Pros:
 
- * Works via USB, including with a [USB qube].
+* Works via USB, including with a [USB qube].
- * Non-fixed capacity.
+* Non-fixed capacity.
-   (Easy to find one on which the ISO can fit.)
+  (Easy to find one on which the ISO can fit.)
 
 Cons:
 
- * Rewritable.
+* Rewritable.
-   (If the drive is mounted to a compromised machine, the ISO could be maliciously altered after it has been written to the drive.)
+  (If the drive is mounted to a compromised machine, the ISO could be maliciously altered after it has been written to the drive.)
- * Untrustworthy firmware.
+* Untrustworthy firmware.
-   (Firmware can be malicious even if the drive is new.
+  (Firmware can be malicious even if the drive is new.
-   Plugging a drive with rewritable firmware into a compromised machine can also [compromise the drive][BadUSB].
+  Plugging a drive with rewritable firmware into a compromised machine can also [compromise the drive][BadUSB].
-   Installing from a compromised drive could compromise even a brand new Qubes installation.)
+  Installing from a compromised drive could compromise even a brand new Qubes installation.)
-
 
 ### Optical discs
 
 Pros:
 
- * Read-only available.
+* Read-only available.
-   (If you use read-only media, you don't have to worry about the ISO being maliciously altered after it has been written to the disc.
+  (If you use read-only media, you don't have to worry about the ISO being maliciously altered after it has been written to the disc.
-   You then have the option of verifying the signature on multiple different machines.)
+  You then have the option of verifying the signature on multiple different machines.)
 
 Cons:
 
- * Fixed capacity.
+* Fixed capacity.
-   (If the size of the ISO is larger than your disc, it will be inconvenient.)
+  (If the size of the ISO is larger than your disc, it will be inconvenient.)
- * Passthrough recording (a.k.a., "burning") is not supported by Xen.
+* Passthrough recording (a.k.a., "burning") is not supported by Xen.
-   (This mainly applies if you're upgrading from a previous version of Qubes.)
+  (This mainly applies if you're upgrading from a previous version of Qubes.)
-   Currently, the only options for recording optical discs (e.g., CDs, DVDs, BRDs) in Qubes are:
+  Currently, the only options for recording optical discs (e.g., CDs, DVDs, BRDs) in Qubes are:
-   1. Use a USB optical drive.
+  1. Use a USB optical drive.
-   2. Attach a SATA optical drive to a secondary SATA controller, then assign this secondary SATA controller to an AppVM.
+  2. Attach a SATA optical drive to a secondary SATA controller, then assign this secondary SATA controller to an AppVM.
-   3. Use a SATA optical drive attached to dom0.
+  3. Use a SATA optical drive attached to dom0.
 
-   (Option 3 violates the Qubes security model since it entails transferring an untrusted ISO to dom0 in order to burn it to disc, which leaves only the other two options.)
+  (Option 3 violates the Qubes security model since it entails transferring an untrusted ISO to dom0 in order to burn it to disc, which leaves only the other two options.)
 
 Considering the pros and cons of each, perhaps a USB drive with non-rewritable (or at least cryptographically-signed) firmware and a physical write-protect switch might be the best option.
 
-
 [AEM]: /doc/anti-evil-maid/
 [verify]: /security/verifying-signatures/
 [classic problem]: https://www.ece.cmu.edu/~ganger/712.fall02/papers/p761-thompson.pdf

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

@@ -81,7 +81,9 @@ The size of each Qubes ISO is available on the [downloads] page by hovering over
 
 If you choose to use a USB drive, copy the ISO onto the USB device, e.g. using `dd`:
 
-    $ sudo dd if=Qubes-RX-x86_64.iso of=/dev/sdY status=progress bs=1048576 && sync
+```
+$ sudo dd if=Qubes-RX-x86_64.iso of=/dev/sdY status=progress bs=1048576 && sync
+```
 
 Change `Qubes-RX-x86_64.iso` to the filename of the version you're installing, and change `/dev/sdY` to the correct target device e.g., `/dev/sdc`).
 Make sure to write to the entire device (e.g., `/dev/sdc`) rather than just a single partition (e.g., `/dev/sdc1`).
@@ -124,9 +126,9 @@ From here, you can navigate the boot screen using the arrow keys on your keyboar
 Pressing the "Tab" key will reveal options. 
 You can choose one of three options:
 
- * Install Qubes OS
+* Install Qubes OS
- * Test this media and install Qubes OS
+* Test this media and install Qubes OS
- * Troubleshooting
+* Troubleshooting
  
 Select the option to test this media and install Qubes OS. 
 
@@ -207,8 +209,8 @@ Don't forget to select your time and date by clicking on the Time & Date entry.
 On the software selection tab, you can choose which software to install in Qubes OS. 
 Two options are available:
 
- * **Debian:** Select this option if you would like to use [Debian] qubes in addition to the default Fedora qubes.
+* **Debian:** Select this option if you would like to use [Debian] qubes in addition to the default Fedora qubes.
- * **Whonix:** Select this option if you would like to use [Whonix] qubes.
+* **Whonix:** Select this option if you would like to use [Whonix] qubes.
    Whonix allows you to use [Tor] securely within Qubes.
 
 Whonix lets you route some or all of your network traffic through Tor for greater privacy.
@@ -233,7 +235,6 @@ Select the storage device on which you would like to install Qubes OS.
   We strongly recommended making a full backup before proceeding.
 </div>
 
-
 Your installation destination can be an internal or external storage drive, such as an SSD, HDD, or USB drive.
 The installation destination must have a least 32 GiB of free space available.
 
@@ -314,24 +315,24 @@ These are designed to give you a more ready-to-use environment from the get-go.
 
 Let's briefly go over the options:
 
- * **Create default system qubes:**
+* **Create default system qubes:**
-   These are the core components of the system, required for things like internet access.
+  These are the core components of the system, required for things like internet access.
- * **Create default application qubes:**
+* **Create default application qubes:**
-   These are how you compartmentalize your digital life.
+  These are how you compartmentalize your digital life.
-   There's nothing special about the ones the installer creates.
+  There's nothing special about the ones the installer creates.
-   They're just suggestions that apply to most people.
+  They're just suggestions that apply to most people.
-   If you decide you don't want them, you can always delete them later, and you can always create your own.
+  If you decide you don't want them, you can always delete them later, and you can always create your own.
- * **Create Whonix Gateway and Workstation qubes:**
+* **Create Whonix Gateway and Workstation qubes:**
-   If you want to use Whonix, you should select this option.
+  If you want to use Whonix, you should select this option.
-   * **Enabling system and template updates over the Tor anonymity network using Whonix:**
+  * **Enabling system and template updates over the Tor anonymity network using Whonix:**
-   If you select this option, then whenever you install or update software in dom0 or a TemplateVM, the internet traffic will go through Tor.
+  If you select this option, then whenever you install or update software in dom0 or a TemplateVM, the internet traffic will go through Tor.
- * **Create USB qube holding all USB controllers:**
+* **Create USB qube holding all USB controllers:**
-   Just like the network qube for the network stack, the USB qube isolates the USB controllers.
+  Just like the network qube for the network stack, the USB qube isolates the USB controllers.
-   * **Use sys-net qube for both networking and USB devices:**
+  * **Use sys-net qube for both networking and USB devices:**
-   You should select this option if you rely on a USB device for network access, such as a USB modem or a USB Wi-Fi adapter.
+  You should select this option if you rely on a USB device for network access, such as a USB modem or a USB Wi-Fi adapter.
- * **Do not configure anything:**
+* **Do not configure anything:**
-   This is for very advanced users only.
+  This is for very advanced users only.
-   If you select this option, you'll have to set everything up manually afterward.
+  If you select this option, you'll have to set everything up manually afterward.
 
 When you're satisfied with you choices, press **Done**. 
 This configuration process may take a while, depending on the speed and compatibility of your system.
@@ -381,18 +382,17 @@ Consider giving back to the Qubes community and helping other users by [generati
 
 ## Getting help
 
- * We work very hard to make the [documentation] accurate, comprehensive useful and user friendly. 
+* We work very hard to make the [documentation] accurate, comprehensive useful and user friendly. 
-   We urge you to read it! It may very well contain the answers to your questions. 
+  We urge you to read it! It may very well contain the answers to your questions. 
-   (Since the documentation is a community effort, we'd also greatly appreciate your help in [improving] it!)
+  (Since the documentation is a community effort, we'd also greatly appreciate your help in [improving] it!)
 
- * If issues arise during installation, see the [Installation Troubleshooting](/doc/installation-troubleshooting) guide. 
+* If issues arise during installation, see the [Installation Troubleshooting](/doc/installation-troubleshooting) guide. 
 
- * If you don't find your answer in the documentation, please see [Help, Support, Mailing Lists, and Forum] for places to ask.
+* If you don't find your answer in the documentation, please see [Help, Support, Mailing Lists, and Forum] for places to ask.
 
- * Please do **not** email individual members of the Qubes team with questions about installation or other problems. 
+* Please do **not** email individual members of the Qubes team with questions about installation or other problems. 
    Instead, please see [Help, Support, Mailing Lists, and Forum] for appropriate places to ask questions.
 
-
 [QSB #46]: /news/2019/01/23/qsb-46/
 [system requirements]: /doc/system-requirements/
 [Qubes-certified hardware]: /doc/certified-hardware/
@@ -423,4 +423,3 @@ Consider giving back to the Qubes community and helping other users by [generati
 [advanced configuration]: /doc/#advanced-configuration
 [hcl-howto]: /doc/hcl/#generating-and-submitting-new-reports
 [Get Started]: /getting-started/
-

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

@@ -8,7 +8,6 @@ permalink: /doc/supported-versions/
 
 This page details the level and period of support for versions of operating systems in the Qubes ecosystem.
 
-
 ## Qubes OS
 
 Qubes OS releases are supported for **six months** after each subsequent major
@@ -26,7 +25,6 @@ past minor releases, are available from our [download mirrors].
 | Release 4.0 | 2018-03-28 | TBA        | Supported             |
 | Release 4.1 | TBA        | TBA        | [In development][4.1] |
 
-
 ### Note on point releases
 
 Please note that point releases, such as 3.2.1 and 4.0.1, do not designate separate, new versions of Qubes OS.
@@ -34,7 +32,6 @@ Rather, they designate their respective major or minor releases, such as 3.2 and
 For example, installing Release 4.0 and fully updating it results in the same system as installing Release 4.0.1.
 Therefore, point releases are not displayed as separate rows on any of the tables on this page.
 
-
 ## Dom0
 
 The table below shows the OS used for dom0 in each Qubes OS release.
@@ -49,14 +46,12 @@ The table below shows the OS used for dom0 in each Qubes OS release.
 | Release 4.0 | Fedora 25 |
 | Release 4.1 | Fedora 32 |
 
-
 ### Note on dom0 and EOL
 
 Dom0 is isolated from domUs. DomUs can access only a few interfaces, such as Xen, device backends (in the dom0 kernel and in other VMs, such as the NetVM), and Qubes tools (gui-daemon, qrexec-daemon, etc.).
 These components are [security-critical], and we provide updates for all of them (when necessary), regardless of the support status of the base distribution.
 For this reason, we consider it safe to continue using a given base distribution in dom0 even after it has reached end-of-life (EOL).
 
-
 ## TemplateVMs
 
 The following table shows select [TemplateVM] versions that are currently supported.
@@ -74,7 +69,6 @@ For upstream EOL information, see [Fedora EOL][fedora-eol] and [Debian EOL][debi
 
 \* Denotes versions for which we have published the packages but have not done extensive testing.
 
-
 ### Note on Whonix support
 
 [Whonix] TemplateVMs are supported by our partner, the [Whonix Project].
@@ -83,15 +77,14 @@ The Whonix Project has set its own support policy for Whonix TemplateVMs in Qube
 This policy requires Whonix TemplateVM users to stay reasonably close to the cutting edge by upgrading to new stable versions of Qubes OS and Whonix TemplateVMs within a month of their respective releases.
 To be precise:
 
- * One month after a new stable version of Qubes OS is released, Whonix TemplateVMs will no longer be supported on any older version of Qubes OS.
+* One month after a new stable version of Qubes OS is released, Whonix TemplateVMs will no longer be supported on any older version of Qubes OS.
-   This means that users who wish to continue using Whonix TemplateVMs on Qubes must always upgrade to the latest stable Qubes OS version within one month of its release.
+  This means that users who wish to continue using Whonix TemplateVMs on Qubes must always upgrade to the latest stable Qubes OS version within one month of its release.
 
- * One month after new stable versions of Whonix TemplateVMs are released, older versions of Whonix TemplateVMs will no longer be supported.
+* One month after new stable versions of Whonix TemplateVMs are released, older versions of Whonix TemplateVMs will no longer be supported.
-   This means that users who wish to continue using Whonix TemplateVMs on Qubes must always upgrade to the latest stable Whonix TemplateVM versions within one month of their release.
+  This means that users who wish to continue using Whonix TemplateVMs on Qubes must always upgrade to the latest stable Whonix TemplateVM versions within one month of their release.
 
 We aim to announce both types of events one month in advance in order to remind users to upgrade.
 
-
 [Version Scheme]: /doc/version-scheme/
 [Downloads]: /downloads/
 [download mirrors]: /downloads/#mirrors
@@ -106,4 +99,3 @@ We aim to announce both types of events one month in advance in order to remind
 [Whonix]: /doc/whonix/
 [Whonix Project]: https://www.whonix.org/
 [Debian-LTS]: https://wiki.debian.org/LTS
-

user/downloading-installing-upgrading/testing.md

@@ -13,21 +13,23 @@ Never rely on code that is in testing for critical work!
 
 Releases
 --------
+
 How to test upcoming Qubes OS releases:
 
- * Use [qubes-builder] to build the latest release.
+* Use [qubes-builder] to build the latest release.
- * Test the latest release candidate (RC), if any is currently available.
+* Test the latest release candidate (RC), if any is currently available.
- * (No support) Experiment with devel alpha ISOs found from time to time at [Qubes OpenQA](https://openqa.qubes-os.org/).
+* (No support) Experiment with devel alpha ISOs found from time to time at [Qubes OpenQA](https://openqa.qubes-os.org/).
 
 See [Version Scheme] for details about release versions and schedules.
 See [Release Checklist] for details about the RC process.
 
 Updates
 -------
+
 How to test updates:
 
- * Enable [dom0 testing repositories].
+* Enable [dom0 testing repositories].
- * Enable [TemplateVM testing repositories].
+* Enable [TemplateVM testing repositories].
 
 Every new update is first uploaded to the `security-testing` repository if it is a security update or `current-testing` if it is a normal update.
 The update remains in `security-testing` or `current-testing` for a minimum of one week.
@@ -42,6 +44,7 @@ While this limitation can be inconvenient, the benefits outweigh the costs, sinc
 
 Providing Feedback
 ------------------
+
 If you're testing new releases or updates, we would be grateful for your feedback.
 
 We use an [automated build process].
@@ -50,7 +53,6 @@ We welcome any kind of feedback on any package in any testing repository.
 Even a simple <span class="fa fa-thumbs-up" title="Thumbs Up"></span> or <span class="fa fa-thumbs-down" title="Thumbs Down"></span> on the package's associated issue would help us to decide whether the package is ready to be migrated to a stable repository.
 If you [report a bug] in a package that is in a testing repository, please reference the appropriate issue in [updates-status].
 
-
 [contribute]: /doc/contributing/
 [qubes-builder]: /doc/qubes-builder/
 [Version Scheme]: /doc/version-scheme/
@@ -61,4 +63,3 @@ If you [report a bug] in a package that is in a testing repository, please refer
 [updates-status]: https://github.com/QubesOS/updates-status/issues
 [report a bug]: /doc/reporting-bugs/
 [Providing Feedback]: #providing-feedback
-