From 67a92614aa9f4c0efc74fb59521260033ae6bb05 Mon Sep 17 00:00:00 2001 From: Maya Date: Sat, 13 Mar 2021 18:03:23 +0100 Subject: [PATCH] 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 | 26 +- developer/building/qubes-builder-details.md | 34 +- developer/building/qubes-builder.md | 185 ++++---- developer/building/qubes-iso-building.md | 4 +- developer/code/code-signing.md | 47 +- developer/code/coding-style.md | 118 ++--- developer/code/source-code.md | 17 +- developer/debugging/automated-tests.md | 37 +- developer/debugging/mount-lvm-image.md | 17 +- developer/debugging/profiling.md | 18 +- developer/debugging/test-bench.md | 21 +- developer/debugging/vm-interface.md | 151 +++---- developer/debugging/windows-debugging.md | 53 ++- developer/general/devel-books.md | 14 +- developer/general/doc-guidelines.md | 50 +-- developer/general/gsoc.md | 194 ++++---- developer/general/gsod.md | 41 +- developer/general/join.md | 3 +- developer/general/package-contributions.md | 79 ++-- developer/general/usability-ux.md | 4 +- developer/releases/1_0/release-notes.md | 28 +- developer/releases/2_0/release-notes.md | 30 +- developer/releases/3_0/release-notes.md | 19 +- developer/releases/3_1/release-notes.md | 18 +- developer/releases/3_1/schedule.md | 2 +- developer/releases/3_2/release-notes.md | 18 +- developer/releases/3_2/schedule.md | 6 +- developer/releases/4_0/release-notes.md | 17 +- developer/releases/4_0/schedule.md | 10 +- developer/releases/notes.md | 13 +- developer/releases/schedules.md | 9 +- developer/releases/todo.md | 3 + developer/services/admin-api.md | 28 +- developer/services/dom0-secure-updates.md | 6 +- developer/services/dvm-impl.md | 36 +- developer/services/qfilecopy.md | 8 +- developer/services/qfileexchgd.md | 35 +- developer/services/qmemman.md | 49 +- developer/services/qrexec-internals.md | 48 +- developer/services/qrexec-socket-services.md | 4 + developer/services/qrexec2.md | 76 ++-- developer/system/architecture.md | 60 ++- developer/system/audio.md | 25 +- developer/system/gui.md | 226 +++++----- developer/system/networking.md | 19 +- developer/system/security-critical-code.md | 34 +- developer/system/storage-pools.md | 3 +- developer/system/template-implementation.md | 71 ++- introduction/contributing.md | 2 - introduction/faq.md | 243 +++++----- introduction/intro.html | 3 +- introduction/reporting-bugs.md | 2 - introduction/statistics.md | 22 +- introduction/support.md | 124 +++-- project-security/canary-checklist.md | 24 +- project-security/canary-template.md | 1 - .../security-bulletins-checklist.md | 26 +- .../security-bulletins-template.md | 1 - project-security/security-pack.md | 284 ++++++------ project-security/security.md | 37 +- project-security/verifying-signatures.md | 425 +++++++++--------- project-security/xsa.md | 2 +- user/advanced-configuration/awesome.md | 12 +- user/advanced-configuration/bind-dirs.md | 7 +- user/advanced-configuration/config-files.md | 36 +- .../disposablevm-customization.md | 207 ++++++--- .../gui-configuration.md | 3 +- user/advanced-configuration/i3.md | 36 +- .../installing-contributed-packages.md | 22 +- user/advanced-configuration/kde.md | 28 +- .../managing-vm-kernel.md | 88 ++-- .../mount-from-other-os.md | 82 ++-- .../resize-disk-image.md | 48 +- user/advanced-configuration/rpc-policy.md | 1 - user/advanced-configuration/salt.md | 167 ++++--- .../secondary-storage.md | 83 ++-- user/advanced-configuration/usb-qubes.md | 134 +++--- .../backup-emergency-restore-v2.md | 26 +- .../backup-emergency-restore-v3.md | 7 +- .../backup-emergency-restore-v4.md | 5 +- user/common-tasks/backup-restore.md | 54 ++- user/common-tasks/block-devices.md | 172 +++---- user/common-tasks/copy-from-dom0.md | 13 +- user/common-tasks/device-handling.md | 24 +- user/common-tasks/disposablevm.md | 82 ++-- user/common-tasks/full-screen-mode.md | 1 - user/common-tasks/getting-started.md | 83 ++-- user/common-tasks/optical-discs.md | 1 - user/common-tasks/pci-devices.md | 91 ++-- user/common-tasks/software-update-dom0.md | 53 ++- user/common-tasks/software-update-domu.md | 68 ++- user/common-tasks/updating-qubes-os.md | 7 +- user/common-tasks/usb-devices.md | 96 ++-- user/common-tasks/volume-backup-revert.md | 16 +- .../custom-install.md | 50 ++- .../download-mirrors.md | 11 +- .../install-security.md | 44 +- .../installation-guide.md | 65 ++- .../supported-versions.md | 16 +- .../testing.md | 15 +- .../upgrade/upgrade-to-r2.md | 14 +- .../upgrade/upgrade-to-r2b1.md | 21 +- .../upgrade/upgrade-to-r2b2.md | 30 +- .../upgrade/upgrade-to-r2b3.md | 22 +- .../upgrade/upgrade-to-r3_0.md | 111 +++-- .../upgrade/upgrade-to-r3_1.md | 76 ++-- .../upgrade/upgrade-to-r3_2.md | 138 +++--- .../upgrade/upgrade-to-r4_0.md | 16 +- .../upgrade/upgrade.md | 18 +- .../version-scheme.md | 2 - user/hardware/certified-hardware.md | 8 - user/hardware/hardware-testing.md | 22 +- user/hardware/system-requirements.md | 70 ++- user/managing-os/debian/debian-upgrade.md | 116 ++--- user/managing-os/debian/debian.md | 34 +- user/managing-os/fedora/fedora-upgrade.md | 169 ++++--- user/managing-os/fedora/fedora.md | 14 +- user/managing-os/minimal-templates.md | 62 +-- user/managing-os/reinstall-template.md | 38 +- user/managing-os/standalone-and-hvm.md | 46 +- user/managing-os/templates.md | 129 +++--- user/managing-os/windows.md | 11 +- user/managing-os/xfce-templates.md | 18 +- user/reference/glossary.md | 110 +++-- user/reference/qubes-service.md | 3 +- user/reference/tools.md | 15 +- user/security-in-qubes/anti-evil-maid.md | 5 +- user/security-in-qubes/data-leaks.md | 16 +- .../device-handling-security.md | 13 +- user/security-in-qubes/firewall.md | 153 ++++--- user/security-in-qubes/split-gpg.md | 181 ++++---- user/security-in-qubes/u2f-proxy.md | 2 +- user/security-in-qubes/vm-sudo.md | 92 ++-- user/security-in-qubes/yubi-key.md | 101 +++-- user/troubleshooting/disk-troubleshooting.md | 74 +-- user/troubleshooting/gui-troubleshooting.md | 25 +- user/troubleshooting/hvm-troubleshooting.md | 50 ++- .../installation-troubleshooting.md | 28 +- .../managing-appvm-shortcuts.md | 13 +- user/troubleshooting/media-troubleshooting.md | 19 +- user/troubleshooting/pci-troubleshooting.md | 79 ++-- .../resume-suspend-troubleshooting.md | 24 +- user/troubleshooting/uefi-troubleshooting.md | 124 ++--- .../troubleshooting/update-troubleshooting.md | 32 +- .../updating-debian-and-whonix.md | 10 +- user/troubleshooting/usb-troubleshooting.md | 79 ++-- user/troubleshooting/vm-troubleshooting.md | 47 +- user/troubleshooting/vpn-troubleshooting.md | 20 +- 148 files changed, 4025 insertions(+), 3639 deletions(-) diff --git a/developer/building/development-workflow.md b/developer/building/development-workflow.md index 3f9b2fcd..50f1c386 100644 --- a/developer/building/development-workflow.md +++ b/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 different `update_repo.sh` script in source VM (below) - - use `local.UpdateApt` qrexec service in target VM (code below) - - in target VM additionally place `update-local-repo.sh` script in repository dir (code below) +- 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 `local.UpdateApt` qrexec service in target VM (code below) +- in target VM additionally place `update-local-repo.sh` script in repository dir (code below) `update_repo.sh` script: diff --git a/developer/building/qubes-builder-details.md b/developer/building/qubes-builder-details.md index b71d03ec..d36d3736 100644 --- a/developer/building/qubes-builder-details.md +++ b/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. -- `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. +- `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. 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: - - `WDK` - Windows Driver Kit (default). Command used to build: *build -cZg*. - - `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_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: - - `CERT_FILENAME` Path to key file (pfx format) - - `CERT_PASSWORD` Key password - - `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 - - `SIGNTOOL` Path to signtool -- `WIN_PACKAGE_CMD` Command used to produce installation package (msi or msm). Default value is *wix.bat*, similar to above - use *true* if you don't want this command. -- `WIN_OUTPUT_HEADERS` Directory (relative to `WIN_SOURCE_SUBDIRS` element) with public headers of the package - for use in other components. -- `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 (*\/\/\*), 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_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*. + - `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_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: + - `CERT_FILENAME` Path to key file (pfx format) + - `CERT_PASSWORD` Key password + - `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 + - `SIGNTOOL` Path to signtool +- `WIN_PACKAGE_CMD` Command used to produce installation package (msi or msm). Default value is *wix.bat*, similar to above - use *true* if you don't want this command. +- `WIN_OUTPUT_HEADERS` Directory (relative to `WIN_SOURCE_SUBDIRS` element) with public headers of the package - for use in other components. +- `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 (*\/\/\*), 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. builder.conf settings --------------------- diff --git a/developer/building/qubes-builder.md b/developer/building/qubes-builder.md index 008c00d9..b4209921 100644 --- a/developer/building/qubes-builder.md +++ b/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 -- 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 +- sudo +- 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 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,95 +50,107 @@ 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 - # edit the builder.conf file and set the following variables: - NO_SIGN=1 +```shell +cp example-configs/qubes-os-master.conf builder.conf +# 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). +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 - %_gpg_path /home/user/.gnupg - %_gpg_name AC1BF9B3 # <-- Key ID used for signing +```bash +%_signature gpg +%_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 - gpg --recv-keys 0xDDFA1A3E36879494 - - # Verify its fingerprint, set as 'trusted'. - # This is described here: - # https://www.qubes-os.org/doc/VerifyingSignatures - - wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc - gpg --import qubes-developers-keys.asc - - git clone git://github.com/QubesOS/qubes-builder.git qubes-builder - cd qubes-builder +```shell +# Import the Qubes master key +gpg --recv-keys 0xDDFA1A3E36879494 - # Verify its integrity: - git tag -v `git describe` - - cp example-configs/qubes-os-master.conf builder.conf - # edit the builder.conf file and set the following variables: - # NO_SIGN="1" - - # Download all components: - - make get-sources - - # And now to build all Qubes rpms (this will take a few hours): - - make qubes - - # ... and then to build the ISO - - make iso +# Verify its fingerprint, set as 'trusted'. +# This is described here: +# https://www.qubes-os.org/doc/VerifyingSignatures + +wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc +gpg --import qubes-developers-keys.asc + +git clone git://github.com/QubesOS/qubes-builder.git qubes-builder +cd qubes-builder + +# Verify its integrity: +git tag -v `git describe` + +cp example-configs/qubes-os-master.conf builder.conf +# edit the builder.conf file and set the following variables: +# NO_SIGN="1" + +# Download all components: + +make get-sources + +# And now to build all Qubes rpms (this will take a few hours): + +make qubes + +# ... and then to build the 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. +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) -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 +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: + - 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 - help`, or using `make build-info`. + help`, or using `make build-info`. 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. @@ -166,26 +185,26 @@ For legacy builds, it will not add the necessary configuration into the build en Also, once enabled, disabling this setting will not disable repositories in relevant chroots. And even if it did, there could be some leftover packages installed from those repos (which may or may not be desirable). -**Note** +**Note** 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 - 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 +```shell +GNUPGHOME=$PWD/keyrings/git gpg --import /path/to/key.asc +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). diff --git a/developer/building/qubes-iso-building.md b/developer/building/qubes-iso-building.md index f09d7af0..bc26a1cb 100644 --- a/developer/building/qubes-iso-building.md +++ b/developer/building/qubes-iso-building.md @@ -42,7 +42,7 @@ Get the necessary keys to verify the sources (run these and other commands below ~~~ wget https://keys.qubes-os.org/keys/qubes-master-signing-key.asc -gpg --import qubes-master-signing-key.asc +gpg --import qubes-master-signing-key.asc gpg --edit-key 36879494 fpr # Verify fingerprint! See Note below! @@ -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 ----------------- diff --git a/developer/code/code-signing.md b/developer/code/code-signing.md index e826561e..8e497695 100644 --- a/developer/code/code-signing.md +++ b/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.) @@ -56,7 +53,7 @@ Real name: Bilbo Baggins E-mail address: bilbo@shire.org -Comment: +Comment: You selected this USER-ID: "Bilbo Baggins " @@ -78,8 +75,7 @@ uid Bilbo Baggins 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. @@ -112,7 +107,7 @@ your Git commits. commit -S ~~~ -3. (Optional) Create signed tags. +3. (Optional) Create signed tags. Signed commits are totally sufficient to contribute to Qubes OS. However, if you have commits which are not signed and you do not want to change them, you can create a signed tag for the commit and push it before the check. @@ -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,16 +144,15 @@ 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: -1. Is the commit signed? +1. Is the commit signed? If the commit is not signed, you can see the message > policy/qubesos/code-signing — No signature found -2. If the commit is signed, the key is downloaded from a GPG key server. +2. If the commit is signed, the key is downloaded from a GPG key server. If you can see the following error message, please check if you have uploaded the key to a key server. > policy/qubesos/code-signing — Unable to verify (no valid key found) @@ -169,23 +162,29 @@ Although GitHub adds a little green `Verified` button next to the commit, the [s In this case, you have several options to sign the commit: -1. Amend the commit and replace it with a signed 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. + +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 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]. +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 - diff --git a/developer/code/coding-style.md b/developer/code/coding-style.md index 3c1e41ea..a7707b10 100644 --- a/developer/code/coding-style.md +++ b/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 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 provides for an aesthetically pleasing experience when one reads the code... +- 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 to easily review the code and catch various bugs, +- 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***: - - `ClassName` - - `some_variable`, `some_function`, `some_argument` +- **Naming conventions for any OS *other than Windows***: + - `ClassName` + - `some_variable`, `some_function`, `some_argument` -- **Naming convention *for Windows OS*** -- exceptionally to preserve Windows conventions please use the following: - - `ClassName`, `FunctionName` - - `pszArgumentOne`, `hPipe` -- use Hungarian notation for argument and variables +- **Naming convention *for Windows OS*** -- exceptionally to preserve Windows conventions please use the following: + - `ClassName`, `FunctionName` + - `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 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) -- Helper, non-executable files in `/usr/share/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/` -- 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` -- Logs: either log to the system-wide messages, or to `/var/log/qubes/` +- 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-*` +- 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/` +- 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/` +- 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` +- 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) -- 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` +- 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` 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! -- 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. -- 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 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. +- 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. +- 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: - - This creates natural boundaries between different code blocks, enforcing proper interfaces, and easing independent development to be conducted on various code parts at the same time, without the fear of running into conflicts. - - By maintaining relatively small git repositories, it is easy for new developers to understand the code and contribute new patches, without the need to understand all the other code. - - Code repositories represent also licensing boundaries. So, e.g. because `core-agent-linux` and `core-agent-windows` are maintained in two different repositories, it is possible to have the latter under a proprietary, non-GPL license, while keeping the former fully open source. - - We have drastically 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). +- 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. + - By maintaining relatively small git repositories, it is easy for new developers to understand the code and contribute new patches, without the need to understand all the other code. + - Code repositories represent also licensing boundaries. So, e.g. because `core-agent-linux` and `core-agent-windows` are maintained in two different repositories, it is possible to have the latter under a proprietary, non-GPL license, while keeping the former fully open source. + - We have drastically 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. - * Limit the subject line to approximately 50 characters. - * Capitalize the subject line. - * Do not end the subject line with a period. - * Use the imperative mood in the subject line. - * Wrap the body at 72 characters. - * Use the body to explain *what* and *why* rather than *how*. +- Separate the subject line from the body with a blank line. +- Limit the subject line to approximately 50 characters. +- Capitalize the subject line. +- Do not end the subject line with a period. +- Use the imperative mood in the subject line. +- Wrap the body at 72 characters. +- 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! -- 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.: +- 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. +- 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. -- Use `const` whenever possible, e.g. in function arguments passed via pointers. -- Do not mix procedural and objective code together -- if you write in C++, use classes and objects. -- Think about classes hierarchy, before starting to implement specific methods. +- Do not place code in `*.h` files. +- Use `const` whenever possible, e.g. in function arguments passed via pointers. +- Do not mix procedural and objective code together -- if you write in C++, use classes and objects. +- Think about classes hierarchy, before 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. diff --git a/developer/code/source-code.md b/developer/code/source-code.md index 6f1f531b..53d15691 100644 --- a/developer/code/source-code.md +++ b/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-agent-linux.git` -- GUI virtualization, Linux VM side. - * `linux-template-builder.git` -- Scripts and other files used to create Qubes +* `gui-daemon.git` -- GUI virtualization, Dom0 side. +* `gui-agent-linux.git` -- GUI virtualization, Linux VM side. +* `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]. @@ -35,9 +35,9 @@ e.g.: git clone https://github.com/QubesOS/qubes-core-admin.git core-admin ~~~ -To build Qubes you do not need to download all these repositories. +To build Qubes you do not need to download all these repositories. If you use [qubes builder] you can specify *what* you want to build, and download only the repositories needed to build that target. - + If you really do want to clone **all** of the repositories, you can use these commands: ~~~ @@ -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. diff --git a/developer/debugging/automated-tests.md b/developer/debugging/automated-tests.md index c222a34c..3e995eb3 100644 --- a/developer/debugging/automated-tests.md +++ b/developer/debugging/automated-tests.md @@ -7,14 +7,12 @@ 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). +Starting with Qubes R3 we use [python unittest][unittest] to perform automatic tests of Qubes OS. +Despite the name, we use it for both [unit tests](https://en.wikipedia.org/wiki/Unit_tests) and [integration tests](https://en.wikipedia.org/wiki/Integration_tests). The main purpose is, of course, to deliver much more stable releases. The integration tests must be run in dom0, but some unit tests can run inside a VM as well. @@ -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 - - `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_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) +- `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_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) ### 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: @@ -213,7 +218,7 @@ class SomeTestCase(unittest.TestCase): # first test that actually use event loop will try to dereference (already # destroyed) objects, resulting in SEGV self.loop = quamash.QEventLoop(self.qtapp) - + def tearDown(self): [...] # process any pending events before destroying the object @@ -237,11 +242,10 @@ class SomeTestCase(unittest.TestCase): gc.collect() ~~~ +## Installation Tests with openQA -Installation Tests with openQA ------------------------------- +**URL:** -**URL:** **Tests:** 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/ - diff --git a/developer/debugging/mount-lvm-image.md b/developer/debugging/mount-lvm-image.md index ca9f0901..c3a0a9db 100644 --- a/developer/debugging/mount-lvm-image.md +++ b/developer/debugging/mount-lvm-image.md @@ -6,8 +6,8 @@ permalink: /doc/mount-lvm-image/ # How to mount LVM image -You want to read your LVM image (e.g., there is a problem where you can't start any VMs except dom0). - +You want to read your LVM image (e.g., there is a problem where you can't start any VMs except dom0). + 1: make the image available for qubesdb. From dom0 terminal: @@ -25,7 +25,8 @@ From dom0 terminal: 3: Attach the device to your newly created disp VM -From the GUI, or from the command line: +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 diff --git a/developer/debugging/profiling.md b/developer/debugging/profiling.md index e20e3208..5b0512be 100644 --- a/developer/debugging/profiling.md +++ b/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`). diff --git a/developer/debugging/test-bench.md b/developer/debugging/test-bench.md index 6f2a9019..9ad7f335 100644 --- a/developer/debugging/test-bench.md +++ b/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 +``` diff --git a/developer/debugging/vm-interface.md b/developer/debugging/vm-interface.md index 7227c41e..f89b0171 100644 --- a/developer/debugging/vm-interface.md +++ b/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 -- XenStore (in Qubes 2, data the same as in QubesDB, keys without leading `/`) -- Qubes RPC (called at VM startup, or when configuration changed) -- GUI protocol +- QubesDB +- XenStore (in Qubes 2, data the same as in QubesDB, keys without leading `/`) +- Qubes RPC (called at VM startup, or when configuration changed) +- 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-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: - - `full` - all disks - - `rw-only` - only `/rw` disk - - `none` - none -- `/qubes-timezone - name of timezone based on dom0 timezone. For example `Europe/Warsaw` -- `/qubes-keyboard` (deprecated in R4.1) - keyboard layout based on dom0 layout. Its syntax is suitable for `xkbcomp` command (after expanding escape sequences like `\n` or `\t`). This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). This entry is created as part of gui-daemon initialization (so not available when gui-daemon disabled, or not started yet). -- `/keyboard-layout` - keyboard layout based on GuiVM layout. Its syntax can be `layout+variant+options`, `layout+variant`, `layout++options` or simply `layout`. For example, `fr+oss`, `pl++compose:caps` or `fr`. This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). -- `/qubes-debug-mode` - flag whether VM has debug mode enabled (qvm-prefs setting). One of `1`, `0` -- `/qubes-service/SERVICE_NAME` - subtree for VM services controlled from dom0 (using the `qvm-service` command or Qubes Manager). One of `1`, `0`. Note that not every service will be listed here, if entry is missing, it means "use VM default". A list of currently supported services is in the `qvm-service` man page. -- `/qubes-netmask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0" -- `/qubes-ip - IP address for this VM (only when VM has netvm set) -- `/qubes-gateway` - default gateway IP (only when VM has netvm set); VM should add host route to this address directly via eth0 (or whatever default interface name is) -- `/qubes-primary-dns` - primary DNS address (only when VM has netvm set) -- `/qubes-secondary-dns` - secondary DNS address (only when VM has netvm set) -- `/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-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-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 +- `/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-persistence` - what data do persist between VM restarts: + - `full` - all disks + - `rw-only` - only `/rw` disk + - `none` - none +- `/qubes-timezone - name of timezone based on dom0 timezone. For example `Europe/Warsaw` +- `/qubes-keyboard` (deprecated in R4.1) - keyboard layout based on dom0 layout. Its syntax is suitable for `xkbcomp` command (after expanding escape sequences like `\n` or `\t`). This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). This entry is created as part of gui-daemon initialization (so not available when gui-daemon disabled, or not started yet). +- `/keyboard-layout` - keyboard layout based on GuiVM layout. Its syntax can be `layout+variant+options`, `layout+variant`, `layout++options` or simply `layout`. For example, `fr+oss`, `pl++compose:caps` or `fr`. This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). +- `/qubes-debug-mode` - flag whether VM has debug mode enabled (qvm-prefs setting). One of `1`, `0` +- `/qubes-service/SERVICE_NAME` - subtree for VM services controlled from dom0 (using the `qvm-service` command or Qubes Manager). One of `1`, `0`. Note that not every service will be listed here, if entry is missing, it means "use VM default". A list of currently supported services is in the `qvm-service` man page. +- `/qubes-netmask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0" +- `/qubes-ip - IP address for this VM (only when VM has netvm set) +- `/qubes-gateway` - default gateway IP (only when VM has netvm set); VM should add host route to this address directly via eth0 (or whatever default interface name is) +- `/qubes-primary-dns` - primary DNS address (only when VM has netvm set) +- `/qubes-secondary-dns` - secondary DNS address (only when VM has netvm set) +- `/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-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-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 -#### 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 - - `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` - - `dsthost`, value: DNS hostname of destination host - - `proto`, values: `tcp`, `udp`, `icmp` - - `specialtarget`, value: One of predefined target, currently defined values: - - `dns` - such option should match DNS traffic to default DNS server (but +- `action`, values: `accept`, `drop`; this is present in every rule +- `dst4`, value: destination IPv4 address with a mask; for example: `192.168.0.0/24` +- `dst6`, value: destination IPv6 address with a mask; for example: `2000::/3` +- `dsthost`, value: DNS hostname of destination host +- `proto`, values: `tcp`, `udp`, `icmp` +- `specialtarget`, value: One of predefined target, currently defined values: + - `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; - - Qubes 3.x format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux. - - Qubes 4.0+ format: used memory size in the VM, in kbytes -- `/qubes-block-devices` - list of block devices exposed by this VM, each device (subdirectory) should be named in a way that VM can attach the device based on it. Each should contain these entries: - - `desc` - device description (ASCII text) - - `size` - device size in bytes - - `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: - - `desc` - device description (ASCII text) - - `usb-ver` - USB version (1, 2 or 3) +- `memory/meminfo` (**xenstore**) - used memory (updated by qubes-meminfo-writer), input information for qmemman; + - Qubes 3.x format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux. + - Qubes 4.0+ format: used memory size in the VM, in kbytes +- `/qubes-block-devices` - list of block devices exposed by this VM, each device (subdirectory) should be named in a way that VM can attach the device based on it. Each should contain these entries: + - `desc` - device description (ASCII text) + - `size` - device size in bytes + - `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: + - `desc` - device description (ASCII text) + - `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.WaitForSession` - called to wait for full VM startup -- `qubes.GetAppmenus` - receive appmenus from given VM (template); TODO: describe format here -- `qubes.GetImageRGBA` - receive image/application icon. Protocol: +- `qubes.SetMonitorLayout` - provide list of monitors, one per line. Each line contains four numbers: `width height X Y width_mm height_mm` (physical dimensions - `width_mm` and `height_mm` - are optional) +- `qubes.WaitForSession` - called to wait for full VM startup +- `qubes.GetAppmenus` - receive appmenus from given VM (template); TODO: describe format here +- `qubes.GetImageRGBA` - receive image/application icon. Protocol: - 1. Caller sends name of requested icon. This can be one of: - * `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:-` - * file name - 2. The service responds with image dimensions: width and height as + 1. Caller sends name of requested icon. This can be one of: + * `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:-` + * file name + 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,19 +189,19 @@ 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 `+` - - everything except alphanumeric characters, `.` and `_` needs to be + - the executable name and arguments are separated by `+` + - everything except alphanumeric characters, `.` and `_` needs to be escaped - - bytes are escaped as `-HH` (where `HH` is hex code, capital letters only) - - `-` itself can be escaped as `--` - - example: to run `ls -a /home/user`, use + - bytes are escaped as `-HH` (where `HH` is hex code, capital letters only) + - `-` itself can be escaped as `--` + - 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 - + Services called in GuiVM: - `policy.Ask`, `policy.Notify` - confirmation prompt and notifications for @@ -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. diff --git a/developer/debugging/windows-debugging.md b/developer/debugging/windows-debugging.md index f8f84450..624db505 100644 --- a/developer/debugging/windows-debugging.md +++ b/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**. -- In both copied files add the following line at the end: `serial = 'pty'`. This will make Xen connect VM's serial ports to dom0's ptys. -- From now on you need to start both VMs like this: `qvm-start --custom-config=/your/edited/host.conf host` -- To connect both VM serial ports together you will either need [socat](http://www.dest-unreach.org/socat/) or a custom utility described later. -- To determine which dom0 pty corresponds to VM's serial port you need to read xenstore, example script below: +- First, you need to prepare separate copies of both *target* and *host* VM configuration files with some changes. Copy the files from **/var/lib/qubes/appvms/vmname/vmname.conf** to some convenient location, let's call them **host.conf** and **target.conf**. +- In both copied files add the following line at the end: `serial = 'pty'`. This will make Xen connect VM's serial ports to dom0's ptys. +- From now on you need to start both VMs like this: `qvm-start --custom-config=/your/edited/host.conf host` +- To connect both VM serial ports together you will either need [socat](http://www.dest-unreach.org/socat/) or a custom utility described later. +- To determine which dom0 pty corresponds to VM's serial port you need to read xenstore, example script below: +```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 *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. -- Reboot the *target* VM. -- Run the above shell script in dom0. -- If everything is fine you should see the proper kernel debugging output in WinDbg. However, if you see something like that: +- 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](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. +- 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: ~~~ Opened \\.\com1 @@ -55,7 +58,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p Connected to Windows 7 7601 x64 target at (Wed Mar 19 20:35:43.262 2014 (UTC + 1:00)), ptr64 TRUE Kernel Debugger connection established. Symbol search path is: srv*c:\symbols*http://msdl.microsoft.com/download/symbols - Executable search path is: + Executable search path is: ... Retry sending the same data packet for 64 times. The transport connection between host kernel debugger and target Windows seems lost. please try resync with target, recycle the host debugger, or reboot the target Windows. @@ -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 #include #include @@ -85,11 +89,11 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p { static int count = 0; static unsigned char buf[17] = {0}; - + // relay to ouptput port write(fd2, &c, 1); fprintf(stderr, "%c", mark); - + /* dump all data going over the line if (count == 0) fprintf(stderr, "%c", mark); @@ -112,13 +116,13 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p unsigned char c = 0; struct termios tio; ssize_t size; - + if (argc < 3) { fprintf(stderr, "Usage: %s pty1 pty2 [mark character]\n", argv[0]); return EINVAL; } - + fd1 = open(argv[1], O_RDONLY | O_NOCTTY); if (fd1 <= 0) { @@ -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: > @@ -202,7 +207,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p > Connected to Windows 7 7601 x64 target at (Wed Mar 19 20:56:31.371 2014 (UTC + 1:00)), ptr64 TRUE > Kernel Debugger connection established. > Symbol search path is: srv*c:\symbols*http://msdl.microsoft.com/download/symbols -> Executable search path is: +> Executable search path is: > Windows 7 Kernel Version 7601 MP (1 procs) Free x64 > Built by: 7601.18247.amd64fre.win7sp1_gdr.130828-1532 > Machine Name: @@ -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 (``````) 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: diff --git a/developer/general/devel-books.md b/developer/general/devel-books.md index 4284b893..00564426 100644 --- a/developer/general/devel-books.md +++ b/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 Device Drivers](https://www.amazon.com/Linux-Device-Drivers-Jonathan-Corbet/dp/0596005903)_, by Jonathan Corbet + - _[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 - 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 - * _[Rapid GUI Programming with Python and Qt](http://www.qtrac.eu/pyqtbook.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 (Although note that [Qt is being replaced by GTK](/doc/usability-ux/#gnome-kde-and-xfce) in Qubes code.) diff --git a/developer/general/doc-guidelines.md b/developer/general/doc-guidelines.md index 8bb5a130..896d2aa2 100644 --- a/developer/general/doc-guidelines.md +++ b/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 hard for readers to miss information they need, since it's all in one place. +* 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. 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. - * 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 +* 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. +* Use hanging indentations where appropriate. - * 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 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.: +* 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 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.: + ~~~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/ diff --git a/developer/general/gsoc.md b/developer/general/gsoc.md index 2c0259b3..bf04228c 100644 --- a/developer/general/gsoc.md +++ b/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: - - [box format](https://www.vagrantup.com/docs/plugins/providers.html#box-format) - - method for running commands inside (ssh vs qvm-run) - - 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 - - Write integration tests +- Design how Vagrant Qubes provider should look like, including: + - [box format](https://www.vagrantup.com/docs/plugins/providers.html#box-format) + - method for running commands inside (ssh vs qvm-run) +- 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 +- Write integration tests **Knowledge prerequisite**: - - Ruby - - Vagrant concepts +- Ruby +- 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) - - [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) + +- [Low level GUI documentation](/doc/gui/) +- [qubes-gui-agent-linux](https://github.com/qubesos/qubes-gui-agent-linux) +- [qubes-gui-daemon](https://github.com/qubesos/qubes-gui-daemon) +- [Use Wayland instead of X11 to increase performance](https://github.com/qubesos/qubes-issues/issues/3366) **Knowledge prerequisite**: @@ -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. - - Update and fix build scripts for recent Qubes OS version. - - Update startup script to mount appropriate directories as either - copy-on-write (device-mapper snapshot), or tmpfs. - - 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 - copy-on-write layer and tmpfs (disable logging etc). - - Research option to install the system from live image. If feasible add - this option. +- Adjust set of VMs and templates included in live edition. +- Update and fix build scripts for recent Qubes OS version. +- Update startup script to mount appropriate directories as either + copy-on-write (device-mapper snapshot), or tmpfs. +- 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 + copy-on-write layer and tmpfs (disable logging etc). +- Research option to install the system from live image. If feasible add + this option. **Knowledge prerequisite**: - - System startup sequence: bootloaders (isolinux, syslinux, grub, UEFI), initramfs, systemd. - - Python and Bash scripting - - Filesystems and block devices: loop devices, device-mapper, tmpfs, overlayfs, sparse files. +- System startup sequence: bootloaders (isolinux, syslinux, grub, UEFI), initramfs, systemd. +- Python and Bash scripting +- 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 - in log-collecting VM) the better. - - Implement log collecting service. Besides logs itself, should save - information about logs origin (VM name) and timestamp. The service should - _not_ trust sending VM in any of those. - - Implement log forwarder compatible with systemd-journald and rsyslog. A - mechanism (service/plugin) fetching logs in real time from those and sending - to log-collecting VM over qrexec service. - - Document the protocol. - - Write unit tests and integration tests. +- Design a _simple_ protocol for transferring logs. The less metadata (parsed + in log-collecting VM) the better. +- Implement log collecting service. Besides logs itself, should save + information about logs origin (VM name) and timestamp. The service should + _not_ trust sending VM in any of those. +- Implement log forwarder compatible with systemd-journald and rsyslog. A + mechanism (service/plugin) fetching logs in real time from those and sending + to log-collecting VM over qrexec service. +- Document the protocol. +- Write unit tests and integration tests. **Knowledge prerequisite**: - - syslog - - systemd - - Python/Bash scripting +- syslog +- systemd +- 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 -- implement corridor feature request add IPv6 support / port to nftables - https://github.com/rustybird/corridor/issues/39 +- 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 - [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 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). - - (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) - - User documentation - - Automated tests (unit tests, integration tests) +- 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 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) 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 +- Automated tests (unit tests, integration tests) **Knowledge prerequisite**: - - Python scripting - - Linux administration, including handling loop devices, partition tables, filesystems etc - - For optional features, C language and x86 architecture (ACPI tables) +- Python scripting +- Linux administration, including handling loop devices, partition tables, filesystems etc +- 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 - - 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) - - More info: [#1806](https://github.com/QubesOS/qubes-issues/issues/1806) +- patching window manager to add colorful borders +- 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) +- More info: [#1806](https://github.com/QubesOS/qubes-issues/issues/1806) **Expected results**: - - Review existing support for other desktop environments (KDE, Xfce4, i3, awesome). - - Patch window manager to draw colorful borders (we use only server-side - decorations), there is already very similar patch in - [Cappsule project](https://github.com/cappsule/cappsule-gui). - - Configure GNOME to not make use of dom0 user home in visible way (no search - in files there, no file manager, etc). - - Configure GNOME to not look into external devices plugged in (no auto - mounting, device notifications etc). - - Package above modifications as rpms, preferably as extra configuration files - and/or plugins than overwriting existing files. Exceptions to this rule may - apply if no other option. - - Adjust comps.xml (in installer-qubes-os repo) to define package group with - all required packages. - - Document installation procedure. +- Review existing support for other desktop environments (KDE, Xfce4, i3, awesome). +- Patch window manager to draw colorful borders (we use only server-side + decorations), there is already very similar patch in + [Cappsule project](https://github.com/cappsule/cappsule-gui). +- Configure GNOME to not make use of dom0 user home in visible way (no search + in files there, no file manager, etc). +- Configure GNOME to not look into external devices plugged in (no auto + mounting, device notifications etc). +- Package above modifications as rpms, preferably as extra configuration files + and/or plugins than overwriting existing files. Exceptions to this rule may + apply if no other option. +- Adjust comps.xml (in installer-qubes-os repo) to define package group with + all required packages. +- Document installation procedure. **Knowledge prerequisite**: - - GNOME architecture - - C language (patching metacity) - - Probably also javascript - for modifying GNOME shell extensions +- GNOME architecture +- C language (patching metacity) +- 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,22 +385,22 @@ 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. - - [#3894](https://github.com/QubesOS/qubes-issues/issues/3894) on porting to L4 microkernel. +- [#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. **Expected results**: - - 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). - - Aarch64 specific integration and unit tests. - - Production of generic u-boot or uefi capable image/iso for target hardware. +- 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). +- Aarch64 specific integration and unit tests. +- Production of generic u-boot or uefi capable image/iso for target hardware. **Knowledge prerequisite**: - - Libvirt and Qubes toolstacks (C and python languages). - - Xen debugging. - - General ARM architecture knowledge. - +- Libvirt and Qubes toolstacks (C and python languages). +- Xen debugging. +- General ARM architecture knowledge. + **Mentor**: [Marek Marczykowski-Górecki](/team/) @@ -426,17 +427,17 @@ More information and further links can be found in the related issue: **Expected results**: - - Add cross-compilation support to qubes-builder and related components. - - Make ppc64 specific adjustments to Qubes toolstacks/manager (including passthrough of devices from device tree to guest domains). - - ppc64 specific integration and unit tests. - - Production of generic u-boot or uefi capable image/iso for target hardware. +- Add cross-compilation support to qubes-builder and related components. +- Make ppc64 specific adjustments to Qubes toolstacks/manager (including passthrough of devices from device tree to guest domains). +- ppc64 specific integration and unit tests. +- Production of generic u-boot or uefi capable image/iso for target hardware. **Knowledge prerequisite**: - - Libvirt and Qubes toolstacks (C and python languages). - - KVM or XEN internals - - General ppc64 architecture knowledge. - +- Libvirt and Qubes toolstacks (C and python languages). +- KVM or XEN internals +- 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**: @@ -521,7 +523,7 @@ A [Fuzzer](https://en.wikipedia.org/wiki/Fuzzing) would help to automate part of ## Past Projects -You can view the projects we had in 2017 in the [GSoC 2017 archive][2017-archive]. We also participated in GSoC 2020, and you can see the project in the [GSoC 2020 archive][2020-archive]. +You can view the projects we had in 2017 in the [GSoC 2017 archive][2017-archive]. We also participated in GSoC 2020, and you can see the project in the [GSoC 2020 archive][2020-archive]. Here are some successful projects which have been implemented in the past by Google Summer of Code participants. @@ -551,14 +553,14 @@ would override all the user changes there). More details: files, LVM thin volumes etc). - template metadata, templates repository - enable the user to browse available templates (probably should be done in dedicated VM, or DisposableVM) - - manual template removal by users (without it, see problems such + - manual template removal by users (without it, see problems such as [#5509](https://github.com/QubesOS/qubes-issues/issues/5509) - Implement the above mechanism: - tool to download named template - should perform download operation in some VM (as dom0 have no network access), then transfer the data to dom0, verify its integrity and then create Template VM and feed it's root filesystem image with downloaded data. - - tool to browse templates repository - both CLI and GUI (preferably integrated + - tool to browse templates repository - both CLI and GUI (preferably integrated with existing Template Manager tool) - integrate both tools - user should be able to choose some template to be installed from repository browsing tool - see diff --git a/developer/general/gsod.md b/developer/general/gsod.md index 46c9c2fd..da15a128 100644 --- a/developer/general/gsod.md +++ b/developer/general/gsod.md @@ -29,21 +29,22 @@ Here's a suggested template for adding project ideas: **Mentor**: Name and email address. ``` + ### Offline documentation **Project**: Offline documentation **Brief explanation**: Qubes OS has thorough documentation on the project website, however a user may find it more convenient to view documentation - especially for troubleshooting network issues -- offline on their Qubes machine. This will improve usability for new users and better support users if they need to troubleshoot anything. -**Expected results**: +**Expected results**: - - Review [past discussions on the issue](https://github.com/QubesOS/qubes-issues/issues/1019) - - Recommend workflow and platform for displaying offline documentation - - Test workflow and platform to ensure usability and functionality +- Review [past discussions on the issue](https://github.com/QubesOS/qubes-issues/issues/1019) +- Recommend workflow and platform for displaying offline documentation +- Test workflow and platform to ensure usability and functionality -**Knowledge prerequisite**: +**Knowledge prerequisite**: - - [Markdown][markdown] +- [Markdown][markdown] **Mentor**: [Marek Marczykowski-Górecki][team] @@ -53,14 +54,14 @@ Here's a suggested template for adding project ideas: **Brief explanation**: When a user first boots Qubes after installing it, there is an opportunity to introduce the user to some of the unique functionality Qubes has. -**Expected results**: +**Expected results**: - - Review [past discussions on the issue](https://github.com/QubesOS/qubes-issues/issues/1774) - - Provide visual mock-ups and proposed text - -**Knowledge prerequisite**: +- Review [past discussions on the issue](https://github.com/QubesOS/qubes-issues/issues/1774) +- Provide visual mock-ups and proposed text - - some experience with Anaconda would be helpful +**Knowledge prerequisite**: + +- some experience with Anaconda would be helpful **Mentor**: [Marek Marczykowski-Górecki][team] @@ -92,16 +93,16 @@ Additionally, terminology is used inconsistently. **Brief explanation**: The Qubes OS is missing an installation guide for virtual machines. Users are installing an outdated and unsupported version of Qubes OS (3.2) instead of the supported version. There is unofficial [existing installation guide] for Qubes OS on a virtual box but it is misleading and lacks documentation. Usually, users face some errors and bugs while installing Qubes OS on a virtual machine.[virtual box issue] -**Expected results**: +**Expected results**: -Provide a new option of installation guide for users working on virtual machines. -Review existing problems and provide solutions to them. -Giving a warning for using outdated versions. -**Knowledge prerequisite**: +**Knowledge prerequisite**: - Experience in virtual boxes and machines. - Basic Knowledge about Fedora linux architecture. - [Markdown][markdown] - + **Mentor**: [Marek Marczykowski-Górecki][team] ## Past Projects @@ -110,7 +111,7 @@ You can view the project we had in 2019 in the [2019 GSoD archive][2019-qubes-gs You can also view the project we had in 2020 in the [2020 GSoD archive][2020-qubes-gsod] and the [2020 writer's report][2020-qubes-report]. -Here are some successful projects which have been implemented in the past by Google Season of Docs participants. +Here are some successful projects which have been implemented in the past by Google Season of Docs participants. ### Consolidate troubleshooting guides @@ -135,14 +136,14 @@ This could be helped by writing consolidated guide with with a clear list of sym **Project**: Improve Getting Started page -**Brief explanation**: The [Getting Started page](https://www.qubes-os.org/getting-started/) is the place a new user would go to understand better how to use Qubes. It is currently has old screenshots not using the default desktop environment and could have much better flow. In addition, this improved page content may end up being served more directly to the user via the [offline documentation](#offline-documentation) or the [firstboot guide](#create-guide-on-firstboot-for-new-users). +**Brief explanation**: The [Getting Started page](https://www.qubes-os.org/getting-started/) is the place a new user would go to understand better how to use Qubes. It is currently has old screenshots not using the default desktop environment and could have much better flow. In addition, this improved page content may end up being served more directly to the user via the [offline documentation](#offline-documentation) or the [firstboot guide](#create-guide-on-firstboot-for-new-users). -**Expected results**: +**Expected results**: - Review the existing page and website, similar pages for other OSes - - Provide visual mock-ups and proposed text + - Provide visual mock-ups and proposed text -**Knowledge prerequisite**: +**Knowledge prerequisite**: - basic Qubes OS knowledge - [Markdown][markdown] diff --git a/developer/general/join.md b/developer/general/join.md index ef195556..6a5d9126 100644 --- a/developer/general/join.md +++ b/developer/general/join.md @@ -9,5 +9,4 @@ 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/). - +In the meantime, there are many different ways you can [contribute to the Qubes OS project](/doc/contributing/). diff --git a/developer/general/package-contributions.md b/developer/general/package-contributions.md index 0c8bd9d5..ac7ac96d 100644 --- a/developer/general/package-contributions.md +++ b/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. - * Be published under an open-source license (read about the [Qubes OS License]). - * Follow our [coding guidelines]. - * Be thoroughly tested. - * Have a clearly-defined use case for Qubes users. - * Not be unduly burdensome to review. +* In no way weaken the security of Qubes OS. +* Be published under an open-source license (read about the [Qubes OS License]). +* Follow our [coding guidelines]. +* Be thoroughly tested. +* Have a clearly-defined use case for Qubes users. +* 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]. - 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]. - 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. - 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 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). - We appreciate your understanding! - 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 not to accept your contribution, we will state the reason and close the issue. +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]. +3. If you haven't already, [sign your code][sig]. +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. + 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 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). + We appreciate your understanding! +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 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. - 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. - 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.) - 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. - 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. +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]. +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. + (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. +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 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), - - All downloaded components should be verified against static hash, - - RPM/DEB installation scripts (e.g. looking at constraints who would hijack other packages), - - Makefiles, - - Package build [reproducible] + +* Package dependencies, +* Build scripts (including downloaded ones), +* All downloaded components should be verified against static hash, +* RPM/DEB installation scripts (e.g. looking at constraints who would hijack other packages), +* 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. - * Decide when the package has reached a new version, and notify the Qubes core developers when this occurs. +* [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. 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 diff --git a/developer/general/usability-ux.md b/developer/general/usability-ux.md index d703ec76..839e286a 100644 --- a/developer/general/usability-ux.md +++ b/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 diff --git a/developer/releases/1_0/release-notes.md b/developer/releases/1_0/release-notes.md index 6a6f5ec7..087acafe 100644 --- a/developer/releases/1_0/release-notes.md +++ b/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 @@ -51,6 +46,5 @@ If you're already running Qubes 1.0-rc1, you don't need to reinstall, it's just If you have Qubes Beta 3 currently installed on your system, you must reinstall from scratch, as we offer no direct upgrade option in the installer (sorry). However, we do offer tools for smooth migration of your AppVMs. In order to do that, please backup your AppVMs using the `qvm-backup` tool [as usual](/doc/backup-restore/). Then, after you install Qubes 1.0 rc1, you can restore them using `qvm-backup-restore` tool. However, because we have changed the default template in RC1, you should tell qvm-back-restore about that by passing `--replace-template` option: ~~~ -qvm-backup-restore --replace-template=fedora-15-x64:fedora-17-x64 +qvm-backup-restore --replace-template=fedora-15-x64:fedora-17-x64 ~~~ - diff --git a/developer/releases/2_0/release-notes.md b/developer/releases/2_0/release-notes.md index 10c75de2..c4cb8287 100644 --- a/developer/releases/2_0/release-notes.md +++ b/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 diff --git a/developer/releases/3_0/release-notes.md b/developer/releases/3_0/release-notes.md index ec3d030d..1bc5872d 100644 --- a/developer/releases/3_0/release-notes.md +++ b/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/). - diff --git a/developer/releases/3_1/release-notes.md b/developer/releases/3_1/release-notes.md index 160d1b90..f22127f5 100644 --- a/developer/releases/3_1/release-notes.md +++ b/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 diff --git a/developer/releases/3_1/schedule.md b/developer/releases/3_1/schedule.md index ede408ed..b26d259e 100644 --- a/developer/releases/3_1/schedule.md +++ b/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 | -| 16 Feb 2016
23 Feb 2016 | 3.1-rc3 release | +| ~~16 Feb 2016~~
23 Feb 2016 | 3.1-rc3 release | diff --git a/developer/releases/3_2/release-notes.md b/developer/releases/3_2/release-notes.md index 24119153..81c92c9c 100644 --- a/developer/releases/3_2/release-notes.md +++ b/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 diff --git a/developer/releases/3_2/schedule.md b/developer/releases/3_2/schedule.md index 05dc5599..e232d275 100644 --- a/developer/releases/3_2/schedule.md +++ b/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 | -| 16 Jul 2016
20 Jul 2016 | current-testing freeze before 3.2-rc2 | -| 23 Jul 2016
27 Jul 2016 | 3.2-rc2 release | -| 5 Aug 2016
9 Aug 2016 | decide whether 3.2-rc2 is the final 3.2 | +| ~~16 Jul 2016~~
20 Jul 2016 | current-testing freeze before 3.2-rc2 | +| ~~23 Jul 2016~~
27 Jul 2016 | 3.2-rc2 release | +| ~~5 Aug 2016~~
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 | diff --git a/developer/releases/4_0/release-notes.md b/developer/releases/4_0/release-notes.md index f2d8b804..8358b9a2 100644 --- a/developer/releases/4_0/release-notes.md +++ b/developer/releases/4_0/release-notes.md @@ -40,28 +40,28 @@ Security Notes These must be set manually. * The following steps may need to be applied in dom0 and Fedora 26 TemplateVMs in order to receive updates (see [#3737]). - + Steps for dom0 updates: - + 1. Open the Qubes Menu by clicking on the "Q" icon in the top-left corner of the screen. 2. Select `Terminal Emulator`. 3. In the window that opens, enter this command: - + sudo nano /etc/yum.repos.d/qubes-dom0.repo - + 4. This opens the nano text editor. Change all four instances of `http` to `https`. 5. Press `CTRL+X`, then `Y`, then `ENTER` to save changes and exit. 6. Check for updates normally. - + Steps for Fedora 26 TemplateVM updates: - + 1. Open the Qubes Menu by clicking on the "Q" icon in the top-left corner of the screen. 2. Select `Template: fedora-26`, then `fedora-26: Terminal`. 3. In the window that opens, enter the command for your version: - + [Qubes 3.2] sudo gedit /etc/yum.repos.d/qubes-r3.repo [Qubes 4.0] sudo gedit /etc/yum.repos.d/qubes-r4.repo - + 4. This opens the gedit text editor in a window. Change all four instances of `http` to `https`. 5. Click the "Save" button in the top-right corner of the window. 6. Close the window. @@ -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 diff --git a/developer/releases/4_0/schedule.md b/developer/releases/4_0/schedule.md index ca2a3c5c..99a2f320 100644 --- a/developer/releases/4_0/schedule.md +++ b/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 | -| 28 Aug 2017
11 Sep 2017
9 Oct 2017
18 Oct 2017 | current-testing freeze before 4.0-rc2 | -| 4 Sep 2017
18 Sep 2017
16 Oct 2017
23 Oct 2017 | 4.0-rc2 release | -| 6 Nov 2017 | decide whether 4.0-rc2 is the final 4.0 | +| ~~28 Aug 2017~~
~~11 Sep 2017~~
~~9 Oct 2017~~
18 Oct 2017 | current-testing freeze before 4.0-rc2 | +| ~~4 Sep 2017~~
~~18 Sep 2017~~
~~16 Oct 2017~~
23 Oct 2017 | 4.0-rc2 release | +| 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 | -| 8 Jan 2018
31 Jan 2018 | 4.0-rc4 release | -| 22 Jan 2018
14 Feb 2018 | decide whether 4.0-rc4 is the final 4.0 | +| ~~8 Jan 2018~~
31 Jan 2018 | 4.0-rc4 release | +| ~~22 Jan 2018~~
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 | diff --git a/developer/releases/notes.md b/developer/releases/notes.md index cb1119f9..e6157b80 100644 --- a/developer/releases/notes.md +++ b/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 R2.0 release notes](/doc/releases/2.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.2 release notes](/doc/releases/3.2/release-notes/) - * [Qubes R4.0 release notes](/doc/releases/4.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 R3.0 release notes](/doc/releases/3.0/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 R4.0 release notes](/doc/releases/4.0/release-notes/) diff --git a/developer/releases/schedules.md b/developer/releases/schedules.md index 50c6824c..faba68c6 100644 --- a/developer/releases/schedules.md +++ b/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.1 release schedule](/doc/releases/3.1/schedule/) - * [Qubes R3.2 release schedule](/doc/releases/3.2/schedule/) - * [Qubes R4.0 release schedule](/doc/releases/4.0/schedule/) - +* [Qubes R3.0 release schedule](/doc/releases/3.0/schedule/) +* [Qubes R3.1 release schedule](/doc/releases/3.1/schedule/) +* [Qubes R3.2 release schedule](/doc/releases/3.2/schedule/) +* [Qubes R4.0 release schedule](/doc/releases/4.0/schedule/) diff --git a/developer/releases/todo.md b/developer/releases/todo.md index e9a95399..44b981b7 100644 --- a/developer/releases/todo.md +++ b/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 diff --git a/developer/services/admin-api.md b/developer/services/admin-api.md index 6580f062..cb71855c 100644 --- a/developer/services/admin-api.md +++ b/developer/services/admin-api.md @@ -148,23 +148,22 @@ to set the policy using current mechanism. Volume properties: - - `pool` - - `vid` - - `size` - - `usage` - - `rw` - - `source` - - `save_on_stop` - - `snap_on_start` - - `revisions_to_keep` - - `is_outdated` +- `pool` +- `vid` +- `size` +- `usage` +- `rw` +- `source` +- `save_on_stop` +- `snap_on_start` +- `revisions_to_keep` +- `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 - - `cpu_time` - absolute CPU time (in milliseconds) spent by the VM since its startup, normalized for one CPU - - `cpu_usage` - CPU usage in percents - +- `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_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 diff --git a/developer/services/dom0-secure-updates.md b/developer/services/dom0-secure-updates.md index 805df16c..b7f3af5a 100644 --- a/developer/services/dom0-secure-updates.md +++ b/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 -- Correcting non-security related bugs (e.g. new buttons for qubes manager) -- Adding new features (e.g. GUI backup tool) +- Updating drivers/libs for new hardware support +- Correcting non-security related bugs (e.g. new buttons for qubes manager) +- Adding new features (e.g. GUI backup tool) Problems with traditional network-based update mechanisms --------------------------------------------------------- diff --git a/developer/services/dvm-impl.md b/developer/services/dvm-impl.md index 72139f3e..a95b376e 100644 --- a/developer/services/dvm-impl.md +++ b/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` -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 -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 - 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 - 3. (in APPVM) busy-waiting for `qubes_restore_complete` xenstore key to appear +1. APPVM is started by `qvm-start` +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 +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 + 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 + 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. -7. APPVM private image is detached -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 +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 +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 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 -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. -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`) -6. create the `qubes_restore_complete` xenstore key. This allows the boot process in DisposableVM to continue. +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` +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. +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. The actual passing of files between AppVM and a DisposableVM is implemented via qubes rpc. diff --git a/developer/services/qfilecopy.md b/developer/services/qfilecopy.md index 60c3cb34..3ae45f05 100644 --- a/developer/services/qfilecopy.md +++ b/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 -- 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. +- "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. 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. -- security - VM kernel parses partition table and filesystem metadata from the block device; they are controlled by (potentially untrusted) sender VM. +- 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. 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. diff --git a/developer/services/qfileexchgd.md b/developer/services/qfileexchgd.md index dc6167c3..b56561a7 100644 --- a/developer/services/qfileexchgd.md +++ b/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 a single file between an AppVM and a DisposableVM +- copying files between AppVMs +- 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 a change in `/local/domain/domid/device/qpen` key - VMs write to this key to request service from *qfilexchgd* +- 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* 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. -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. -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. +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. +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. 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. 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, - 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 - 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. +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) + 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` + 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. +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. diff --git a/developer/services/qmemman.md b/developer/services/qmemman.md index f9581adb..2ab06957 100644 --- a/developer/services/qmemman.md +++ b/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 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 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. 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 -- works well in practice, with less than 1% CPU consumption in the idle case -- simple, concise implementation +- provides automatic balancing of memory across participating PV and HVM domains, based on their memory demand +- works well in practice, with less than 1% CPU consumption in the idle case +- simple, concise implementation Cons: -- 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 -- it takes more time to obtain free Xen memory, as all participating domains need to instructed to yield memory +- 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 +- 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 -- 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. +- 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. +- 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 -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` -4. if TOTAL\_MEMORY \< TOTAL\_PREFMEM, then - 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` +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 +3. if TOTAL\_MEMORY \> TOTAL\_PREFMEM, then redistribute TOTAL\_MEMORY across all domains proportionally to their `prefmem` +4. if TOTAL\_MEMORY \< TOTAL\_PREFMEM, then + 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` 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) -- one of the domains is below its `prefmem`, and more than MIN\_MEM\_CHANGE\_WHEN\_UNDER\_PREF (15MB) would be added to it +- 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 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` -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 -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). - +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. +3. shrink donors, proportionally to their `prefmem`, so that X MB should become free +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). Notes ----- diff --git a/developer/services/qrexec-internals.md b/developer/services/qrexec-internals.md index 33b41c47..5c3760a1 100644 --- a/developer/services/qrexec-internals.md +++ b/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-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. +- `domain-id`: Numeric Qubes ID assigned to the associated domain. +- `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. ### 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. -* `-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. -* `-c `: 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. +- `-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. +- `-e`: Optional. If present, stdout/stdin are not connected to the remote peer. Only process creation status code is received. +- `-c `: 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. ## 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. -* `service-name`: Requested service name. -* `local-program`: `local-program` is executed locally and its stdin/stdout are connected to the remote service endpoint. +- `target-domain-name`: Target domain for the service request. Source is the current domain. +- `service-name`: Requested service name. +- `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 */ - struct msg_header { - uint32_t type; /* message type */ - uint32_t len; /* data length */ - }; +```c +/* uniform for all peers, data type depends on message type */ +struct msg_header { + 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 { - uint32_t version; /* qrexec protocol version */ - }; +```c +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. diff --git a/developer/services/qrexec-socket-services.md b/developer/services/qrexec-socket-services.md index e15adc3d..5189fcc9 100644 --- a/developer/services/qrexec-socket-services.md +++ b/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: +``` \0 +``` When running in dom0, it is: +``` \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`). diff --git a/developer/services/qrexec2.md b/developer/services/qrexec2.md index 1f5f3c48..d528d44a 100644 --- a/developer/services/qrexec2.md +++ b/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 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 [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 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/qubes-rpc-multiplexer`: executes the actual service program, +* `/usr/lib/qubes/qrexec-agent`: started by VM bootup scripts, a daemon. +* `/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. diff --git a/developer/system/architecture.md b/developer/system/architecture.md index e66f34fa..f9f33c3f 100644 --- a/developer/system/architecture.md +++ b/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) -- 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) -- No networking code in the privileged domain (dom0) -- All user applications run in “AppVMs,” lightweight VMs based on Linux -- Centralized updates of all AppVMs based on the same template -- Qubes GUI virtualization presents applications as if they were running locally -- Qubes GUI provides isolation between apps sharing the same desktop -- Secure system boot based (optional) +- Based on a secure bare-metal hypervisor (Xen) +- 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) +- No networking code in the privileged domain (dom0) +- All user applications run in “AppVMs,” lightweight VMs based on Linux +- Centralized updates of all AppVMs based on the same template +- Qubes GUI virtualization presents applications as if they were running locally +- Qubes GUI provides isolation between apps sharing the same desktop +- 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 - Qubes services) - - VM-customizations (making the VMs lightweight and working well with seamless - GUI virtualization) - - 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), - - GUI domain customizations (Desktop Environment customizations, decoration - coloring plugin, etc) - - The AdminVM distribution (various customizations, special services, such as - for receiving and verifying updates, in the future: custom distro) - - The Xen hypervisor (with a bunch of customization patches, occasional - hardening) or - in the future - some other virtualising or containerizing - software or technology - - Multiple "Qubes Apps" (various services built on top of Qubes qrexec - infrastructure, such as: trusted PDF and Image converters, Split GPG, safe - USB proxies for HID devices, USB proxy for offering USB devices (exposed via - qvm-usb), Yubikey support, USB Armory support, etc) - - 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 - - Salt Stack integration +- VM-located core agents (implementing e.g. qrexec endpoints used by various + Qubes services) +- VM-customizations (making the VMs lightweight and working well with seamless + GUI virtualization) +- 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), +- GUI domain customizations (Desktop Environment customizations, decoration + coloring plugin, etc) +- The AdminVM distribution (various customizations, special services, such as + for receiving and verifying updates, in the future: custom distro) +- The Xen hypervisor (with a bunch of customization patches, occasional + hardening) or - in the future - some other virtualising or containerizing + software or technology +- Multiple "Qubes Apps" (various services built on top of Qubes qrexec + infrastructure, such as: trusted PDF and Image converters, Split GPG, safe + USB proxies for HID devices, USB proxy for offering USB devices (exposed via + qvm-usb), Yubikey support, USB Armory support, etc) +- 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 +- Salt Stack integration And all these components are "glued together" by the Qubes Core Stack. diff --git a/developer/system/audio.md b/developer/system/audio.md index 05c69bab..6b225931 100644 --- a/developer/system/audio.md +++ b/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) - - `module-vchan-sink` running in a VM (loaded into the PulseAudio process) +- `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) 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. - - `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). - - `0x00020001` -- VM does want to send audio output. +- `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. +- `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. 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) - - object path: `/org/qubesos/audio` - - interface: `org.qubesos.Audio` - - property: `RecAllowed` (which can be set using the `org.freedesktop.DBus.Properties` interface) +- destination: `org.qubesos.Audio.VMNAME` (where `VMNAME` is the VM's name) +- object path: `/org/qubesos/audio` +- interface: `org.qubesos.Audio` +- 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 0\n` - disable audio input +- `audio-input 1\n` - enable 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). - diff --git a/developer/system/gui.md b/developer/system/gui.md index 8e17e827..ae0b24fb 100644 --- a/developer/system/gui.md +++ b/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 -- *qubes_drv* - it provides a virtual keyboard and mouse (in fact, more, see below) +- *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) -For each AppVM, there is a pair of *qubes_gui* (running in AppVM) and *qubes_guid* (running in dom0) processes connected over vchan. +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 -- 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 window size/position change, apply them to the local window +- 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 +- 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 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* -- 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 -- receive information about window size/position change, apply them to the local window +- 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 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 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. @@ -41,30 +41,30 @@ AppVM has no way to get information on keystrokes fed to other AppVMs (e.g. XTES Window content updates implementation ------------------------------------- -Typical remote desktop applications, like *vnc*, pass information on all changed window content in-band (say, over tcp). -As that channel has limited throughput, this impacts video performance. +Typical remote desktop applications, like *vnc*, pass information on all changed window content in-band (say, over tcp). +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 -- passes this information via `MFNDUMP` message to *qubes_guid* in dom0 +- 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 -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. +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. -- *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* -- 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. +- 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 +- 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. -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*). +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 -- no changes to Xorg code -- minimal size of the supporting code +- window updates at DRAM speed +- no changes to Xorg code +- minimal size of the supporting code ![gui.png](/attachment/wiki/GUIdocs/gui.png) @@ -78,14 +78,14 @@ In Qubes, a custom window decorator is used that paints a colourful frame (the c Clipboard sharing implementation -------------------------------- -Certainly, it would be insecure to allow AppVM to read/write the clipboards of other AppVMs unconditionally. +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. -- 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. +- 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. +- 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 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. *qubes_gui* and *qubes_guid* code notes @@ -93,20 +93,20 @@ 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 vchan connecting to the remote party +- messages from the local X server +- 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. If one changes the number/order/signature of messages, one should increase the *QUBES_GUID_PROTOCOL_VERSION* constant in *messages.h* include file. -*qubes_guid* writes debugging information to */var/log/qubes/qubes.domain_id.log* file; *qubes_gui* writes debugging information to */var/log/qubes/gui_agent.log*. +*qubes_guid* writes debugging information to */var/log/qubes/qubes.domain_id.log* file; *qubes_gui* writes debugging information to */var/log/qubes/gui_agent.log*. Include these files when reporting a bug. AppVM -> dom0 messages ----------------------- -Proper handling of the below messages is security-critical. +Proper handling of the below messages is security-critical. Observe that beside two messages (`CLIPBOARD` and `MFNDUMP`) the rest have fixed size, so the parsing code can be small. The *override_redirect* window attribute is explained at [Override Redirect Flag](https://tronche.com/gui/x/xlib/window/attributes/override-redirect.html). The *transient_for* attribute is explained at [Transient_for attribute](https://tronche.com/gui/x/icccm/sec-4.html#WM_TRANSIENT_FOR). @@ -115,8 +115,8 @@ Window manager hints and flags are described in the [Extended Window Manager Hin Each message starts with the following header: -~~~ -struct msghdr { +```c +struct msghdr { uint32_t type; uint32_t window; /* This field is intended for use by gui_agents to skip unknown @@ -126,7 +126,7 @@ struct msghdr { * whatever it wants! */ uint32_t untrusted_len; }; -~~~ +``` This header is followed by message-specific data: @@ -164,9 +164,9 @@ struct msg_create { MSG_MAP 
-struct msg_map_info { 
-  uint32_t transient_for; 
-  uint32_t override_redirect; 
+struct msg_map_info {
+  uint32_t transient_for;
+  uint32_t override_redirect;
 };
Map a window with given parameters @@ -179,12 +179,12 @@ struct msg_map_info { MSG_CONFIGURE 
-struct msg_configure { 
-  uint32_t x; 
-  uint32_t y; 
-  uint32_t width; 
-  uint32_t height; 
-  uint32_t override_redirect; 
+struct msg_configure {
+  uint32_t x;
+  uint32_t y;
+  uint32_t width;
+  uint32_t height;
+  uint32_t override_redirect;
 };
Change window position/size/type @@ -192,15 +192,15 @@ struct msg_configure { MSG_MFNDUMP 
-struct shm_cmd { 
-  uint32_t shmid; 
-  uint32_t width; 
-  uint32_t height; 
-  uint32_t bpp; 
-  uint32_t off; 
-  uint32_t num_mfn; 
-  uint32_t domid; 
-  uint32_t mfns[0]; 
+struct shm_cmd {
+  uint32_t shmid;
+  uint32_t width;
+  uint32_t height;
+  uint32_t bpp;
+  uint32_t off;
+  uint32_t num_mfn;
+  uint32_t domid;
+  uint32_t mfns[0];
 };
Retrieve the array of mfns that constitute the composition buffer of a remote window. @@ -211,8 +211,8 @@ struct shm_cmd { MSG_SHMIMAGE 
-struct msg_shmimage { 
-     uint32_t x; 
+struct msg_shmimage {
+     uint32_t x;
      uint32_t y;
      uint32_t width;
      uint32_t height;
@@ -223,8 +223,8 @@ struct msg_shmimage {
 
   MSG_WMNAME
   
-struct msg_wmname { 
-  char data[128]; 
+struct msg_wmname {
+  char data[128];
 };
 

  Set the window name; only printable characters are allowed
@@ -237,16 +237,16 @@ struct msg_wmname {
 
   MSG_WINDOW_HINTS
   
-struct msg_window_hints { 
-     uint32_t flags; 
-     uint32_t min_width; 
-     uint32_t min_height; 
-     uint32_t max_width; 
-     uint32_t max_height; 
-     uint32_t width_inc; 
-     uint32_t height_inc; 
-     uint32_t base_width; 
-     uint32_t base_height; 
+struct msg_window_hints {
+     uint32_t flags;
+     uint32_t min_width;
+     uint32_t min_height;
+     uint32_t max_width;
+     uint32_t max_height;
+     uint32_t width_inc;
+     uint32_t height_inc;
+     uint32_t base_width;
+     uint32_t base_height;
 };
 
 
  Size hints for window manager
@@ -254,7 +254,7 @@ struct msg_window_hints {
 
   MSG_WINDOW_FLAGS
   
-struct msg_window_flags { 
+struct msg_window_flags {
      uint32_t flags_set;
      uint32_t flags_unset;
 };
@@ -279,12 +279,12 @@ Proper handling of the below messages is NOT security-critical.
 
 Each message starts with the following header
 
-~~~
-struct msghdr {   
+```c
+struct msghdr {
         uint32_t type;
         uint32_t window;
 };
-~~~
+```
 
 The header is followed by message-specific data:
 
@@ -297,12 +297,12 @@ The header is followed by message-specific data:
 
   MSG_KEYPRESS
   
-struct msg_keypress {  
-  uint32_t type;  
-  uint32_t x;  
-  uint32_t y;  
-  uint32_t state;  
-  uint32_t keycode;  
+struct msg_keypress {
+  uint32_t type;
+  uint32_t x;
+  uint32_t y;
+  uint32_t state;
+  uint32_t keycode;
 };
 
 
  Tell *qubes_drv* driver to generate a keypress
@@ -310,12 +310,12 @@ struct msg_keypress {
 
   MSG_BUTTON
   
-struct msg_button {  
-  uint32_t type;  
-  uint32_t x;  
-  uint32_t y;  
-  uint32_t state;  
-  uint32_t button;  
+struct msg_button {
+  uint32_t type;
+  uint32_t x;
+  uint32_t y;
+  uint32_t state;
+  uint32_t button;
 };
 
 
  Tell *qubes_drv* driver to generate mouseclick
@@ -323,11 +323,11 @@ struct msg_button {
 
   MSG_MOTION
   
-struct msg_motion {  
-  uint32_t x;  
-  uint32_t y;  
-  uint32_t state;  
-  uint32_t is_hint;  
+struct msg_motion {
+  uint32_t x;
+  uint32_t y;
+  uint32_t state;
+  uint32_t is_hint;
 };
 
 
  Tell *qubes_drv* driver to generate motion event
@@ -335,12 +335,12 @@ struct msg_motion {
 
   MSG_CONFIGURE
   
-struct msg_configure { 
-  uint32_t x; 
-  uint32_t y; 
-  uint32_t width; 
-  uint32_t height; 
-  uint32_t override_redirect; 
+struct msg_configure {
+  uint32_t x;
+  uint32_t y;
+  uint32_t width;
+  uint32_t height;
+  uint32_t override_redirect;
 };
 
 
  Change window position/size/type
@@ -348,9 +348,9 @@ struct msg_configure {
 
   MSG_MAP
   
-struct msg_map_info { 
-  uint32_t transient_for; 
-  uint32_t override_redirect; 
+struct msg_map_info {
+  uint32_t transient_for;
+  uint32_t override_redirect;
 };
 
 
  Map a window with given parameters
@@ -363,14 +363,14 @@ struct msg_map_info {
 
   MSG_CROSSING
   
-struct msg_crossing { 
-  uint32_t type; 
-  uint32_t x; 
-  uint32_t y; 
-  uint32_t state; 
-  uint32_t mode; 
-  uint32_t detail; 
-  uint32_t focus; 
+struct msg_crossing {
+  uint32_t type;
+  uint32_t x;
+  uint32_t y;
+  uint32_t state;
+  uint32_t mode;
+  uint32_t detail;
+  uint32_t focus;
 };
 
 
  Notify window about enter/leave event
@@ -378,10 +378,10 @@ struct msg_crossing {
 
   MSG_FOCUS
   
-struct msg_focus {  
-  uint32_t type;  
-  uint32_t mode;  
-  uint32_t detail;  
+struct msg_focus {
+  uint32_t type;
+  uint32_t mode;
+  uint32_t detail;
 };
 
 
  Raise a window, XSetInputFocus
@@ -409,8 +409,8 @@ struct msg_focus {
 
   MSG_WINDOW_FLAGS
   
-struct msg_window_flags { 
-      uint32_t flags_set; 
+struct msg_window_flags {
+      uint32_t flags_set;
      uint32_t flags_unset;
 };
 
 
diff --git a/developer/system/networking.md b/developer/system/networking.md
index cde78ade..452cd9fd 100644
--- a/developer/system/networking.md
+++ b/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.
-
diff --git a/developer/system/security-critical-code.md b/developer/system/security-critical-code.md
index 9c6ccab6..8e23be7d 100644
--- a/developer/system/security-critical-code.md
+++ b/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 GUI virtualization code (`qubes-guid`)
- - Dom0-side of the sound virtualization code (`pacat-simple-vchan`)
- - Dom0-side in qrexec-related code (`qrexec_daemon`)
- - VM memory manager (`qmemman`) that runs in Dom0
- - 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)
-
+- Dom0-side of the libvchan library
+- Dom0-side of the GUI virtualization code (`qubes-guid`)
+- Dom0-side of the sound virtualization code (`pacat-simple-vchan`)
+- Dom0-side in qrexec-related code (`qrexec_daemon`)
+- VM memory manager (`qmemman`) that runs in Dom0
+- 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)
 
 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
- - Xen's xenstore backend running in Dom0
- - Xen's block backend running in Dom0's kernel
- - The RPM program used in Dom0 for verifying signatures on dom0 updates
- - Somewhat trusted: log viewing software in dom0 that parses VM-influenced logs
-
+- The Xen hypervisor
+- Xen's xenstore backend running in Dom0
+- Xen's block backend running in Dom0's kernel
+- The RPM program used in Dom0 for verifying signatures on dom0 updates
+- 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
- - VMs' core networking stacks (core TCP/IP code)
+- Xen network PV frontends
+- 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/
-
diff --git a/developer/system/storage-pools.md b/developer/system/storage-pools.md
index 8886f406..56f5a44b 100644
--- a/developer/system/storage-pools.md
+++ b/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.
@@ -50,4 +49,4 @@ argument to `qvm-create` to have the VM images stored in pool `foo`. See also
 `qvm-create --help`.
 
 While the current API is not as clean and beautiful as the R4 API, it allows
-you to write your own storage drivers e.g. for Btrfs today. 
+you to write your own storage drivers e.g. for Btrfs today.
diff --git a/developer/system/template-implementation.md b/developer/system/template-implementation.md
index 0f320910..24b7b5d3 100644
--- a/developer/system/template-implementation.md
+++ b/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
--   **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)
--   **xvdd** – modules.img – kernel modules and firmware
+- **xvda** – base root device (/) – details described below
+- **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)
+- **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
--   */usr/local* – which is symlink to /rw/usrlocal
--   some config files (/rw/config) called by qubes core scripts (ex /rw/config/rc.local)
+- */home* – which is bind mounted to /rw/home
+- */usr/local* – which is symlink to /rw/usrlocal
+- some config files (/rw/config) called by qubes core scripts (ex /rw/config/rc.local)
 
 **Note:** Whenever a TemplateBasedVM is created, the contents of the `/home` directory of its parent TemplateVM are 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
--   *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)
+- *vmlinuz* – actual kernel
+- *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)
 
 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
--   multiple AppVMs that are using different versions of root.img (from various points in time) can be running concurrently
+- 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
 
 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-cow.img – differences between the device as seen by AppVM and the current root.img
+- root.img – real template filesystem
+- 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.
-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).
-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*.
-6.  Cleanup snapshot device (if nobody uses it at the moment).
-7.  Move *root-cow.img.old* to *root-cow.img* (overriding existing file).
+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*).
+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.
+5. Replace *snapshot-merge* d-m target back to *snapshot*.
+6. Cleanup snapshot device (if nobody uses it at the moment).
+7. Move *root-cow.img.old* to *root-cow.img* (overriding existing file).
 
-Snapshot device in AppVM
-------------------------
+## Snapshot device in AppVM
 
 Root device is exposed to AppVM in read-only mode. AppVM can write only in:
 
--   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
+- 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 is divided into two partitions:
 
-1.  changes to root device
-2.  swap partition
+1. changes to root device
+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*.
 
diff --git a/introduction/contributing.md b/introduction/contributing.md
index 9326f797..f88873e3 100644
--- a/introduction/contributing.md
+++ b/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/
-
diff --git a/introduction/faq.md b/introduction/faq.md
index f7369860..98a6ab1e 100644
--- a/introduction/faq.md
+++ b/introduction/faq.md
@@ -20,7 +20,7 @@ redirect_from:
 ### What is Qubes OS?
 
 Qubes OS is a security-oriented operating system (OS).
-The OS is the software that runs all the other programs on a computer. 
+The OS is the software that runs all the other programs on a computer.
 Some examples of popular OSes are Microsoft Windows, Mac OS X, Android, and iOS.
 Qubes is free and open-source software (FOSS).
 This means that everyone is free to use, copy, and change the software in any way.
@@ -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,30 +129,29 @@ Briefly, here are some of the main pros and cons of this approach relative to Qu
    Pros
 
 
- * 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.
-	(For example, you might find it natural to lock your secure laptop in a safe when you take your unsecure laptop out with you.)
+- 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.
+  (For example, you might find it natural to lock your secure laptop in a safe when you take your unsecure laptop out with you.)
 
 

      Cons
 

 
- * 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.
-	(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.
- * Malware which can bridge air gaps has existed for several years now and is becoming increasingly common.
+- 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.
+  (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.
+- 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.
 
 ### What about other approaches to security?
 
-The other two popular [approaches] are “Security by Correctness” and “Security by Obscurity.” 
+The other two popular [approaches] are “Security by Correctness” and “Security by Obscurity.”
 We don't believe either of these approaches are capable of providing reasonable security today, nor do we believe that they will be capable of doing so in the foreseeable future.
 
 ### How is Qubes different from other security solutions?
@@ -163,8 +160,8 @@ Please see this [article] for a thorough discussion.
 
 ### Is Qubes just another Linux distribution?
 
-If you really want to call it a distribution, then it's more of a "Xen distribution" than a Linux one. 
-But Qubes is much more than just Xen packaging. 
+If you really want to call it a distribution, then it's more of a "Xen distribution" than a Linux one.
+But Qubes is much more than just Xen packaging.
 It has its own VM management infrastructure, with support for template VMs, centralized VM updating, etc.
 It also has a very unique GUI virtualization infrastructure.
 
@@ -179,9 +176,9 @@ We believe that this is currently the only practically viable approach to implem
 
 ### Does Qubes use full disk encryption (FDE)?
 
-Yes, of course! 
-Full disk encryption is enabled by default. 
-Specifically, we use [LUKS]/[dm-crypt]. 
+Yes, of course!
+Full disk encryption is enabled by default.
+Specifically, we use [LUKS]/[dm-crypt].
 You can even [manually configure your encryption parameters][custom_config] if you like!
 
 ### What do all these terms mean?
@@ -191,13 +188,13 @@ All Qubes-specific terms are defined in the [glossary]
 ### Does Qubes run every app in a separate VM?
 
 No! This would not make much sense.
-Qubes uses lightweight VMs to create security qubes (e.g., "work," "personal," and "banking,"). 
+Qubes uses lightweight VMs to create security qubes (e.g., "work," "personal," and "banking,").
 A typical user would likely need around five qubes.
 Very paranoid users, or those who are high-profile targets, might use a dozen or more qubes.
 
 ### Why does Qubes use Xen instead of KVM or some other hypervisor?
 
-In short: we believe the Xen architecture allows for the creation of more secure systems (i.e. with a much smaller TCB, which translates to a smaller attack surface). 
+In short: we believe the Xen architecture allows for the creation of more secure systems (i.e. with a much smaller TCB, which translates to a smaller attack surface).
 We discuss this in much greater depth in our [Architecture Specification document].
 
 ### How is Qubes affected by Xen Security Advisories (XSAs)?
@@ -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)?
-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?
-4.  Does it support VT-d, and does it allow for the creation of untrusted driver domains?
-5.  Does it support S3 sleep?
-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.)
-8.  Other special features? E.g. eliminates cooperative covert channels between VMs?
+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)?
+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?
+5. Does it support S3 sleep?
+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.)
+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).
-2.  Runs unmodified usermode apps (binaries).
-3.  Runs unmodified Linux drivers (dom0 and driver domains). PV VMs require special written pvdrivers.
-4.  Full VT-d support including untrusted driver domains.
-5.  S3 sleep supported well.
-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.
-8.  Mostly WorksTM :)
+1. PV and HVM Virtual Machines (ring0/3 for PV domains, VT-x/AMD-v for HVMs).
+2. Runs unmodified usermode apps (binaries).
+3. Runs unmodified Linux drivers (dom0 and driver domains). PV VMs require special written pvdrivers.
+4. Full VT-d support including untrusted driver domains.
+5. S3 sleep supported well.
+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.
+8. Mostly WorksTM :)
 
 ### Which virtualization modes do VMs use?
 
@@ -242,8 +239,8 @@ Stub domains - HVMs                        | PV   |
 
 ### What's so special about Qubes' GUI virtualization?
 
-We have designed the GUI virtualization subsystem with two primary goals: security and performance. 
-Our GUI infrastructure introduces only about 2,500 lines of C code (LOC) into the privileged domain (Dom0), which is very little, and thus leaves little space for bugs and potential attacks. 
+We have designed the GUI virtualization subsystem with two primary goals: security and performance.
+Our GUI infrastructure introduces only about 2,500 lines of C code (LOC) into the privileged domain (Dom0), which is very little, and thus leaves little space for bugs and potential attacks.
 At the same time, due to the smart use of Xen shared memory, our GUI implementation is very efficient, so most virtualized applications really feel as if they were executed natively.
 
 ### Why passwordless sudo?
@@ -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]
 
@@ -283,13 +281,13 @@ We've gone to special effort to set all of this up so that no one has to trust t
 
 ### What does it mean to "distrust the infrastructure"?
 
-A core tenet of the Qubes philosophy is "distrust the infrastructure," where "the infrastructure" refers to things like hosting providers, CDNs, DNS services, package repositories, email servers, PGP keyservers, etc. 
+A core tenet of the Qubes philosophy is "distrust the infrastructure," where "the infrastructure" refers to things like hosting providers, CDNs, DNS services, package repositories, email servers, PGP keyservers, etc.
 As a project, we focus on securing endpoints instead of attempting to secure "the middle" (i.e., the infrastructure), since one of our primary goals is to free users from being forced to entrust their security to unknown third parties.
 Instead, our aim is for users to be required to trust as few entities as possible (ideally, only themselves and any known persons whom they voluntarily decide to trust).
 
-Users can never fully control all the infrastructure they rely upon, and they can never fully trust all the entities who do control it. 
-Therefore, we believe the best solution is not to attempt to make the infrastructure trustworthy, but instead to concentrate on solutions that obviate the need to do so. 
-We believe that many attempts to make the infrastructure appear trustworthy actually provide only the illusion of security and are ultimately a disservice to real users. 
+Users can never fully control all the infrastructure they rely upon, and they can never fully trust all the entities who do control it.
+Therefore, we believe the best solution is not to attempt to make the infrastructure trustworthy, but instead to concentrate on solutions that obviate the need to do so.
+We believe that many attempts to make the infrastructure appear trustworthy actually provide only the illusion of security and are ultimately a disservice to real users.
 Since we don't want to encourage or endorse this, we make our distrust of the infrastructure explicit.
 
 Also see: [Should I trust this website?]
@@ -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?
@@ -324,29 +321,28 @@ Absolutely.
 
 ### Can I run applications, like games, which require hardware acceleration?
 
-Those won’t fly. 
-We do not provide GPU virtualization for Qubes. 
-This is mostly a security decision, as implementing such a feature would most likely introduce a great deal of complexity into the GUI virtualization infrastructure. 
+Those won’t fly.
+We do not provide GPU virtualization for Qubes.
+This is mostly a security decision, as implementing such a feature would most likely introduce a great deal of complexity into the GUI virtualization infrastructure.
 However, Qubes does allow for the use of accelerated graphics (e.g. OpenGL) in dom0’s Window Manager, so all the fancy desktop effects should still work.
 AppVMs use a software-only (CPU-based) implementation of OpenGL, which may be good enough for basic games and applications.
 
 For further discussion about the potential for GPU passthrough on Xen/Qubes, please see the following threads:
 
--   [GPU passing to HVM]
--   [Clarifications on GPU security]
+- [GPU passing to HVM]
+- [Clarifications on GPU security]
 
 ### Is Qubes a multi-user system?
 
-No. 
-Qubes does not pretend to be a multi-user system. 
-Qubes assumes that the user who controls Dom0 controls the whole system. 
-It is very difficult to **securely** implement multi-user support. 
+No.
+Qubes does not pretend to be a multi-user system.
+Qubes assumes that the user who controls Dom0 controls the whole system.
+It is very difficult to **securely** implement multi-user support.
 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].
@@ -361,9 +357,9 @@ See [Certified Hardware].
 
 ### How much disk space does each qube require?
 
-Each qube is created from a TemplateVM and shares the root filesystem with this TemplateVM (in a read-only manner). 
-This means that each qube needs only as much disk space as is necessary to store its own private data. 
-This also means that it is possible to update the software for several qubes simultaneously by running a single update process in the TemplateVM upon which those qubes are based. 
+Each qube is created from a TemplateVM and shares the root filesystem with this TemplateVM (in a read-only manner).
+This means that each qube needs only as much disk space as is necessary to store its own private data.
+This also means that it is possible to update the software for several qubes simultaneously by running a single update process in the TemplateVM upon which those qubes are based.
 (These qubes will then have to be restarted in order for the update to take effect in them.)
 
 ### How much memory is recommended for Qubes?
@@ -374,7 +370,7 @@ Please see the [system requirements].
 
 Please see the [system requirements] for the latest information.
 If you are receiving an error message on install saying your "hardware lacks the features required to proceed", check to make sure the virtualization options are enabled in your BIOS/UEFI configuration.
-You may be able to install without the required CPU features for testing purposes only, but VMs (in particular, sys-net) may not function correctly and there will be no security isolation. 
+You may be able to install without the required CPU features for testing purposes only, but VMs (in particular, sys-net) may not function correctly and there will be no security isolation.
 For more information, see [Qubes-certified hardware](/doc/certified-hardware/).
 
 ### Why is VT-x/AMD-V important?
@@ -385,24 +381,24 @@ In addition, if your system lacks VT-x/AMD-V, then it also lacks VT-d/ADM-Vi/AMD
 (See next question.)
 
 ### Why is VT-d/ADM-Vi/AMD IOMMU important?
- 
-On a system without VT-d/ADM-Vi/AMD IOMMU, there will be no real security benefit to having a separate NetVM, as an attacker could always use a simple [DMA attack](#what-is-a-dma-attack) to go from the NetVM to Dom0. 
-Nonetheless, all of Qubes' other security mechanisms, such as qube separation, work without VT-d/ADM-Vi/AMD IOMMU. 
+
+On a system without VT-d/ADM-Vi/AMD IOMMU, there will be no real security benefit to having a separate NetVM, as an attacker could always use a simple [DMA attack](#what-is-a-dma-attack) to go from the NetVM to Dom0.
+Nonetheless, all of Qubes' other security mechanisms, such as qube separation, work without VT-d/ADM-Vi/AMD IOMMU.
 Therefore, a system running Qubes without VT-d/ADM-Vi/AMD IOMMU would still be significantly more secure than one running Windows, Mac, or Linux.
 
 ### What is a DMA attack?
 
 Direct Memory Access (DMA) is mechanism for PCI devices to access system memory (read/write).
-Without VT-d/ADM-Vi/AMD IOMMU, any PCI device can access all the memory, regardless of the VM to which it is assigned (or if it is left in dom0). 
-Most PCI devices allow the driver to request an arbitrary DMA operation (like "put received network packets at this address in memory", or "get this memory area and send it to the network"). 
-So, without VT-d/ADM-Vi/AMD IOMMU, it gives unlimited access to the whole system. 
-Now, it is only a matter of knowing where to read/write to take over the system, instead of just crashing. 
+Without VT-d/ADM-Vi/AMD IOMMU, any PCI device can access all the memory, regardless of the VM to which it is assigned (or if it is left in dom0).
+Most PCI devices allow the driver to request an arbitrary DMA operation (like "put received network packets at this address in memory", or "get this memory area and send it to the network").
+So, without VT-d/ADM-Vi/AMD IOMMU, it gives unlimited access to the whole system.
+Now, it is only a matter of knowing where to read/write to take over the system, instead of just crashing.
 But since you can read the whole memory, it isn't that hard.
 
-Now, how does this apply to Qubes OS? 
-The above attack requires access to a PCI device, which means that it can be performed only from the NetVM or USB VM, so someone must first break into one of those VMs. 
-But this isn't that hard, because there is a lot of complex code handling network traffic. 
-There is a history of bugs in DHCP clients, DNS clients, etc. 
+Now, how does this apply to Qubes OS?
+The above attack requires access to a PCI device, which means that it can be performed only from the NetVM or USB VM, so someone must first break into one of those VMs.
+But this isn't that hard, because there is a lot of complex code handling network traffic.
+There is a history of bugs in DHCP clients, DNS clients, etc.
 Most attacks on the NetVM and USB VM (but not all of them!) require being somewhat close to the target system, for example, being connected to the same Wi-Fi network, or in the case of a USB VM, having physical access to a USB port.
 
 ### Can I use AMD-v instead of VT-x?
@@ -433,11 +429,10 @@ You have to restart the NetVM after the TemplateVM has been shut down.
 
 ### Can I install Qubes OS together with other operating system (dual-boot/multi-boot)?
 
-You shouldn't do that, because it poses a security risk for your Qubes OS installation. 
+You shouldn't do that, because it poses a security risk for your Qubes OS installation.
 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].
@@ -464,31 +459,33 @@ Enable "debug mode" in the qube's settings, either by checking the box labeled "
 
 ### I created a usbVM and assigned usb controllers to it. Now the usbVM wont boot.
 
-This is probably because one of the controllers does not support reset. 
-See the [USB Troubleshooting guide](/doc/usb-troubleshooting/#usbvm-does-not-boot-after-creating-and-assigning-usb-controllers-to-it). 
+This is probably because one of the controllers does not support reset.
+See the [USB Troubleshooting guide](/doc/usb-troubleshooting/#usbvm-does-not-boot-after-creating-and-assigning-usb-controllers-to-it).
 
 ### I assigned a PCI device to a qube, then unassigned it/shut down the qube. Why isn't the device available in dom0?
 
-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. 
+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 `` 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 `` with your device, for example `00:1c.2`:
 
-        echo 0000: > /sys/bus/pci/drivers/pciback/unbind
-        MODALIAS=`cat /sys/bus/pci/devices/0000:/modalias`
-        MOD=`modprobe -R $MODALIAS | head -n 1`
-        echo 0000: > /sys/bus/pci/drivers/$MOD/bind
+    ```
+    echo 0000: > /sys/bus/pci/drivers/pciback/unbind
+    MODALIAS=`cat /sys/bus/pci/devices/0000:/modalias`
+    MOD=`modprobe -R $MODALIAS | head -n 1`
+    echo 0000: > /sys/bus/pci/drivers/$MOD/bind
+    ```
 
 See also [here][assign_devices].
 
 ### How do I install Flash in a Debian qube?
 
-The Debian way is to install the flashplugin-nonfree package. 
+The Debian way is to install the flashplugin-nonfree package.
 Download this in a qubes, and copy it to a Debian template.
 This will make Flash available to every qube using that template.
 
@@ -501,16 +498,18 @@ If you only want Flash available in one qube:
 
 ### How do I play video files?
 
-If you're having trouble playing a video file in a qube, you're probably missing the required codecs. 
-The easiest way to resolve this is to install VLC Media Player and use that to play your video files. 
-You can do this in multiple different TemplateVM distros (Fedora, Debian, etc.). 
+If you're having trouble playing a video file in a qube, you're probably missing the required codecs.
+The easiest way to resolve this is to install VLC Media Player and use that to play your video files.
+You can do this in multiple different TemplateVM distros (Fedora, Debian, etc.).
 
 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.
 
@@ -528,23 +529,23 @@ For Fedora:
 
 The recommended approach is to pass only the specific partition you intend to use from [`sys-usb`](/doc/usb/) to another qube via `qvm-block`.
 They will show up in the destination qube as `/dev/xvd*` and must be mounted manually.
-Another approach is to attach the entire USB drive to your destination qube. 
-However, this could theoretically lead to an attack because it forces the destination qube to parse the device's partition table. 
+Another approach is to attach the entire USB drive to your destination qube.
+However, this could theoretically lead to an attack because it forces the destination qube to parse the device's partition table.
 If you believe your device is safe, you may proceed to attach it.
 
-In Qubes 4.0, this is accomplished with the Devices Widget located in the tool tray (default top right corner, look for an icon with a yellow square). 
-From the top part of the list, click on the drive you want to attach, then select the qube to attach it to. 
+In Qubes 4.0, this is accomplished with the Devices Widget located in the tool tray (default top right corner, look for an icon with a yellow square).
+From the top part of the list, click on the drive you want to attach, then select the qube to attach it to.
 Although you can also attach the entire USB device to a qube by selecting it from the bottom part of the list, in general this approach should not be used because you are exposing the target qube to unnecessary additional attack surface.
 
-Although external media such as external hard drives or flash drives plugged in via USB are available in the USB qube, it is not recommended to access them directly from inside the USB qube. 
+Although external media such as external hard drives or flash drives plugged in via USB are available in the USB qube, it is not recommended to access them directly from inside the USB qube.
 See [Block (Storage) Devices][storage](/doc/block-devices/) for more information.
 
 ### My encrypted drive doesn't appear in Debian qube.
 
-This is an issue that affects qubes based on Debian Jessie. 
+This is an issue that affects qubes based on Debian Jessie.
 The problem is fixed in Stretch, and does not affect Fedora-based qubes.
 
-A mixed drive with some encrypted partitions appears correctly in Nautilus. 
+A mixed drive with some encrypted partitions appears correctly in Nautilus.
 The encrypted partitions are identified and the user is prompted for password on attempting to mount the partition.
 
 A fully encrypted drive does not appear in Nautilus.
@@ -564,7 +565,7 @@ The decrypted device is now available at `/mnt` - when you have finished using i
 
 ### Windows Update is stuck.
 
-This has nothing to do with Qubes. 
+This has nothing to do with Qubes.
 [It's a longstanding Windows bug.](https://superuser.com/questions/951960/windows-7-sp1-windows-update-stuck-checking-for-updates)
 
 ### Fullscreen Firefox is frozen.
@@ -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  kernel ""
+```
+qvm-prefs  kernel ""
+```
 
 ### When I try to install a TemplateVM, it says no match is found.
 
@@ -603,13 +606,14 @@ 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?
 
-During boot, Qubes starts several virtual machines. 
-Having so many qubes running at once inevitably strains the resources of your computer and causes slowness. 
-The most effective way to speed up Qubes is to get more powerful hardware -- a fast CPU, a lot of memory and fast SSDs. 
+During boot, Qubes starts several virtual machines.
+Having so many qubes running at once inevitably strains the resources of your computer and causes slowness.
+The most effective way to speed up Qubes is to get more powerful hardware -- a fast CPU, a lot of memory and fast SSDs.
 Qubes is slower when reading from the disk because of the VM overhead, which is why we recommend installing it on a fast SSD.
 
 ### Could you please make my preference the default?
@@ -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,21 +634,21 @@ 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 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 must be built from source, the source code and any builders must be signed.
+- 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 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.
    (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?
 
 Since 2013 [Xen has not supported 32-bit x86 architecture](https://wiki.xenproject.org/wiki/Xen_Project_Release_Features) and Intel VT-d, which Qubes uses to isolate devices and drivers, is available on Intel 64-bit processors only.
 
-In addition, with features like improved ASLR, it is often more difficult to exploit a bug on x64 Linux than x86 Linux. 
-While we designed Qubes from the beginning to limit potential attack vectors, we still realize that some of the code running in Dom0, e.g. our GUI daemon or xen-store daemon, however simple, might contain some bugs. 
-Plus since we haven't implemented a separate storage domain, the disk backends are in Dom0 and are "reachable" from the VMs, which adds up to the potential attack surface. 
-So, having faced a choice between 32-bit and 64-bit OS for Dom0, it was almost a no-brainer. 
-The 64-bit option provides some (little perhaps, but some) more protection against some classes of attacks, and at the same time does not have any disadvantages except the extra requirement of a 64 bit processor. 
+In addition, with features like improved ASLR, it is often more difficult to exploit a bug on x64 Linux than x86 Linux.
+While we designed Qubes from the beginning to limit potential attack vectors, we still realize that some of the code running in Dom0, e.g. our GUI daemon or xen-store daemon, however simple, might contain some bugs.
+Plus since we haven't implemented a separate storage domain, the disk backends are in Dom0 and are "reachable" from the VMs, which adds up to the potential attack surface.
+So, having faced a choice between 32-bit and 64-bit OS for Dom0, it was almost a no-brainer.
+The 64-bit option provides some (little perhaps, but some) more protection against some classes of attacks, and at the same time does not have any disadvantages except the extra requirement of a 64 bit processor.
 And even though Qubes now "needs" a 64 bit processor, it didn't make sense to run Qubes on a system without 3-4GB of memory, and those have 64-bit CPUs anyway.
 
 ### What is the recommended build environment for Qubes OS?
@@ -662,23 +665,23 @@ See the [Qubes Source Code Repositories](/doc/source-code/) article.
 
 ### What is Qubes' attitude toward changing guest distros?
 
-We try to respect each distro's culture, where possible. 
+We try to respect each distro's culture, where possible.
 See the discussion on issue [#1014](https://github.com/QubesOS/qubes-issues/issues/1014) for an example.
 
 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.
- * We're less likely to introduce Qubes-specific issues.
- * Each officially supported distribution (ideally) should offer the same set of
+- The upstream documentation matches the distribution running in the Qubes VM.
+- We're less likely to introduce Qubes-specific issues.
+- 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.
 
 ### Is the I/O emulation component (QEMU) part of the Trusted Computing Base (TCB)?
 
-No. Unlike many other virtualization systems, Qubes takes special effort to keep QEMU _outside_ of the TCB. 
-This has been achieved thanks to the careful use of Xen's stub domain feature. 
+No. Unlike many other virtualization systems, Qubes takes special effort to keep QEMU _outside_ of the TCB.
+This has been achieved thanks to the careful use of Xen's stub domain feature.
 For more details about how we improved on Xen's native stub domain use, see [here](https://blog.invisiblethings.org/2012/03/03/windows-support-coming-to-qubes.html).
 
 [force_usb2]: https://www.systutorials.com/qa/1908/how-to-force-a-usb-3-0-port-to-work-in-usb-2-0-mode-in-linux
@@ -703,7 +706,7 @@ Yes, Qubes natively supports automation via [Salt (SaltStack)][Salt].
 There is also the unofficial [ansible-qubes toolkit][ansible].
 (**Warning:** Since this is an external project that has not been reviewed or endorsed by the Qubes team, [allowing it to manage dom0 may be a security risk](https://github.com/Qubes-Community/Contents/blob/master/docs/security/security-guidelines.md#dom0-precautions).)
 
-[4.x System Requirements]: /doc/system-requirements/#qubes-release-4x 
+[4.x System Requirements]: /doc/system-requirements/#qubes-release-4x
 [Admin API]: /news/2017/06/27/qubes-admin-api/
 [ansible]: https://github.com/Rudd-O/ansible-qubes
 [Anti Evil Maid]: /doc/anti-evil-maid/
@@ -716,9 +719,9 @@ There is also the unofficial [ansible-qubes toolkit][ansible].
 [clipboard]: /doc/copy-paste
 [command-line interface]: https://en.wikipedia.org/wiki/Command-line_interface
 [commands]: https://en.wikipedia.org/wiki/Command_(computing)
-[coreboot]: https://www.coreboot.org/ 
+[coreboot]: https://www.coreboot.org/
 [Core Stack]: /news/2017/10/03/core3/
-[custom_config]: /doc/custom-install/ 
+[custom_config]: /doc/custom-install/
 [Debian is not certified]: https://www.gnu.org/distros/common-distros.en.html
 [disposable]: /doc/disposablevm/
 [disposable qube]: /doc/dispvm/
@@ -726,7 +729,7 @@ There is also the unofficial [ansible-qubes toolkit][ansible].
 [dm-crypt]: https://en.wikipedia.org/wiki/Dm-crypt
 [doc-signing keys]: https://github.com/QubesOS/qubes-secpack/tree/master/keys/doc-signing
 [documentation guidelines]: /doc/doc-guidelines
-[documentation on multibooting]: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/multiboot.md 
+[documentation on multibooting]: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/multiboot.md
 [Enable RPMFusion]: /doc/software-update-domu/#rpmfusion-for-fedora-templatevms
 [file]: /doc/copying-files
 [firewalls]: /doc/firewall
@@ -753,7 +756,7 @@ There is also the unofficial [ansible-qubes toolkit][ansible].
 [storage]: /doc/block-devices/
 [system requirements]: /doc/system-requirements/
 [Tails]: https://tails.boum.org/
-[Template]: /doc/template-implementation 
+[Template]: /doc/template-implementation
 [terminal emulator]: https://en.wikipedia.org/wiki/Terminal_emulator
 [this message]: https://groups.google.com/group/qubes-devel/msg/6412170cfbcb4cc5
 [this page]: /doc/vm-sudo/
diff --git a/introduction/intro.html b/introduction/intro.html
index d7e1931b..54e9d00c 100644
--- a/introduction/intro.html
+++ b/introduction/intro.html
@@ -11,6 +11,7 @@ redirect_from:
 ---
 
 
What is Qubes OS?

+
 
 

   

@@ -159,6 +160,7 @@ redirect_from:
 
 
 
Why Qubes OS?

+
 
 
Physical isolation is a given safeguard that the digital world lacks

 
@@ -336,4 +338,3 @@ redirect_from:
     
   
 

-
diff --git a/introduction/reporting-bugs.md b/introduction/reporting-bugs.md
index a8e02692..43da5363 100644
--- a/introduction/reporting-bugs.md
+++ b/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
-
diff --git a/introduction/statistics.md b/introduction/statistics.md
index 85f90911..4db738ea 100644
--- a/introduction/statistics.md
+++ b/introduction/statistics.md
@@ -2,7 +2,7 @@
 layout: default
 title: Statistics
 permalink: /statistics/
-redirect_from: 
+redirect_from:
 - /counter/
 ---
 
@@ -12,8 +12,7 @@ redirect_from:
   
 

 
-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.
- - `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.
+
+- `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.
+- `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 number of requests from each IPv4 address
- - Standard server access and error logs
+- The IPv4 addresses that connect to the Qubes update servers
+- The number of requests from each IPv4 address
+- 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
-
diff --git a/introduction/support.md b/introduction/support.md
index ad5eb8b8..027826b2 100644
--- a/introduction/support.md
+++ b/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
- * Installation problems
- * Hardware compatibility problems
- * Questions of the form: "How do I...?"
+* [HCL] reports
+* Installation problems
+* Hardware compatibility problems
+* 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
-   related to installing Qubes OS)
- * The [User FAQ]
- * The [documentation] (for questions about how to use Qubes OS)
+* The [Installation Guide], [System Requirements], and [HCL] (for problems
+  related to installing Qubes OS)
+* The [User FAQ]
+* 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.
-   * 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.
- * Discussions about proposed new features, patches, etc.
-   * For example: "I would like to implement feature XYZ."
- * Contributed code and patches.
- * Security discussions which are relevant to Qubes in some way.
+* Questions about why we made certain architecture or implementation decisions.
+  * 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.
+* Discussions about proposed new features, patches, etc.
+  * For example: "I would like to implement feature XYZ."
+* Contributed code and patches.
+* 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
- * Project funding applications and strategies
- * FOSS governance discussions
- * Most Github issues tagged "[business]"
+* Participation (talks, workshops, etc.) at upcoming events
+* Project funding applications and strategies
+* FOSS governance discussions
+* 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
- * Who is managing localization for a given language
- * Most Github issues tagged "[localization]"
+* Questions about or issues with [Transifex], the translation platform we use
+* Who is managing localization for a given language
+* 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: 
- * Matrix, strictly Qubes: 
- * `#qubes` channel on freenode.net via traditional IRC clients or: 
-
+* Matrix, Qubes-related: 
+* Matrix, strictly Qubes: 
+* `#qubes` channel on freenode.net via traditional IRC clients or: 
 
 [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
-
diff --git a/project-security/canary-checklist.md b/project-security/canary-checklist.md
index 487a8ba3..ffa1bf40 100644
--- a/project-security/canary-checklist.md
+++ b/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
- * Finalize canary, sign, and add signed tags
- 
-Announcement
-------------
+* Draft canary and push to private repository
+* Finalize canary, sign, and add signed tags
 
- * 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
+## 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
diff --git a/project-security/canary-template.md b/project-security/canary-template.md
index 3aac7bad..1914b456 100644
--- a/project-security/canary-template.md
+++ b/project-security/canary-template.md
@@ -58,4 +58,3 @@ Footnotes
 ```
 
 ~~~
-
diff --git a/project-security/security-bulletins-checklist.md b/project-security/security-bulletins-checklist.md
index 03ba2234..21aa7d0e 100644
--- a/project-security/security-bulletins-checklist.md
+++ b/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
- * Build fixed packages
- * Finalize QSB, sign, and add signed tags
- 
-Announcement
-------------
+* Draft QSB and push to private repository
+* Build fixed packages
+* Finalize QSB, sign, and add signed tags
 
- * 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
+## 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
diff --git a/project-security/security-bulletins-template.md b/project-security/security-bulletins-template.md
index f6d41ba6..c55055a9 100644
--- a/project-security/security-bulletins-template.md
+++ b/project-security/security-bulletins-template.md
@@ -80,4 +80,3 @@ https://www.qubes-os.org/security/
 ```
 
 ~~~
-
diff --git a/project-security/security-pack.md b/project-security/security-pack.md
index e2363bc1..96bbd9e1 100644
--- a/project-security/security-pack.md
+++ b/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 Security Bulletins (QSBs)](/security/bulletins/)
- * [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)
- * Security-related information and announcements (e.g., key revocations)
+* [Qubes PGP keys](https://keys.qubes-os.org/keys/)
+* [Qubes Security Bulletins (QSBs)](/security/bulletins/)
+* [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)
+* Security-related information and announcements (e.g., key revocations)
 
 While `qubes-secpack` itself is independent of any particular host, its current
 official location is:
 
 
 
-
 History and Rationale
 ---------------------
 
@@ -40,92 +39,94 @@ 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:
-    
+
     https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-013-2015.txt
-    
+
     As per the previous discussions about recent problems with verifying
     digital signatures on messages sent to Google Groups (thanks to
     automatic footer addition by Google), we have decided to change the way
     we publish Qubes Security Bulletins, as well as other security-related
     info pertinent to the Qubes Project.
-    
+
     Starting today, we will be maintain a Git repository -- "Qubes Security
     Pack" -- which will contain all the QSBs released so far, all the keys,
     warrant canaries [1], and potentially some additional info or
     announcements (e.g. key revocations). The whole repo can be found here:
-    
+
     https://github.com/QubesOS/qubes-secpack
-    
+
     Note that all the keys distributed there should be signed by Qubes
     Master Key. The Master Key is also attached in the repo, but should
     really be obtained/verified using a different channel.
-    
+
     Additionally, most of the files are signed by core Qubes
     developers (currently by Marek and myself) via detached signatures as
     well as git tag signatures.
-    
+
     The are several advantages of using Git to distribute all these information:
-    
+
     1) Git repo is a collection of files, some of which can be detached GPG
     signatures for other files and we can ensure all these files are
     distributed together.
-    
+
     2) Git makes it easy for people to clone and redistribute these
     collection of files, as well as to easily host them and view on the Web.
-    
+
     3) Git provides for signed tags mechanisms which is another mean we
     utilize to ensure integrity of the distributed files.
-    
+
     A few words about the Warrant Canary which we've just introduced today,
     and which can be seen here:
-    
+
     https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-001-2015.txt
-    
+
     Even though we're not providing any kind of services (such as e.g. email
     hosting), that could be searched or tapped by authorities, there are
     other possibilities that worry us [2], in the light of various recent
     law "developments", such as those that might be coercing people to hand
     over their private keys to authorities.
-    
+
     Until we fully decentralize the root of trust for Qubes, something that
     requires the move to deterministic builds [3], and so won't happen
     very soon, the possibility of having to disclose any of the Qubes
     signing keys to anybody might have pretty serious consequences for those
     who decided to entrust Qubes with anything serious. And we would like to
     somehow minimize these consequences with this canary thing.
-    
+
     Additionally the canary is a nice way of ensuring "freshness" of our
     messaging to the community.
-    
+
     Of course the canary doesn't solve all the problems. E.g. if my signing
     keys were somehow stolen without our knowledge, it wouldn't help.
     Neither it could help in case me being or becoming a miscreant. And
     probably it doesn't address many other potential problems, which could
     only be solved one day with a multi-signature scheme. But anyway, until
     that time, this is the best we can do, I think.
-    
+
     And congrats to Jann for the very interesting clipboard attack (even
     though mostly theoretical, still very cool)!
-    
+
     Thanks,
     joanna.
-    
+
     --
     The Qubes Security Team
     https://www.qubes-os.org/doc/SecurityPage
-    
-    
+
+
     [1] http://en.wikipedia.org/wiki/Warrant_canary
-    
+
     [2] Especially myself, because I'm currently the Root Of Trust for all
     Qubes binaries :/
-    
+
     [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
-        Cloning into 'qubes-secpack'...
-        remote: Counting objects: 195, done.
-        remote: Total 195 (delta 0), reused 0 (delta 0)
-        Receiving objects: 100% (195/195), 130.94 KiB | 207.00 KiB/s, done.
-        Resolving deltas: 100% (47/47), done.
-        Checking connectivity... done.
+    ```shell_session
+    $ git clone https://github.com/QubesOS/qubes-secpack.git
+    Cloning into 'qubes-secpack'...
+    remote: Counting objects: 195, done.
+    remote: Total 195 (delta 0), reused 0 (delta 0)
+    Receiving objects: 100% (195/195), 130.94 KiB | 207.00 KiB/s, 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/*/*
-        gpg: directory `/home/user/.gnupg' created
-        gpg: new configuration file `/home/user/.gnupg/gpg.conf' created
-        gpg: WARNING: options in `/home/user/.gnupg/gpg.conf' are not yet active during this run
-        gpg: keyring `/home/user/.gnupg/secring.gpg' created
-        gpg: keyring `/home/user/.gnupg/pubring.gpg' created
-        gpg: /home/user/.gnupg/trustdb.gpg: trustdb created
-        gpg: key C37BB66B: public key "Joanna Rutkowska (Qubes OS signing key) " imported
-        gpg: key 1E30A75D: public key "Joanna Rutkowska (Qubes OS signing key) " imported
-        gpg: key 74EADABC: public key "Joanna Rutkowska (Qubes OS signing key) " imported
-        gpg: key 65EF29CA: public key "Joanna Rutkowska (Qubes OS Signing Key) " imported
-        gpg: key 34898310: public key "Joanna Rutkowska (Qubes OS Signing Key) " imported
-        gpg: key B298547C: public key "Marek Marczykowski (Qubes OS signing key) " imported
-        gpg: key AB5EEF90: public key "Marek Marczykowski (Qubes OS signing key) " imported
-        gpg: key A603BCB6: public key "Marek Marczykowski (Qubes OS signing key) " imported
-        gpg: key 42CFA724: public key "Marek Marczykowski-Górecki (Qubes OS signing key) " imported
-        gpg: key 15CE40BF: public key "Wojciech Zygmunt Porczyk (Qubes OS signing key) " imported
-        gpg: key 36879494: public key "Qubes Master Signing Key" imported
-        gpg: key 211093A7: public key "Qubes OS Release 1 Signing Key" imported
-        gpg: key 0A40E458: public key "Qubes OS Release 2 Signing Key" imported
-        gpg: key 03FA5082: public key "Qubes OS Release 3 Signing Key" imported
-        gpg: key 92C7B3DC: public key "Joanna Rutkowska (Qubes Security Pack Signing Key) " imported
-        gpg: key 1830E06A: public key "Marek Marczykowski-Górecki (Qubes security pack) " imported
-        gpg: key 3F48CB21: public key "Qubes OS Security Team " imported
-        gpg: Total number processed: 17
-        gpg:               imported: 17  (RSA: 17)
-        gpg: no ultimately trusted keys found
+    ```shell_session
+    $ gpg --import qubes-secpack/keys/*/*
+    gpg: directory `/home/user/.gnupg' created
+    gpg: new configuration file `/home/user/.gnupg/gpg.conf' created
+    gpg: WARNING: options in `/home/user/.gnupg/gpg.conf' are not yet active during this run
+    gpg: keyring `/home/user/.gnupg/secring.gpg' created
+    gpg: keyring `/home/user/.gnupg/pubring.gpg' created
+    gpg: /home/user/.gnupg/trustdb.gpg: trustdb created
+    gpg: key C37BB66B: public key "Joanna Rutkowska (Qubes OS signing key) " imported
+    gpg: key 1E30A75D: public key "Joanna Rutkowska (Qubes OS signing key) " imported
+    gpg: key 74EADABC: public key "Joanna Rutkowska (Qubes OS signing key) " imported
+    gpg: key 65EF29CA: public key "Joanna Rutkowska (Qubes OS Signing Key) " imported
+    gpg: key 34898310: public key "Joanna Rutkowska (Qubes OS Signing Key) " imported
+    gpg: key B298547C: public key "Marek Marczykowski (Qubes OS signing key) " imported
+    gpg: key AB5EEF90: public key "Marek Marczykowski (Qubes OS signing key) " imported
+    gpg: key A603BCB6: public key "Marek Marczykowski (Qubes OS signing key) " imported
+    gpg: key 42CFA724: public key "Marek Marczykowski-Górecki (Qubes OS signing key) " imported
+    gpg: key 15CE40BF: public key "Wojciech Zygmunt Porczyk (Qubes OS signing key) " imported
+    gpg: key 36879494: public key "Qubes Master Signing Key" imported
+    gpg: key 211093A7: public key "Qubes OS Release 1 Signing Key" imported
+    gpg: key 0A40E458: public key "Qubes OS Release 2 Signing Key" imported
+    gpg: key 03FA5082: public key "Qubes OS Release 3 Signing Key" imported
+    gpg: key 92C7B3DC: public key "Joanna Rutkowska (Qubes Security Pack Signing Key) " imported
+    gpg: key 1830E06A: public key "Marek Marczykowski-Górecki (Qubes security pack) " imported
+    gpg: key 3F48CB21: public key "Qubes OS Security Team " imported
+    gpg: Total number processed: 17
+    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
-        gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc.
-        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
-                                                                               
-        gpg> fpr
-        pub   4096R/36879494 2010-04-01 Qubes Master Signing Key
-         Primary key fingerprint: 427F 11FD 0FAA 4B08 0123  F01C DDFA 1A3E 3687 9494
-                                                                               
-        gpg> trust
-        pub  4096R/36879494  created: 2010-04-01  expires: never       usage: SC  
-                             trust: unknown       validity: unknown
-        [ unknown] (1). Qubes Master Signing Key
-                                                                               
-        Please decide how far you trust this user to correctly verify other users' keys
-        (by looking at passports, checking fingerprints from different sources, etc.)
-                                                                               
-          1 = I don't know or won't say
-          2 = I do NOT trust
-          3 = I trust marginally
-          4 = I trust fully
-          5 = I trust ultimately
-          m = back to the main menu
-                                                                               
-        Your decision? 5
-        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  
-                             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
+    ```shell_session
+    $ gpg --edit-key 36879494
+    gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc.
+    This is free software: you are free to change and redistribute it.
+    There is NO WARRANTY, to the extent permitted by law.
 
-    **Important!**
-   
-    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
-    a trustworthy source (ideally, multiple sources) *other than* this website
-    and visually compare it (them) to the fingerprint displayed in the preceding
-    step, ensuring they match. You can read more about digital signatures and
-    key verification [here](/security/verifying-signatures/).
 
- 4. Verify signed Git tags.
+    pub  4096R/36879494  created: 2010-04-01  expires: never       usage: SC
+                         trust: unknown       validity: unknown
+    [ unknown] (1). Qubes Master Signing Key
 
-        $ cd qubes-secpack/
-        $ git tag -v `git describe`
-        object 2bb7f0b966593d8ed74e140a04d60c68b96b164e
-        type commit
-        tag joanna_sec_2bb7f0b9
-        tagger Joanna Rutkowska  1468335706 +0000
-        
-        Tag for commit 2bb7f0b966593d8ed74e140a04d60c68b96b164e
-        gpg: Signature made 2016-07-12T08:01:46 PDT
-        gpg:                using RSA key 0x4E6829BC92C7B3DC
-        gpg: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) " [full]
+    gpg> fpr
+    pub   4096R/36879494 2010-04-01 Qubes Master Signing Key
+    Primary key fingerprint: 427F 11FD 0FAA 4B08 0123  F01C DDFA 1A3E 3687 9494
+
+    gpg> trust
+    pub  4096R/36879494  created: 2010-04-01  expires: never       usage: SC
+                         trust: unknown       validity: unknown
+    [ unknown] (1). Qubes Master Signing Key
+
+    Please decide how far you trust this user to correctly verify other users' keys
+    (by looking at passports, checking fingerprints from different sources, etc.)
+
+    1 = I don't know or won't say
+    2 = I do NOT trust
+    3 = I trust marginally
+    4 = I trust fully
+    5 = I trust ultimately
+    m = back to the main menu
+
+    Your decision? 5
+    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
+                         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
+    ```
+
+   **Important!**
+
+   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
+   a trustworthy source (ideally, multiple sources) *other than* this website
+   and visually compare it (them) to the fingerprint displayed in the preceding
+   step, ensuring they match. You can read more about digital signatures and
+   key verification [here](/security/verifying-signatures/).
+
+4. Verify signed Git tags.
+
+    ```shell_session
+    $ cd qubes-secpack/
+    $ git tag -v `git describe`
+    object 2bb7f0b966593d8ed74e140a04d60c68b96b164e
+    type commit
+    tag joanna_sec_2bb7f0b9
+    tagger Joanna Rutkowska  1468335706 +0000
+
+    Tag for commit 2bb7f0b966593d8ed74e140a04d60c68b96b164e
+    gpg: Signature made 2016-07-12T08:01:46 PDT
+    gpg:                using RSA key 0x4E6829BC92C7B3DC
+    gpg: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) " [full]
+    ```
 
     (The final line of output confirms that the signature is good.)
 
- 5. Verify detached PGP signatures.
+5. Verify detached PGP signatures.
 
-        $ cd canaries/                                     
-        $ gpg --verify canary-001-2015.txt.sig.joanna canary-001-2015.txt
-        gpg: Signature made Mon Jan  5 20:21:40 2015 UTC using RSA key ID 92C7B3DC
-        gpg: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) "
-        $ gpg --verify canary-001-2015.txt.sig.marmarek canary-001-2015.txt
-        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) "
+    ```shell_session
+    $ cd canaries/
+    $ gpg --verify canary-001-2015.txt.sig.joanna canary-001-2015.txt
+    gpg: Signature made Mon Jan  5 20:21:40 2015 UTC using RSA key ID 92C7B3DC
+    gpg: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) "
+    $ gpg --verify canary-001-2015.txt.sig.marmarek canary-001-2015.txt
+    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) "
+    ```
 
-    (The fourth and final lines of output confirm that the two signatures are
-    good.)
+(The fourth and final lines of output confirm that the two signatures are
+ 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.
-
diff --git a/project-security/security.md b/project-security/security.md
index 25eb0c82..4059f807 100644
--- a/project-security/security.md
+++ b/project-security/security.md
@@ -2,7 +2,7 @@
 layout: doc
 title: Security
 permalink: /security/
-redirect_from: 
+redirect_from:
 - /en/security/
 - /en/doc/security/
 - /en/doc/qubes-security/
@@ -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]
- - 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, signing, and publishing [Security Bulletins]
- - Writing, signing, and publishing [Canaries]
- - Generating, safeguarding, and using the project's [PGP Keys]
+- Responding to [reported security issues]
+- 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, signing, and publishing [Security Bulletins]
+- Writing, signing, and publishing [Canaries]
+- 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/
diff --git a/project-security/verifying-signatures.md b/project-security/verifying-signatures.md
index af43e0d7..52068abf 100644
--- a/project-security/verifying-signatures.md
+++ b/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]
- 2. [Get the Release Signing Key][RSK]
- 3. [Verify your Qubes ISO][signature file]
+1. [Get the Qubes Master Signing Key and verify its authenticity][QMSK]
+2. [Get the Release Signing Key][RSK]
+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:
+    
+    ```shell_session
+    $ dnf install distribution-gpg-keys
+    ```
 
-       $ 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:
+    ```shell_session
+    $ gpg2 --fetch-keys https://keys.qubes-os.org/keys/qubes-master-signing-key.asc
+    ```
 
-       $ 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:
+    ```shell_session
+    $ gpg2 --import ./qubes-master-signing-key.asc
+    ```
 
-       $ gpg2 --import ./qubes-master-signing-key.asc 
+- Get it from a public [keyserver] (specified on first use with `--keyserver ` along with keyserver options to include key signatures), e.g.:
 
- - Get it from a public [keyserver] (specified on first use with `--keyserver ` 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
-    uid   Qubes Master Signing Key
+```
+pub   4096R/36879494 2010-04-01
+      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 against PDFs, photographs, and videos in which the fingerprint appears
+- 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
    (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.
- - Ask people to post the fingerprint on various mailing lists, forums, and chat rooms.
- - Repeat the above over Tor.
- - Repeat the above over various VPNs and proxy servers.
- - 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.
- - Repeat the above from different computers and devices.
+- 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.
+- Repeat the above over Tor.
+- Repeat the above over various VPNs and proxy servers.
+- 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.
+- 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.
-    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
-    
-    gpg> fpr
-    pub   4096R/36879494 2010-04-01 Qubes Master Signing Key
-     Primary key fingerprint: 427F 11FD 0FAA 4B08 0123  F01C DDFA 1A3E 3687 9494
-    
-    gpg> trust
-    pub  4096R/36879494  created: 2010-04-01  expires: never       usage: SC
-                         trust: unknown       validity: unknown
-    [ unknown] (1). Qubes Master Signing Key
-    
-    Please decide how far you trust this user to correctly verify other users' keys
-    (by looking at passports, checking fingerprints from different sources, etc.)
-    
-      1 = I don't know or won't say
-      2 = I do NOT trust
-      3 = I trust marginally
-      4 = I trust fully
-      5 = I trust ultimately
-      m = back to the main menu
-    
-    Your decision? 5
-    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
-                         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
+```
+$ gpg2 --edit-key 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
+gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc.
+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
+
+gpg> fpr
+pub   4096R/36879494 2010-04-01 Qubes Master Signing Key
+Primary key fingerprint: 427F 11FD 0FAA 4B08 0123  F01C DDFA 1A3E 3687 9494
+
+gpg> trust
+pub  4096R/36879494  created: 2010-04-01  expires: never       usage: SC
+                     trust: unknown       validity: unknown
+[ unknown] (1). Qubes Master Signing Key
+
+Please decide how far you trust this user to correctly verify other users' keys
+(by looking at passports, checking fingerprints from different sources, etc.)
+
+   1 = I don't know or won't say
+   2 = I do NOT trust
+   3 = I trust marginally
+   4 = I trust fully
+   5 = I trust ultimately
+   m = back to the main menu
+
+Your decision? 5
+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
+                     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]
-          427F11FD0FAA4B080123F01CDDFA1A3E36879494
-    uid           [ultimate] Qubes Master Signing Key
+```
+$ gpg2 -k "Qubes Master Signing Key"
+pub   rsa4096 2010-04-01 [SC]
+      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-*`.
-   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-*`.
-   If you wish to use one of these keys, make sure to import it into your keyring, e.g.:
+- 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.
+  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.:
 
-       $ 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.
-   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].
-   Once you've downloaded your Release Signing Key, import it with GPG:
+- Download it as a file.
+  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].
+  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"
-    pub   rsa4096 2017-03-06 [SC]
-          5817A43B283DE5A9181A522E1848792F9E2795E9
-    uid           [  full  ] Qubes OS Release X Signing Key
-    sig!3        1848792F9E2795E9 2017-03-06  Qubes OS Release X Signing Key
-    sig!         DDFA1A3E36879494 2017-03-08  Qubes Master Signing Key
+```shell_session
+$ gpg2 --check-signatures "Qubes OS Release X Signing Key"
+pub   rsa4096 2017-03-06 [SC]
+      5817A43B283DE5A9181A522E1848792F9E2795E9
+uid           [  full  ] Qubes OS Release X 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]
-          5817A43B283DE5A9181A522E1848792F9E2795E9
-    uid           [  full  ] Qubes OS Release X Signing Key
+```
+$ gpg2 -k "Qubes OS Release"
+pub   rsa4096 2017-03-06 [SC]
+      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
-    gpg: armor header: Version: GnuPG v1
-    gpg: Signature made Tue 08 Mar 2016 07:40:56 PM PST using RSA key ID 03FA5082
-    gpg: using PGP trust model
-    gpg: Good signature from "Qubes OS Release X Signing Key"
-    gpg: binary signature, digest algorithm SHA256
+```shell_session
+$ gpg2 -v --verify Qubes-RX-x86_64.iso.asc Qubes-RX-x86_64.iso
+gpg: armor header: Version: GnuPG v1
+gpg: Signature made Tue 08 Mar 2016 07:40:56 PM PST using RSA key ID 03FA5082
+gpg: using PGP trust model
+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
-    
-    3c951138b8b9867d8657f173c1b58b82 *Qubes-RX-x86_64.iso
-    1fc9508160d7c4cba6cacc3025165b0f996c843f *Qubes-RX-x86_64.iso
-    6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a *Qubes-RX-x86_64.iso
-    de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe *Qubes-RX-x86_64.iso
-    -----BEGIN PGP SIGNATURE-----
-    Version: GnuPG v2
-    
-    iQIcBAEBCAAGBQJX4XO/AAoJEMsRyh0D+lCCL9sP/jlZ26zhvlDEX/eaA/ANa/6b
-    Dpsh/sqZEpz1SWoUxdm0gS+anc8nSDoCQSMBxnafuBbmwTChdHI/P7NvNirCULma
-    9nw+EYCsCiNZ9+WCeroR8XDFSiDjvfkve0R8nwfma1XDqu1bN2ed4n/zNoGgQ8w0
-    t5LEVDKCVJ+65pI7RzOSMbWaw+uWfGehbgumD7a6rfEOqOTONoZOjJJTnM0+NFJF
-    Qz5yBg+0FQYc7FmfX+tY801AwSyevj3LKGqZN1GVcU9hhoHH7f2BcbdNk9I5WHHq
-    doKMnZtcdyadQGwMNB68Wu9+0CWsXvk6E00QfW69M4d6w0gbyoJyUL1uzxgixb5O
-    qodxrqeitXQSZZvU4kom5zlSjqZs4dGK+Ueplpkr8voT8TSWer0Nbh/VMfrNSt1z
-    0/j+e/KMjor7XxehR+XhNWa2YLjA5l5H9rP+Ct/LAfVFp4uhsAnYf0rUskhCStxf
-    Zmtqz4FOw/iSz0Os+IVcnRcyTYWh3e9XaW56b9J/ou0wlwmJ7oJuEikOHBDjrUph
-    2a8AM+QzNmnc0tDBWTtT2frXcotqL+Evp/kQr5G5pJM/mTR5EQm7+LKSl7yCPoCj
-    g8JqGYYptgkxjQdX3YAy9VDsCJ/6EkFc2lkQHbgZxjXqyrEMbgeSXtMltZ7cCqw1
-    3N/6YZw1gSuvBlTquP27
-    =e9oD
-    -----END PGP SIGNATURE-----
-    
+```
+-----BEGIN PGP SIGNED MESSAGE-----
+Hash: SHA256
+
+3c951138b8b9867d8657f173c1b58b82 *Qubes-RX-x86_64.iso
+1fc9508160d7c4cba6cacc3025165b0f996c843f *Qubes-RX-x86_64.iso
+6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a *Qubes-RX-x86_64.iso
+de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe *Qubes-RX-x86_64.iso
+-----BEGIN PGP SIGNATURE-----
+Version: GnuPG v2
+
+iQIcBAEBCAAGBQJX4XO/AAoJEMsRyh0D+lCCL9sP/jlZ26zhvlDEX/eaA/ANa/6b
+Dpsh/sqZEpz1SWoUxdm0gS+anc8nSDoCQSMBxnafuBbmwTChdHI/P7NvNirCULma
+9nw+EYCsCiNZ9+WCeroR8XDFSiDjvfkve0R8nwfma1XDqu1bN2ed4n/zNoGgQ8w0
+t5LEVDKCVJ+65pI7RzOSMbWaw+uWfGehbgumD7a6rfEOqOTONoZOjJJTnM0+NFJF
+Qz5yBg+0FQYc7FmfX+tY801AwSyevj3LKGqZN1GVcU9hhoHH7f2BcbdNk9I5WHHq
+doKMnZtcdyadQGwMNB68Wu9+0CWsXvk6E00QfW69M4d6w0gbyoJyUL1uzxgixb5O
+qodxrqeitXQSZZvU4kom5zlSjqZs4dGK+Ueplpkr8voT8TSWer0Nbh/VMfrNSt1z
+0/j+e/KMjor7XxehR+XhNWa2YLjA5l5H9rP+Ct/LAfVFp4uhsAnYf0rUskhCStxf
+Zmtqz4FOw/iSz0Os+IVcnRcyTYWh3e9XaW56b9J/ou0wlwmJ7oJuEikOHBDjrUph
+2a8AM+QzNmnc0tDBWTtT2frXcotqL+Evp/kQr5G5pJM/mTR5EQm7+LKSl7yCPoCj
+g8JqGYYptgkxjQdX3YAy9VDsCJ/6EkFc2lkQHbgZxjXqyrEMbgeSXtMltZ7cCqw1
+3N/6YZw1gSuvBlTquP27
+=e9oD
+-----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
-    Qubes-RX-x86_64.iso: OK
-    md5sum: WARNING: 23 lines are improperly formatted
-    $ sha1sum -c Qubes-RX-x86_64.iso.DIGESTS
-    Qubes-RX-x86_64.iso: OK
-    sha1sum: WARNING: 23 lines are improperly formatted
-    $ sha256sum -c Qubes-RX-x86_64.iso.DIGESTS
-    Qubes-RX-x86_64.iso: OK
-    sha256sum: WARNING: 23 lines are improperly formatted
-    $ sha512sum -c Qubes-RX-x86_64.iso.DIGESTS
-    Qubes-RX-x86_64.iso: OK
-    sha512sum: WARNING: 23 lines are improperly formatted
+```shell_session
+$ md5sum -c Qubes-RX-x86_64.iso.DIGESTS
+ Qubes-RX-x86_64.iso: OK
+md5sum: WARNING: 23 lines are improperly formatted
+$ sha1sum -c Qubes-RX-x86_64.iso.DIGESTS
+Qubes-RX-x86_64.iso: OK
+sha1sum: WARNING: 23 lines are improperly formatted
+$ sha256sum -c Qubes-RX-x86_64.iso.DIGESTS
+Qubes-RX-x86_64.iso: OK
+sha256sum: WARNING: 23 lines are improperly formatted
+$ sha512sum -c Qubes-RX-x86_64.iso.DIGESTS
+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
-    MD5(Qubes-RX-x86_64.iso)= 3c951138b8b9867d8657f173c1b58b82
-    $ openssl dgst -sha1 Qubes-RX-x86_64.iso
-    SHA1(Qubes-RX-x86_64.iso)= 1fc9508160d7c4cba6cacc3025165b0f996c843f
-    $ openssl dgst -sha256 Qubes-RX-x86_64.iso
-    SHA256(Qubes-RX-x86_64.iso)= 6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a
-    $ openssl dgst -sha512 Qubes-RX-x86_64.iso
-    SHA512(Qubes-RX-x86_64.iso)= de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe
+```shell_session
+$ openssl dgst -md5 Qubes-RX-x86_64.iso
+MD5(Qubes-RX-x86_64.iso)= 3c951138b8b9867d8657f173c1b58b82
+$ openssl dgst -sha1 Qubes-RX-x86_64.iso
+SHA1(Qubes-RX-x86_64.iso)= 1fc9508160d7c4cba6cacc3025165b0f996c843f
+$ openssl dgst -sha256 Qubes-RX-x86_64.iso
+SHA256(Qubes-RX-x86_64.iso)= 6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a
+$ 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]
- 2. [Get the Release Signing Key][RSK]
- 3. Verify the signature in the digest file:
+1. [Get the Qubes Master Signing Key and verify its authenticity][QMSK]
+2. [Get the Release Signing Key][RSK]
+3. Verify the signature in the digest file:
+
+    ```shell_session
+    $ gpg2 -v --verify Qubes-RX-x86_64.iso.DIGESTS
+    gpg: armor header: Hash: SHA256
+    gpg: armor header: Version: GnuPG v2
+    gpg: original file name=''
+    gpg: Signature made Tue 20 Sep 2016 10:37:03 AM PDT using RSA key ID 03FA5082
+    gpg: using PGP trust model
+    gpg: Good signature from "Qubes OS Release X Signing Key"
+    gpg: textmode signature, digest algorithm SHA256
+    ```
 
-        $ gpg2 -v --verify Qubes-RX-x86_64.iso.DIGESTS 
-        gpg: armor header: Hash: SHA256
-        gpg: armor header: Version: GnuPG v2
-        gpg: original file name=''
-        gpg: Signature made Tue 20 Sep 2016 10:37:03 AM PDT using RSA key ID 03FA5082
-        gpg: using PGP trust model
-        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 
+```shell_session
+$ git tag -v 
+```
 
 or
 
-    $ git verify-tag 
+```shell_session
+$ git verify-tag 
+```
 
 To verify a signature on a Git commit:
 
-    $ git log --show-signature 
+```shell_session
+$ git log --show-signature 
+```
 
 or
 
-    $ git verify-commit 
+```shell_session
+$ git verify-commit 
+```
 
 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,112 +430,92 @@ 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).
-   Read this page again carefully.
- - You're using the wrong GPG command.
-   Follow the examples in [Verify your Qubes ISO][signature file] carefully.
- - 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.
-   If you still get the same result, try downloading the ISO again from a different source, then try verifying again.
-
+- You're trying to verify the wrong file(s).
+  Read this page again carefully.
+- You're using the wrong GPG command.
+  Follow the examples in [Verify your Qubes ISO][signature file] carefully.
+- 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.
+  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.
 Anyone can sign anyone else's public key and upload the signed public key to keyservers.
-Everyone is also free to revoke their own keys at any time (assuming they possess or can create a revocation certificate). 
+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
-
diff --git a/project-security/xsa.md b/project-security/xsa.md
index 6341cf6a..849d004e 100644
--- a/project-security/xsa.md
+++ b/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.
diff --git a/user/advanced-configuration/awesome.md b/user/advanced-configuration/awesome.md
index 4f95505c..9f77d808 100644
--- a/user/advanced-configuration/awesome.md
+++ b/user/advanced-configuration/awesome.md
@@ -19,15 +19,19 @@ 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.
 
 ## Development
 
 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.
-
diff --git a/user/advanced-configuration/bind-dirs.md b/user/advanced-configuration/bind-dirs.md
index 75b046c1..b8f54056 100644
--- a/user/advanced-configuration/bind-dirs.md
+++ b/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.
diff --git a/user/advanced-configuration/config-files.md b/user/advanced-configuration/config-files.md
index e03dd9ed..9471d45b 100644
--- a/user/advanced-configuration/config-files.md
+++ b/user/advanced-configuration/config-files.md
@@ -16,16 +16,16 @@ Qubes-specific VM config files
 ------------------------------
 
 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. 
+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:
 
     ~~~
     # Store bluetooth keys in /rw to keep them across VM restarts
-    rm -rf /var/lib/bluetooth 
+    rm -rf /var/lib/bluetooth
     ln -s /rw/config/var-lib-bluetooth /var/lib/bluetooth
     ~~~
 
@@ -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.
-    Good place to write custom firewall rules.
+- 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.
 
     ~~~
     /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.
-    The file is used only in a VM with PCI devices attached.
-    Intended for use with problematic device drivers.
+- `/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.
+  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).
-     Note that this will cause much higher CPU usage in dom0. It's enabled by
-		 default, disabling it may save CPU in dom0.
+- `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
+  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).
diff --git a/user/advanced-configuration/disposablevm-customization.md b/user/advanced-configuration/disposablevm-customization.md
index 6d3fd1c9..b6677902 100644
--- a/user/advanced-configuration/disposablevm-customization.md
+++ b/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
-    [user@dom0 ~]$ qvm-prefs custom-disposablevm-template template_for_dispvms True
-    [user@dom0 ~]$ qvm-features custom-disposablevm-template appmenus-dispvm 1
+```shell_session
+[user@dom0 ~]$ qvm-create --template debian-9 --label red custom-disposablevm-template
+[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:
-    -   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 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).
+2. Change the qube's settings and/or applications, as desired. Some examples of changes you may want to make include:
+    - Changing Firefox's default startup settings and homepage.
+    - Changing default editor, image viewer. 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.
 
+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 DisposableVMs to autostart at system boot.
-   * Attach PCI devices with the `--persistent` option. 
+- Set custom firewall rule sets and run Qubes VPN scripts. 
+- Set DisposableVMs to autostart at system boot.
+- 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 
+    ```shell_session
+    [user@dom0 ~]$ qvm-create --class AppVM --label gray 
+    ```
 
 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  template_for_dispvms true
-
+    ```shell_session
+    [user@dom0 ~]$ qvm-prefs  template_for_dispvms true
+    ```
 
 ### Create the sys-net DisposableVM
 
 1. Create `sys-net` DisposableVM based on the DisposableVM Template:
 
-       [user@dom0 ~]$ qvm-create --template  --class DispVM --label red disp-sys-net
+    ```shell_session
+    [user@dom0 ~]$ qvm-create --template  --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 :
+    ```shell_session
+    [user@dom0 ~]$ qvm-pci attach --persistent disp-sys-net :
+    ```
 
 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  --class DispVM --label green disp-sys-firewall
+    ```shell_session
+    [user@dom0 ~]$ qvm-create --template  --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  netvm disp-sys-firewall
+    ```shell_session
+    [user@dom0 ~]$ qvm-prefs  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  --class DispVM --label red disp-sys-usb
+    ```shell_session
+    [user@dom0 ~]$ qvm-create --template  --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 :
+    ```
 
-       [user@dom0 ~]$ qvm-pci attach --persistent disp-sys-usb :
-    
 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:
-
-    [user@dom0~]$ qvm-pci detach  :
+Detach PCI device from VM:
 
+```shell_session
+[user@dom0~]$ qvm-pci detach  :
+```
 
 ### 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
-    default_dispvm        -  custom-disposablevm-template
+```shell_session
+[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
-    This will completely remove the selected VM(s)
-      custom-disposablevm-template
+```shell_session
+[user@dom0 ~]$ qvm-remove 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
+```
diff --git a/user/advanced-configuration/gui-configuration.md b/user/advanced-configuration/gui-configuration.md
index 14adf587..9f3a1d90 100644
--- a/user/advanced-configuration/gui-configuration.md
+++ b/user/advanced-configuration/gui-configuration.md
@@ -51,5 +51,4 @@ EndSection
 
 ## GUI Troubleshooting
 
-See [GUI Troubleshooting](/doc/gui-troubleshooting) for issues relating to the Qubes graphical user interface and how to fix them. 
-
+See [GUI Troubleshooting](/doc/gui-troubleshooting) for issues relating to the Qubes graphical user interface and how to fix them.
diff --git a/user/advanced-configuration/i3.md b/user/advanced-configuration/i3.md
index 4730e990..a28e0027 100644
--- a/user/advanced-configuration/i3.md
+++ b/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
-    $ make verify-sources
-    $ make rpms
+```shell_session
+$ make get-sources
+$ make verify-sources
+$ make rpms
+```
 
 ### Installing
 
@@ -79,17 +87,23 @@ next step.
 
 Now in dom0, copy in the rpm:
 
-    $ qvm-run --pass-io  'cat ' > i3.rpm
+```shell_session
+$ qvm-run --pass-io  'cat ' > 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 \\
-        rxvt-unicode xcb-util-wm perl-JSON-XS xcb-util-cursor \\
-        dzen2 dmenu xorg-x11-fonts-misc libev
+```shell_session
+$ sudo qubes-dom0-update perl-AnyEvent-I3 xorg-x11-apps \\
+    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.
diff --git a/user/advanced-configuration/installing-contributed-packages.md b/user/advanced-configuration/installing-contributed-packages.md
index 31fb395e..61625145 100644
--- a/user/advanced-configuration/installing-contributed-packages.md
+++ b/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/
-
diff --git a/user/advanced-configuration/kde.md b/user/advanced-configuration/kde.md
index b27a93e8..f062050e 100644
--- a/user/advanced-configuration/kde.md
+++ b/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)
diff --git a/user/advanced-configuration/managing-vm-kernel.md b/user/advanced-configuration/managing-vm-kernel.md
index c8948b37..b9066dfe 100644
--- a/user/advanced-configuration/managing-vm-kernel.md
+++ b/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)
-- `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)
-- `default-kernelopts-common.txt` - default kernel options, in addition to those specified with `kernelopts` qube property (can be disabled with `no-default-kernelopts` feature)
+* `vmlinuz` - kernel binary (may not be a Linux kernel)
+* `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)
+* `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:
 
@@ -246,7 +241,7 @@ If you'd like to use a different kernel than default, continue reading.
 Install whatever kernel you want.
 You need to also ensure you have the `kernel-devel` package for the same kernel version installed.
 
-If you are using a distribution kernel package (`kernel` package), the initramfs and kernel modules may be handled automatically. 
+If you are using a distribution kernel package (`kernel` package), the initramfs and kernel modules may be handled automatically.
 If you are using a manually built kernel, you need to handle this on your own.
 Take a look at the `dkms` documentation, especially the `dkms autoinstall` command may be useful.
 If you did not see the `kernel` install rebuild your initramfs, or are using a manually built kernel, you will need to rebuild it yourself.
@@ -256,8 +251,8 @@ Replace the version numbers in the example below with the ones appropriate to th
 sudo dracut -f /boot/initramfs-4.15.14-200.fc26.x86_64.img 4.15.14-200.fc26.x86_64
 ~~~
 
-Once the kernel is installed, you need to create a GRUB configuration. 
-You may want to adjust some settings in `/etc/default/grub`; for example, lower `GRUB_TIMEOUT` to speed up VM startup. 
+Once the kernel is installed, you need to create a GRUB configuration.
+You may want to adjust some settings in `/etc/default/grub`; for example, lower `GRUB_TIMEOUT` to speed up VM startup.
 Then, you need to generate the actual configuration:
 In Fedora it can be done using the `grub2-mkconfig` tool:
 
@@ -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`
 
@@ -311,52 +306,59 @@ Depends on `Virtualization` mode setting:
 
 The `Kernel` setting of the `Virtualization` mode setting:
 
-* If `Virtualization` is set to `PVH` -> `Kernel` -> choose `pvgrub2-pvh` -> OK 
-* If `Virtualization` is set to `PV` -> `Kernel` -> choose `pvgrub2` -> OK 
-* If `Virtualization` is set to `HVM` -> `Kernel` -> choose `none` -> OK 
+* If `Virtualization` is set to `PVH` -> `Kernel` -> choose `pvgrub2-pvh` -> OK
+* If `Virtualization` is set to `PV` -> `Kernel` -> choose `pvgrub2` -> OK
+* If `Virtualization` is set to `HVM` -> `Kernel` -> choose `none` -> OK
 
 Start the VM.
 
-The process of using Qubes VM kernel with distribution kernel is complete. 
+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  with actual kernel version.
 
-    sudo dkms autoinstall -k 
-    
+```bash_session
+sudo dkms autoinstall -k 
+```
+
 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:
-	Running module version sanity check.
-	 - Original module
-	   - No original module exists within this kernel
-	 - Installation
-	   - Installing to /lib/modules/3.16.0-4-amd64/updates/dkms/
+u2mfn:
+Running module version sanity check.
+  - Original module
+    - No original module exists within this kernel
+  - Installation
+    - Installing to /lib/modules/3.16.0-4-amd64/updates/dkms/
 
-	depmod....
+depmod....
 
-	DKMS: install completed.
-	$ sudo update-initramfs -u
-	update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64
+  DKMS: install completed.
+$ sudo update-initramfs -u
+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. 
-
+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
-
diff --git a/user/advanced-configuration/mount-from-other-os.md b/user/advanced-configuration/mount-from-other-os.md
index 64160df9..176466fb 100644
--- a/user/advanced-configuration/mount-from-other-os.md
+++ b/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.
-	   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
-	├─sda2                                                                8:2    0     1G  0 part  /boot
-	└─sda3                                                                8:3    0 110.6G  0 part
-	  └─luks-fed62fc2-2674-266d-2667-2667259cbdec                       253:0    0 110.6G  0 crypt
-		├─qubes_dom0-pool00_tmeta                                       253:1    0    88M  0 lvm
-		│ └─qubes_dom0-pool00-tpool                                     253:3    0  84.4G  0 lvm
-		│   ├─qubes_dom0-root                                           253:4    0  84.4G  0 lvm   /
-		│   ├─qubes_dom0-pool00                                         253:6    0  84.4G  0 lvm
-		│   ├─qubes_dom0-vm--fedora--30--dvm--private--1576749131--back 253:7    0     2G  0 lvm
-		├─qubes_dom0-pool00_tdata                                       253:2    0  84.4G  0 lvm
-		│ └─qubes_dom0-pool00-tpool                                     253:3    0  84.4G  0 lvm
-		│   ├─qubes_dom0-root                                           253:4    0  84.4G  0 lvm   /
-		│   ├─qubes_dom0-pool00                                         253:6    0  84.4G  0 lvm
-		│   ├─qubes_dom0-vm--fedora--30--dvm--private--1576749131--back 253:7    0     2G  0 lvm
-		└─qubes_dom0-swap                                               253:5    0     4G  0 lvm   [SWAP]
-	sdb                                                                   8:16   0 447.1G  0 disk
-	├─sdb1                                                                8:17   0   549M  0 part
-	└─sdb2                                                                8:18   0 446.6G  0 part
-	sr0                                                                  11:0    1  1024M  0 rom
-	nvme0n1                                                             259:0    0 465.8G  0 disk
-	├─nvme0n1p1                                                         259:1    0     1G  0 part
-	└─nvme0n1p2                                                         259:2    0 464.8G  0 part
-```
+    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`.
+
+        ```
+        sda                                                                   8:0    0 111.8G  0 disk
+        ├─sda1                                                                8:1    0   200M  0 part  /boot/efi
+        ├─sda2                                                                8:2    0     1G  0 part  /boot
+        └─sda3                                                                8:3    0 110.6G  0 part
+          └─luks-fed62fc2-2674-266d-2667-2667259cbdec                       253:0    0 110.6G  0 crypt
+            ├─qubes_dom0-pool00_tmeta                                       253:1    0    88M  0 lvm
+            │ └─qubes_dom0-pool00-tpool                                     253:3    0  84.4G  0 lvm
+            │   ├─qubes_dom0-root                                           253:4    0  84.4G  0 lvm   /
+            │   ├─qubes_dom0-pool00                                         253:6    0  84.4G  0 lvm
+            ├─qubes_dom0-vm--fedora--30--dvm--private--1576749131--back 253:7    0     2G  0 lvm
+            ├─qubes_dom0-pool00_tdata                                       253:2    0  84.4G  0 lvm
+            │ └─qubes_dom0-pool00-tpool                                     253:3    0  84.4G  0 lvm
+            │   ├─qubes_dom0-root                                           253:4    0  84.4G  0 lvm   /
+            │   ├─qubes_dom0-pool00                                         253:6    0  84.4G  0 lvm
+            │   ├─qubes_dom0-vm--fedora--30--dvm--private--1576749131--back 253:7    0     2G  0 lvm
+            └─qubes_dom0-swap                                               253:5    0     4G  0 lvm   [SWAP]
+        sdb                                                                   8:16   0 447.1G  0 disk
+        ├─sdb1                                                                8:17   0   549M  0 part
+        └─sdb2                                                                8:18   0 446.6G  0 part
+        sr0                                                                  11:0    1  1024M  0 rom
+        nvme0n1                                                             259:0    0 465.8G  0 disk
+        ├─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/`.
 
@@ -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.
-	   This will conflict with the name of the VG of the currently installed system.
-	   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.
-	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.
-	3. The command `vgrename  other_install` will rename the 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.
+       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.
+    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.
+    3. The command `vgrename  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/-private   | VM  				| The /rw partition of the named VM. 		  |
-| other\_install/-root      | templateVM root 	| The root partition of the named TemplateVM. |
-| other\_install/pool00\_tmeta     	| LVM Metadata 		| The metadata LV of this disk. 			  |
+| other\_install/root           | dom0 root         | The root partition of dom0.                 |
+| other\_install/-private   | VM                | The /rw partition of the named VM.          |
+| other\_install/-root      | templateVM root   | The root partition of the named TemplateVM. |
+| other\_install/pool00\_tmeta  | LVM Metadata      | The metadata LV of this disk.               |
 
 6. Mount the disk using the command `mount /dev/other_install/ `.
    *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`.
-
-
diff --git a/user/advanced-configuration/resize-disk-image.md b/user/advanced-configuration/resize-disk-image.md
index 434ea001..60ee2238 100644
--- a/user/advanced-configuration/resize-disk-image.md
+++ b/user/advanced-configuration/resize-disk-image.md
@@ -11,21 +11,19 @@ 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.
-So a 2GB private volume with 100M of files will only use 100M.  
+So a 2GB private volume with 100M of files will only use 100M.
 This explains how you can have *many* qubes with large private volumes on quite a small disk.
-This is called over provisioning.  
+This is called over provisioning.
 You should keep an eye on the disk-space widget to see how much free space you actually have.
 
 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.
@@ -33,7 +31,7 @@ In most cases, the GUI tool Qube Settings (available for every qube from the Sta
 ![vm-settings-disk-image.png](/attachment/wiki/DiskSize/r4.0-vm-settings-disk-image.png)
 
 In case of standalone qubes and templates, just change the Disk Storage settings above.
-In case of template-based qubes, the private storage (the /home directory and user files) can be changed in the qube's own settings, but the system root image is [inherited from the template](/getting-started/), and so it must be changed in the template settings. 
+In case of template-based qubes, the private storage (the /home directory and user files) can be changed in the qube's own settings, but the system root image is [inherited from the template](/getting-started/), and so it must be changed in the template settings.
 If you are increasing the disk image size for Linux-based qubes installed from Qubes OS repositories in Qubes 4.0 or later, changing the settings above is all you need to do - in other cases, you may need to do more, according to instructions below.
 See also the OS-specific follow-up instructions below.
 
@@ -45,30 +43,32 @@ Maximum size which can be assigned through Qube Settings is 1048576 MiB - if you
 ~~~
 qvm-volume extend :root 
 ~~~
+
 OR
+
 ~~~
 qvm-volume extend :private 
 ~~~
 
 Note: Size is the target size (i.e. 4096MB or 16GB, ...), not the size to add to the existing disk.
 
-If you have run out of space for software in your Template, you need to increase *root image* of the Template (not private storage!). 
+If you have run out of space for software in your Template, you need to increase *root image* of the Template (not private storage!).
 **Make sure changes in the Template between reboots don't exceed 10G.**
 It is recommended that you restart (or start and then shutdown, if it is not running) the template after resizing the root image.
 
 If you are **not** using Linux in the qube, you will also need to:
 
-1.  Start the template.
-2.  Resize the filesystem using OS appropriate tools.
-3.  Verify available space in the template using `df -h` or OS specific tools.
-4.  Shutdown the template.
+1. Start the template.
+2. Resize the filesystem using OS appropriate tools.
+3. Verify available space in the template using `df -h` or OS specific tools.
+4. Shutdown the template.
 
-#### Windows 7 ####
+#### Windows 7
 
-1.  Click Start
-2.  type "diskmgmt.msc" - this takes you to Disk Management
-3.  Right-click on your existing volume, select "Extend Volume..."
-4.  Click through the wizard.
+1. Click Start
+2. type "diskmgmt.msc" - this takes you to Disk Management
+3. Right-click on your existing volume, select "Extend Volume..."
+4. Click through the wizard.
 
 No reboot required.
 
@@ -87,19 +87,18 @@ 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.  
+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.
 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:  
+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
-
-
-
-
-
diff --git a/user/advanced-configuration/rpc-policy.md b/user/advanced-configuration/rpc-policy.md
index fe516f5a..6b049d69 100644
--- a/user/advanced-configuration/rpc-policy.md
+++ b/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/
-
diff --git a/user/advanced-configuration/salt.md b/user/advanced-configuration/salt.md
index e8427443..4111d8a7 100644
--- a/user/advanced-configuration/salt.md
+++ b/user/advanced-configuration/salt.md
@@ -9,7 +9,7 @@ permalink: /doc/salt/
 Since the Qubes R3.1 release we have included the Salt (also called SaltStack)
 management engine in dom0 as default (with some states already configured).
 Salt allows administrators to easily configure their systems.
-In this guide we will show how it is set up and how you can modify it for your 
+In this guide we will show how it is set up and how you can modify it for your
 own purpose.
 
 In the current form the **API is provisional** and subject to change between
@@ -20,48 +20,48 @@ In the current form the **API is provisional** and subject to change between
 This document is not meant to be comprehensive Salt documentation; however,
 before writing anything it is required you have at least *some* understanding of
 basic Salt-related vocabulary.
-For more exhaustive documentation, visit [official site][salt-doc], though we 
-must warn you that it is not easy to read if you just start working with Salt 
+For more exhaustive documentation, visit [official site][salt-doc], though we
+must warn you that it is not easy to read if you just start working with Salt
 and know nothing.
 
 ### The Salt Architecture
 
 Salt is a client-server model, where the server (called *master*) manages
 its clients (called *minions*).
-In typical situations, it is intended that the administrator interacts only 
+In typical situations, it is intended that the administrator interacts only
 with the master and keeps the configurations there.
 In Qubes, we don't have a master.
-Instead we have one minion which resides in `dom0` and manages domains from 
+Instead we have one minion which resides in `dom0` and manages domains from
 there.
 This setup is also supported by Salt.
 
-Salt is a management engine (similar to Ansible, Puppet, and Chef), that 
+Salt is a management engine (similar to Ansible, Puppet, and Chef), that
 enforces a particular state of a minion system.
 A *state* is an end effect *declaratively* expressed by the administrator.
 This is the most important concept in the entire engine.
 All configurations (i.e., the states) are written in YAML.
 
 A *pillar* is a data back-end declared by the administrator.
-When states become repetitive, instead of pure YAML they can be written using a 
-template engine (preferably Jinja2); which can use data structures specified in 
+When states become repetitive, instead of pure YAML they can be written using a
+template engine (preferably Jinja2); which can use data structures specified in
 pillars.
 
-A *formula* is a ready to use, packaged solution that combines a state and a 
+A *formula* is a ready to use, packaged solution that combines a state and a
 pillar (possibly with some file templates and other auxiliary files).
 There are many formulas made by helpful people all over the Internet.
 
 A *grain* is some data that is also available in templates, but its value is not
 directly specified by administrator.
-For example, the distribution (e.g., `"Debian"` or `"Gentoo"`) is a value of 
-the grain `"os"`. It also contains other information about the kernel, 
+For example, the distribution (e.g., `"Debian"` or `"Gentoo"`) is a value of
+the grain `"os"`. It also contains other information about the kernel,
 hardware, etc.
 
 A *module* is a Python extension to Salt that is responsible for actually
 enforcing the state in a particular area.
 It exposes some *imperative* functions for the administrator.
-For example, there is a `system` module that has a `system.halt` function that, 
+For example, there is a `system` module that has a `system.halt` function that,
 when issued, will immediately halt a domain.
-There is another function called `state.highstate` which will synchronize the 
+There is another function called `state.highstate` which will synchronize the
 state of the system with the administrator's configuration/desires.
 
 ### Configuration
@@ -73,9 +73,9 @@ A state is written in YAML and looks like this:
 
     stateid:
       cmd.run:  #this is the execution module. in this case it will execute a command on the shell
-      - name: echo 'hello world' #this is a parameter of the state. 
+      - name: echo 'hello world' #this is a parameter of the state.
 
-The stateid has to be unique throughout all states running for a minion and can 
+The stateid has to be unique throughout all states running for a minion and can
 be used to order the execution of the references state.
 `cmd.run` is an execution module.
 It executes a command on behalf of the administrator.
@@ -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 [executing shell commands][salt-doc-states-cmd].
+- For [installing and uninstalling][salt-doc-states-pkg] packages.
+- For [executing shell commands][salt-doc-states-cmd].
 
 With these three states you can define most of the configuration of a VM.
 
@@ -114,14 +114,14 @@ You can also [order the execution][salt-doc-states-order] of your states:
       - order: 1
 
 The order of execution will be `A, B, C, D`.
-The official documentation has more details on the 
+The official documentation has more details on the
 [require][salt-doc-states-req] and [order][salt-doc-states-ord] arguments.
 
 #### State Files
 
 When configuring a system you will write one or more state files (`*.sls`) and
 put (or symlink) them into the main Salt directory `/srv/salt/`.
-Each state file contains multiple states and should describe some unit of 
+Each state file contains multiple states and should describe some unit of
 configuration (e.g., a state file `mail.sls` could setup a VM for e-mail).
 
 #### Top Files
@@ -138,7 +138,7 @@ Their structure looks like this:
 In most cases, the environment will be called `base`.
 The `target_matching_clause` will be used to select your minions (VMs).
 It can be either the name of a VM or a regular expression.
-If you are using a regular expressions, you need to give Salt a hint you are 
+If you are using a regular expressions, you need to give Salt a hint you are
 doing so:
 
     environment:
@@ -147,9 +147,9 @@ doing so:
       - statefile
 
 For each target you can write a list of state files.
-Each line is a path to a state file (without the `.sls` extension) relative to 
+Each line is a path to a state file (without the `.sls` extension) relative to
 the main directory.
-Each `/` is exchanged with a `.`, so you can't reference files or directories 
+Each `/` is exchanged with a `.`, so you can't reference files or directories
 with a `.` in their name.
 
 ### Enabling Top Files and Applying the States
@@ -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.)
 
@@ -178,13 +186,13 @@ To apply the states to dom0 and all VMs:
 You will sometimes find yourself writing repetitive states.
 To solve this, there is the ability to template files or states.
 This is most commonly done with [Jinja][jinja].
-Jinja is similar to Python and in many cases behaves in a similar fashion, but 
+Jinja is similar to Python and in many cases behaves in a similar fashion, but
 there are sometimes differences when, for example, you set some variable inside
 a loop: the variable outside will not get changed.
 Instead, to get this behavior, you would use a `do` statement.
 So you should take a look at the [Jinja API documentation][jinja-tmp].
-Documentation about using Jinja to directly call Salt functions and get data 
-about your system can be found in the official 
+Documentation about using Jinja to directly call Salt functions and get data
+about your system can be found in the official
 [Salt documentation][jinja-call-salt-functions].
 
 ## Salt Configuration, QubesOS layout
@@ -192,7 +200,7 @@ about your system can be found in the official
 All Salt configuration files are in the `/srv/` directory, as usual.
 The main directory is `/srv/salt/` where all state files reside.
 States are contained in `*.sls` files.
-However, the states that are part of the standard Qubes distribution are mostly 
+However, the states that are part of the standard Qubes distribution are mostly
 templates and the configuration is done in pillars from formulas.
 
 The formulas are in `/srv/formulas`, including stock formulas for domains in
@@ -206,7 +214,7 @@ It accepts all the same arguments of the vanilla tool.
 
 Salt in Qubes can be used to configure VMs from dom0.
 Simply set the VM name as the target minion name in the top file.
-You can also use the `qubes` pillar module to select VMs with a particular 
+You can also use the `qubes` pillar module to select VMs with a particular
 property (see below).
 If you do so, then you need to pass additional arguments to the `qubesctl` tool:
 
@@ -228,16 +236,15 @@ 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` 
+The actual configuration is applied using `salt-ssh` (running over `qrexec`
 instead of `ssh`).
-Which means you don't need to install anything special in a VM you want to 
+Which means you don't need to install anything special in a VM you want to
 manage.
 Additionally, for each target VM, `salt-ssh` is started from a temporary VM.
-This way dom0 doesn't directly interact with potentially malicious target VMs; 
-and in the case of a compromised Salt VM, because they are temporary, the 
+This way dom0 doesn't directly interact with potentially malicious target VMs;
+and in the case of a compromised Salt VM, because they are temporary, the
 compromise cannot spread from one VM to another.
 
 Beginning with Qubes 4.0 and after [QSB #45], we implemented two changes:
@@ -273,16 +280,16 @@ 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 `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 `vcpus` flag informs Salt how many Virtual CPUs should be allocated to the 
+- 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 `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
   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 
+As you will notice, the options are the same (or very similar) to those used in
 `qvm-prefs`.
 
 This should be put in `/srv/salt/my-new-vm.sls` or another `.sls` file.
@@ -292,21 +299,25 @@ A separate `*.top` file should be also written:
       dom0:
         - my-new-vm
 
-**Note** The third line should contain the name of the previous state file, 
+**Note** The third line should contain the name of the previous state file,
 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
 
 Lets make sure that the `mc` package is installed in all templates.
-Similar to the previous example, you need to create a state file 
+Similar to the previous example, you need to create a state file
 (`/srv/salt/mc-everywhere.sls`):
 
     mc:
@@ -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,22 +488,24 @@ 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.
-   Adjust to your available RAM.
-   The default is 4, and the GUI updater sets it to 1.
- - `--targets=vm1,vm2,...` --- Limit to specific VMs, instead of all of them.
-   (Use instead of `--templates` or `--standalones`.)
- - `--show-output` --- Show an update summary instead of just OK/FAIL.
+- `--max-concurrency` --- Limits how many templates are updated at the same time.
+  Adjust to your available RAM.
+  The default is 4, and the GUI updater sets it to 1.
+- `--targets=vm1,vm2,...` --- Limit to specific VMs, instead of all of them.
+  (Use instead of `--templates` or `--standalones`.)
+- `--show-output` --- Show an update summary instead of just OK/FAIL.
 
 For other options, see `qubesctl --help`.
 
 ## The `qubes` Pillar Module
 
-Additional pillar data is available to ease targeting configurations (for example all templates). 
+Additional pillar data is available to ease targeting configurations (for example all templates).
 
 **Note:** This list is subject to change in future releases.
 
@@ -495,10 +513,10 @@ Additional pillar data is available to ease targeting configurations (for exampl
 
 VM type. Possible values:
 
- - `admin` - Administration domain (`dom0`)
- - `template` - Template VM
- - `standalone` - Standalone VM
- - `app` - Template based AppVM
+- `admin` - Administration domain (`dom0`)
+- `template` - Template VM
+- `standalone` - Standalone VM
+- `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`.
@@ -517,12 +534,14 @@ If the log does not contain useful information:
 1. Run `sudo qubesctl --skip-dom0 --target=VM_NAME state.highstate`
 2. When your VM is being started (yellow) press Ctrl-z on qubesctl.
 3. Open terminal in disp-mgmt-VM_NAME.
-4. Look at /etc/qubes-rpc/qubes.SaltLinuxVM - this is what is 
+4. Look at /etc/qubes-rpc/qubes.SaltLinuxVM - this is what is
    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,8 +553,10 @@ 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 states][salt-doc-states] ([files][salt-doc-states-file], [commands][salt-doc-states-cmd], 
+- [Salt documentation][salt-doc]
+- [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]
-* [Jinja templates][jinja]
-* [Qubes specific modules][salt-qvm-doc]
-* [Formulas for default Qubes VMs][salt-virtual-machines-states]
+- [Top files][salt-doc-top]
+- [Jinja templates][jinja]
+- [Qubes specific modules][salt-qvm-doc]
+- [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
diff --git a/user/advanced-configuration/secondary-storage.md b/user/advanced-configuration/secondary-storage.md
index 52aeb3fb..b189f8e9 100644
--- a/user/advanced-configuration/secondary-storage.md
+++ b/user/advanced-configuration/secondary-storage.md
@@ -8,15 +8,14 @@ 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. 
+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.
 
 These steps assume you have already created a separate [volume group](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/logical_volume_manager_administration/vg_admin#VG_create) and [thin pool](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/logical_volume_manager_administration/thinly_provisioned_volume_creation) (not thin volume) for your HDD.
@@ -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:
 
-    #  is a freely chosen pool name
-    #  is LVM volume group name
-    #  is LVM thin pool name
-    qvm-pool --add  lvm_thin -o volume_group=,thin_pool=,revisions_to_keep=2
-    
+```shell_session
+#  is a freely chosen pool name
+#  is LVM volume group name
+#  is LVM thin pool name
+qvm-pool --add  lvm_thin -o volume_group=,thin_pool=,revisions_to_keep=2
+```
+
 Now, you can create qubes in that pool:
 
-    qvm-create -P  --label red 
+```
+qvm-create -P  --label red 
+```
 
 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   
-    qvm-remove 
+```
+qvm-clone -P   
+qvm-remove 
+```
 
 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  template 
+```
+qvm-prefs  template 
+```
 
 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 :
 
-    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  (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/
-
diff --git a/user/advanced-configuration/usb-qubes.md b/user/advanced-configuration/usb-qubes.md
index 8a75ab53..64da9c3e 100644
--- a/user/advanced-configuration/usb-qubes.md
+++ b/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.
-     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.
-     If you find a free controller, note its name and proceed to step 2.
- 2.  Create a new qube.
-     Give it an appropriate name and color label (recommended: `sys-usb`, red).
- 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.
-     Move it to the "Selected" list by highlighting it and clicking the single arrow `>` button.
+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.
+   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.
+2. Create a new qube.
+   Give it an appropriate name and color label (recommended: `sys-usb`, red).
+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.
+   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.
-     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.
+   **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.
 
- 4.  Click `OK`.
-     Restart the qube.
- 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.)
+4. Click `OK`.
+   Restart the qube.
+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.)
 
 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,20 +116,25 @@ 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
-    
-(Change `sys-usb` to your desired USB qube.)
+```
+sys-usb dom0 allow
+```
 
+(Change `sys-usb` to your desired USB qube.)
 
 ## How to hide all USB controllers from dom0 ##
 
@@ -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.
- 2. Find the line that begins with `GRUB_CMDLINE_LINUX`.
- 3. Add `rd.qubes.hide_all_usb` to that line.
- 4. Save and close the file.
- 5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
- 6. Reboot.
+  1. Open the file `/etc/default/grub` in dom0.
+  2. Find the line that begins with `GRUB_CMDLINE_LINUX`.
+  3. Add `rd.qubes.hide_all_usb` to that line.
+  4. Save and close the file.
+  5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
+  6. Reboot.
 
- * 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.
+* 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.
 
 ## Removing a USB qube ##
 
 **Warning:** This procedure will result in your USB controller(s) being attached directly to dom0.
 
- * GRUB2
- 
- 1. Shut down the USB qube.
- 2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
- 3. Open the file `/etc/default/grub` in dom0.
- 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.
- 6. Save and close the file.
- 7. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
- 8. Reboot.
+* GRUB2
 
- * 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 `/etc/default/grub` in dom0.
+  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.
+  6. Save and close the file.
+  7. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
+  8. Reboot.
 
+* 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.
 
 [remove your USB-qube]: #removing-a-usb-qube
 [security implications]: /doc/device-handling-security/#usb-security
diff --git a/user/common-tasks/backup-emergency-restore-v2.md b/user/common-tasks/backup-emergency-restore-v2.md
index 6c03bd3e..2dce6286 100644
--- a/user/common-tasks/backup-emergency-restore-v2.md
+++ b/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,13 +41,13 @@ 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/
     [user@restore vm1]$ openssl dgst -sha512 -hmac "your_passphrase" private.img.000
     HMAC-SHA512(private.img.000)= cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
-    [user@restore vm1]$ cat private.img.000.hmac 
+    [user@restore vm1]$ cat private.img.000.hmac
     (stdin)= cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
     ~~~
 
@@ -59,14 +59,14 @@ 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
     ~~~
 
   **Note:** For multi-part files, a loop can be used:
- 
+
   ~~~
   find -name 'private.img.*' | sort -V | while read f; do
     openssl enc -d -pass pass:your_passphrase -aes-256-cbc -in $f -out
@@ -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`.
-    3.  `tar --new-volume-script=./new-volume-script -xvf private.img.dec.000`.
+    2. `chmod +x new-volume-script`.
+    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:
-
-    https://github.com/QubesOS/qubes-doc.git
+  this file in Git repository housing all the documentation on [Github](https://github.com/QubesOS/qubes-doc.git)
diff --git a/user/common-tasks/backup-emergency-restore-v3.md b/user/common-tasks/backup-emergency-restore-v3.md
index 2718b5d4..a403e856 100644
--- a/user/common-tasks/backup-emergency-restore-v3.md
+++ b/user/common-tasks/backup-emergency-restore-v3.md
@@ -44,7 +44,7 @@ any GNU/Linux system with the following procedure.
 
         [user@restore ~]$ openssl dgst -sha512 -hmac "your_passphrase" backup-header
         HMAC-SHA512(backup-header)= 5b266783e116fe3b2601a54c249ca5f5f96d421dfe6828eeaeb2dcd014e9e945c27b3d7b0f952f5d55c927318906d9c360f387b0e1f069bb8195e96543e2969c
-        [user@restore ~]$ cat backup-header.hmac 
+        [user@restore ~]$ cat backup-header.hmac
         (stdin)= 5b266783e116fe3b2601a54c249ca5f5f96d421dfe6828eeaeb2dcd014e9e945c27b3d7b0f952f5d55c927318906d9c360f387b0e1f069bb8195e96543e2969c
 
     **Note:** The hash values should match. If they do not match, then the
@@ -69,7 +69,7 @@ any GNU/Linux system with the following procedure.
         encrypted=True
         compressed=True
         compression-filter=gzip
-  
+
     **Note:** If you see `version=2` here, go to [Emergency Backup Recovery -
     format version 2](/doc/backup-emergency-restore-v2/) instead.
 
@@ -78,7 +78,7 @@ any GNU/Linux system with the following procedure.
         [user@restore ~]$ cd vm1/
         [user@restore vm1]$ openssl dgst -sha512 -hmac "your_passphrase" private.img.000
         HMAC-SHA512(private.img.000)= cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
-        [user@restore vm1]$ cat private.img.000.hmac 
+        [user@restore vm1]$ cat private.img.000.hmac
         (stdin)= cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
 
     **Note:** The hash values should match. If they do not match, then the
@@ -137,4 +137,3 @@ any GNU/Linux system with the following procedure.
     repository:
 
         https://github.com/QubesOS/qubes-doc.git
-
diff --git a/user/common-tasks/backup-emergency-restore-v4.md b/user/common-tasks/backup-emergency-restore-v4.md
index 28361135..e87a5299 100644
--- a/user/common-tasks/backup-emergency-restore-v4.md
+++ b/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
 -------------------------
 
@@ -53,7 +52,7 @@ any GNU/Linux system.
 
  4. Verify the signature on the `scrypt` RPM.
 
-        [user@restore ~]$ rpm -K scrypt-*.rpm 
+        [user@restore ~]$ rpm -K scrypt-*.rpm
         scrypt-*.rpm: digests signatures OK
 
     The message `digests signatures OK` means that both the digest (i.e., the
@@ -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/
-
diff --git a/user/common-tasks/backup-restore.md b/user/common-tasks/backup-restore.md
index 60e63ab3..ac59da61 100644
--- a/user/common-tasks/backup-restore.md
+++ b/user/common-tasks/backup-restore.md
@@ -25,7 +25,7 @@ Backing up changes to dom0
 --------------------------
 
 When backing up dom0 using the Qubes backup tool (explained below), only the home directory is backed up.
-Therefore, if there are files outside of the home directory you wish to save, you should copy them into the home directory prior to creating a backup. 
+Therefore, if there are files outside of the home directory you wish to save, you should copy them into the home directory prior to creating a backup.
 Here is an example of how to back up Qubes config files and RPC policies:
 
     $ mkdir -p ~/backup/etc/qubes/
@@ -48,7 +48,7 @@ Creating a backup
 
    You may choose whether to compress backups by checking or unchecking the **Compress the backup** box.
    Normally this should be left on unless you have a specific reason otherwise.
-   
+
    Once you have selected all desired VMs, click **Next**.
 
 3. Select the destination for the backup:
@@ -56,7 +56,7 @@ Creating a backup
    If you wish to send your backup to a (currently running) VM, select the VM in the drop-down box next to **Target AppVM**.
    If you wish to send your backup to a [USB mass storage device](/doc/usb/), you can use the directory selection widget to mount a connected device (under "Other locations" item on the left); or first mount the device in a VM, then select the mount point inside that VM as the backup destination.
 
-   You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup. 
+   You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup.
    For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply browse to it using the convenient directory selection dialog (`...`) at the right.
    This destination directory must already exist.
    If it does not exist, you must create it manually prior to backing up.
@@ -68,7 +68,7 @@ Creating a backup
    **Note:** The supplied passphrase is used for **both** encryption/decryption and integrity verification.
 
    At this point, you may also choose whether to save your settings by checking or unchecking the **Save settings as default backup profile** box.
-   
+
    **Warning: Saving the settings will result in your backup passphrase being saved in plaintext in dom0, so consider your threat model before checking this box.**
 
 4. You will now see the summary of VMs to be backed up.
@@ -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
 -----------------------
 
@@ -95,31 +94,31 @@ This brings up the **Qubes Restore VMs** window.
    - If your backup is located on a [USB mass storage device](/doc/usb/), attach it first to another VM or select `sys-usb` in the next item.
    - If your backup is located in a (currently running) VM, select the VM in the drop-down box next to **AppVM**.
 
-   You must also specify the directory and filename of the backup (or a command to be executed in a VM) in the **Backup file** field. 
+   You must also specify the directory and filename of the backup (or a command to be executed in a VM) in the **Backup file** field.
    If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3.
    For example, if you had chosen the `~/backups` directory of a VM as your destination in step 3, you would now select the same VM and again browse to (using `...`) the `backups` folder.
    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.
-   2.  **ignore username mismatch**: This option applies only to the restoration of dom0's home directory.
+   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.
    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.
 
-4. If your backup is encrypted, you must check the **Encrypted backup** box. 
+4. If your backup is encrypted, you must check the **Encrypted backup** box.
 If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here.
 
-   **Note:** The passphrase which was supplied when the backup was created was used for **both** encryption/decryption and integrity verification. 
+   **Note:** The passphrase which was supplied when the backup was created was used for **both** encryption/decryption and integrity verification.
    If the backup was not encrypted, the supplied passphrase is used only for integrity verification.
    All backups made from a Qubes R4.0 system will be encrypted.
 
-5. You will now see the summary of VMs to be restored. 
+5. You will now see the summary of VMs to be restored.
 If there are any issues preventing the restore, they will be listed here and the **Next** button grayed out.
 
-6. When you are ready, click **Next**. 
-Qubes will proceed to restore from your backup. 
+6. When you are ready, click **Next**.
+Qubes will proceed to restore from your backup.
 Once the progress bar has completed, you may click **Finish**.
 
 **Note:** When restoring from a dom0 backup, a new directory will be created in the current dom0 home directory, and the contents from the backup will be placed inside this new directory.
@@ -128,20 +127,18 @@ 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. 
+The Qubes backup system has been designed with emergency disaster recovery in 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.
 
 Refer to the following for emergency restore of a backup created on:
 
- * [Qubes R4 or newer](/doc/backup-emergency-restore-v4/)
- * [Qubes R3](/doc/backup-emergency-restore-v3/)
- * [Qubes R2 or older](/doc/backup-emergency-restore-v2/)
-
+- [Qubes R4 or newer](/doc/backup-emergency-restore-v4/)
+- [Qubes R3](/doc/backup-emergency-restore-v3/)
+- [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. 
- (Depending on the decryption passphrase you use for your system drive, this may necessitate selecting a stronger 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. 
- For example, when you attempt to retrieve a recent backup, the adversary may instead give you a very old backup containing a compromised VM. 
+- 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).
- * If working with symlinks, note the issues described in [this thread](https://groups.google.com/d/topic/qubes-users/EITd1kBHD30/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).
diff --git a/user/common-tasks/block-devices.md b/user/common-tasks/block-devices.md
index a3bda98f..8ad26fbe 100644
--- a/user/common-tasks/block-devices.md
+++ b/user/common-tasks/block-devices.md
@@ -9,21 +9,20 @@ 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.)
 
 Qubes OS supports the ability to attach a USB drive (or just its partitions) to any qube easily, no matter which qube handles the USB controller.
 
-Attaching USB drives is integrated into the Devices Widget: ![device manager icon]  
+Attaching USB drives is integrated into the Devices Widget: ![device manager icon]
 Simply insert your USB drive and click on the widget.
 You will see multiple entries for your USB drive; typically, `sys-usb:sda`, `sys-usb:sda1`, and `sys-usb:2-1` for example.
 Entries starting with a number (e.g. here `2-1`) are the [whole usb-device][USB].
@@ -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
-    sudo mount /dev/xvdi2 mnt
+```
+cd ~
+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:
-    
-        qvm-block
-    
+1. In a dom0 console (running as a normal user), list all available block devices:
+
+    ```
+    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:
+
+    ```
+    qvm-block attach work sys-usb:sdb
+    ```
 
- 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
-    
     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.
-    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:
-    
-        cd ~
-        mkdir mnt
-        sudo mount /dev/xvdi mnt
-    
+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 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:
 
- 4. When you finish using the block device, click the eject button or right-click and select **Unmount**.
+    ```
+    cd ~
+    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**.
 
     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.
-    You can use any device as long as it will be detected under the same name (for example, `sdb`).
+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`).
 
- 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`).
-    You can get it from the `qvm-block` listing:
+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`).
+   You can get it from the `qvm-block` listing:
 
-        [user@dom0 ~]$ qvm-block
-        sys-usb:sda DataTraveler_2.0 () 246 MiB (attached to 'testvm' as 'xvdi')
-        [user@dom0 ~]$ sudo xl block-attach testvm phy:/dev/sda backend=sys-usb xvdi
+    ```shell_session
+    [user@dom0 ~]$ qvm-block
+    sys-usb:sda DataTraveler_2.0 () 246 MiB (attached to 'testvm' as 'xvdi')
+    [user@dom0 ~]$ sudo xl block-attach testvm phy:/dev/sda backend=sys-usb xvdi
+    ```
 
     In above example, all `xl block-attach` parameters can be deduced from the 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
-        BACKEND:DEVID  DESCRIPTION  USED BY
-        sourceVM:loop0 /path/to/file
+    ```shell_session
+    ~]$ qvm-block
+    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
-
diff --git a/user/common-tasks/copy-from-dom0.md b/user/common-tasks/copy-from-dom0.md
index dfe2e467..fa6b6012 100644
--- a/user/common-tasks/copy-from-dom0.md
+++ b/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  
+```
+qvm-copy-to-vm  
+```
 
 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  'cat /path/to/file_in_src_domain' > /path/to/file_name_in_dom0
+```
+qvm-run --pass-io  '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  'cat > /path/to/file_name_in_appvm'
-
+```
+cat /path/to/file_in_dom0 | qvm-run --pass-io  'cat > /path/to/file_name_in_appvm'
+```
diff --git a/user/common-tasks/device-handling.md b/user/common-tasks/device-handling.md
index 82cd6458..a40c4740 100644
--- a/user/common-tasks/device-handling.md
+++ b/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
-
diff --git a/user/common-tasks/disposablevm.md b/user/common-tasks/disposablevm.md
index 2bb5a3d8..54804767 100644
--- a/user/common-tasks/disposablevm.md
+++ b/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. 
+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,21 +48,25 @@ 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  template_for_dispvms True
+```
+qvm-prefs  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.
 
-You can change this behaviour for individual VMs: in the Application Menu, open Qube Settings for the VM in question and go to the "Advanced" tab. 
+You can change this behaviour for individual VMs: in the Application Menu, open Qube Settings for the VM in question and go to the "Advanced" tab.
 Here you can edit the "Default 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  default_dispvm 
+```
+qvm-prefs  default_dispvm 
+```
 
 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.
 
-NetVM and firewall rules for DisposableVM Templates can be set as they can for a normal VM. 
+NetVM and firewall rules for DisposableVM Templates can be set as they can for a normal VM.
 By default a DisposableVM will inherit the NetVM and firewall settings of the DisposableVM Template on which it is based.
 This is a change in behaviour from R3.2, where DisposableVMs would inherit the settings of the AppVM from which they were launched.
 Therefore, launching a DisposableVM from an AppVM will result in it using the network/firewall settings of the DisposableVM Template on which it is based.
@@ -75,40 +77,43 @@ This means if you have changed anon-whonix's `default_dispvm` to use the system
 
 A DisposableVM launched from the Start Menu inherits the NetVM and firewall settings of the DisposableVM Template on which it is based.
 Note that changing the "NetVM" setting for the system default DisposableVM Template *does* affect the NetVM of DisposableVMs launched from the Start Menu.
-Different DisposableVM Templates with individual NetVM settings can be added to the Start Menu. 
+Different DisposableVM Templates with individual NetVM settings can be added to the Start Menu.
 
 **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  appmenus-dispvm 1
+```
+qvm-features  appmenus-dispvm 1
+```
 
 To launch a DisposableVM Template from the command line, in dom0 please type the following:
-    
-    qvm-run --dispvm= --service qubes.StartApp+NameOfApp
 
+```
+qvm-run --dispvm= --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. 
-This app is running in its own dedicated VM -- a DisposableVM created for the purpose of viewing or editing this very file. 
-Once you close the viewing application the whole DisposableVM will be destroyed. 
+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.
+This app is running in its own dedicated VM -- a DisposableVM created for the purpose of viewing or editing this very file.
+Once you close the viewing application the whole DisposableVM will be destroyed.
 If you have edited the file and saved the changes, the changed file will be saved back to the original AppVM, overwriting the original.
 
 ![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**. 
-Wait a few seconds until a web browser starts. 
-Once you close the viewing application the whole DisposableVM will be destroyed. 
+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**.
+Wait a few seconds until a web browser starts.
+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,11 +123,10 @@ 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. 
+The DisposableVM will stay running so long as the process which started the DisposableVM has not exited.
 Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details [here](https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009)).
 Starting an arbitrary program can be done from an AppVM by running
 
@@ -132,11 +136,10 @@ 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. 
+The DisposableVM will stay running so long as the process which started the DisposableVM has not exited.
 Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details [here](https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009)).
 It is possible to start an arbitrary application in a DisposableVM directly from dom0 by running:
 
@@ -147,8 +150,7 @@ $ qvm-run --dispvm= --service qubes.StartApp+xterm
 The label color will be inherited from ``.
 (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,10 +166,12 @@ This will create a new DisposableVM based on ``, 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: allow
 ~~~
-This line means: 
+
+This line means:
 - FROM: Any VM
 - TO: A DisposableVM based on ``
 - WHAT: Allow sending an "Open URL" request
@@ -176,13 +180,11 @@ In other words, any VM will be allowed to create a new DisposableVM based on ``. 
+Each qube has its own menu directory under the scheme `Domain: `.
 After navigating into one of these directories, simply click on the application you'd like to start:
 
 ![menu1.png](/attachment/wiki/GettingStarted/r4.0-menu1.png)
 
 ![menu2.png](/attachment/wiki/GettingStarted/r4.0-menu2.png)
 
-By default, each qube's menu contains only a few shortcuts. 
-If you'd like to add more, enter the qube's **Qube Settings** and add them on the Applications tab. 
+By default, each qube's menu contains only a few shortcuts.
+If you'd like to add more, enter the qube's **Qube Settings** and add them on the Applications tab.
 
 To start apps from the terminal in dom0, type:
 
-    $ qvm-run   [arguments]
+```shell_session
+$ qvm-run   [arguments]
+```
 
 e.g.:
 
-    $ qvm-run untrusted firefox
-    
-This command will start the qube if it is not already running.
+```shell_session
+$ qvm-run untrusted firefox
+```
 
+This command will start the qube if it is not already running.
 
 Adding, removing, and listing qubes
 -----------------------------------
@@ -117,26 +118,24 @@ 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-remove`
- - `qvm-ls`
-
+- `qvm-create`
+- `qvm-remove`
+- `qvm-ls`
 
 How many qubes do I need?
 -------------------------
 
-That's a great question, but there's no one-size-fits-all answer. 
-It depends on the structure of your digital life, and this is at least a little different for everyone. 
+That's a great question, but there's no one-size-fits-all answer.
+It depends on the structure of your digital life, and this is at least a little different for everyone.
 If you plan on using your system for work, then it also depends on what kind of job you do.
 
-It's a good idea to start out with the three qubes created automatically by the installer: work, personal, and untrusted. 
-If and when you start to feel that some activity just doesn't fit into any of your existing qubes, or you want to partition some part of your life, you can easily create a new qube for it. 
+It's a good idea to start out with the three qubes created automatically by the installer: work, personal, and untrusted.
+If and when you start to feel that some activity just doesn't fit into any of your existing qubes, or you want to partition some part of your life, you can easily create a new qube for it.
 You'll also be able to easily [copy][copy-files] any files you need to the newly created qube.
 
 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 Moving Files Between Domains][copy-files]
- * [Copying from (and to) dom0]
- * [Fullscreen Mode]
- * [DisposableVMs]
- * [Device Handling] (block, USB, and PCI devices)
+- [Copying and Pasting Text Between Domains][copy-paste]
+- [Copying and Moving Files Between Domains][copy-files]
+- [Copying from (and to) dom0]
+- [Fullscreen Mode]
+- [DisposableVMs]
+- [Device Handling] (block, USB, and PCI devices)
 
 If you encounter any problems, please visit the [Help, Support, and Mailing Lists] page.
 
diff --git a/user/common-tasks/optical-discs.md b/user/common-tasks/optical-discs.md
index 2631d2e6..cacbb0cc 100644
--- a/user/common-tasks/optical-discs.md
+++ b/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`.
-
diff --git a/user/common-tasks/pci-devices.md b/user/common-tasks/pci-devices.md
index c6fd76ff..ae38f2f9 100644
--- a/user/common-tasks/pci-devices.md
+++ b/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.
@@ -33,57 +32,60 @@ Limits imposed by the PC and VT-d architectures may require all functions belong
 This requirement can be dropped with the `no-strict-reset` option during attachment, bearing in mind the aforementioned [security considerations].
 In the steps below, you can tell if this is needed if you see the BDF for the same device listed multiple times with only the number after the "." changing.
 
-While PCI device can only be used by one powered on VM at a time, it *is* possible to *assign* the same device to more than one VM at a time. 
+While PCI device can only be used by one powered on VM at a time, it *is* possible to *assign* the same device to more than one VM at a time.
 This means that you can use the device in one VM, shut that VM down, start up a different VM (to which the same device is 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"!
-     - 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!)
+   - 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`.
+   - 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.
- 3. Select a device you want to attach to the qube and click the single arrow right! (`>`)
- 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.
- 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!
+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! (`>`)
+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.
+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!
 
-
-## `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. 
+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.
 
-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. 
-    Replace `` with your full device, for example `0000:00:1c.2`:
+- 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 `` with your full device, for example `0000:00:1c.2`:
 
-        echo  > /sys/bus/pci/drivers/pciback/unbind
-        MODALIAS=`cat /sys/bus/pci/devices//modalias`
-        MOD=`modprobe -R $MODALIAS | head -n 1`
-        echo  > /sys/bus/pci/drivers/$MOD/bind
-
-    It is **strongly discouraged to reattach PCI devices to dom0**, especially if they don't support resetting!
+    ```
+    echo  > /sys/bus/pci/drivers/pciback/unbind
+    MODALIAS=`cat /sys/bus/pci/devices//modalias`
+    MOD=`modprobe -R $MODALIAS | head -n 1`
+    echo  > /sys/bus/pci/drivers/$MOD/bind
+    ```
 
+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
-
diff --git a/user/common-tasks/software-update-dom0.md b/user/common-tasks/software-update-dom0.md
index daecefbb..19e2fca0 100644
--- a/user/common-tasks/software-update-dom0.md
+++ b/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=` 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/
-
diff --git a/user/common-tasks/software-update-domu.md b/user/common-tasks/software-update-domu.md
index f8521a67..d19ea1aa 100644
--- a/user/common-tasks/software-update-domu.md
+++ b/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.
- 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 ` on Fedora, `sudo apt install ` on Debian).
- 4. Shut down the TemplateVM.
- 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.
+1. Start the TemplateVM.
+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 ` on Fedora, `sudo apt install ` on Debian).
+4. Shut down the TemplateVM.
+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.
     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-*-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-*-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-*-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=` 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
-* `*-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
+- `*-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
+- `*-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,15 +86,13 @@ 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): 
+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):
 
 ~~~
 sudo dnf config-manager --set-enabled rpmfusion-free
@@ -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