Merge branch 'pierwill-common-tasks-semantic-linefeed-fixes'

QubesOS/qubes-issues#2639

user/common-tasks/block-devices.md

@@ -26,7 +26,9 @@ Qubes OS supports the ability to attach a USB drive (or just its partitions) to
 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]. Entries without a number (e.g. here `sda`) are the whole block-device. Other entries are partitions of that block-device (e.r. here `sda1`).
+Entries starting with a number (e.g. here `2-1`) are the [whole usb-device][USB].
+Entries without a number (e.g. here `sda`) are the whole block-device.
+Other entries are partitions of that block-device (e.r. here `sda1`).
 
 The simplest option is to attach the entire block drive.
 In our example, this is `sys-usb:sda`, so hover over it.
@@ -40,7 +42,8 @@ See below for more detailed steps.
 
 ## 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:
+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
@@ -60,9 +63,11 @@ To specify this device node name, you need to use the command line tool and its
 
 The command-line tool you may use to mount whole USB drives or their partitions is `qvm-block`, a shortcut for `qvm-device block`.
 
-`qvm-block` won't recognise your device by any given name, but rather the device-node the sourceVM assigns. So make sure you have the drive available in the sourceVM, then list the available block devices (step 1.) to find the corresponding device-node.
+`qvm-block` won't recognise your device by any given name, but rather the device-node the sourceVM assigns.
+So make sure you have the drive available in the sourceVM, then list the available block devices (step 1.) to find the corresponding device-node.
 
-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`)
+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:
     
@@ -154,13 +159,16 @@ To attach a file as block device to another qube, first turn it into a loopback
 
         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.
+    [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. Click the Device Manager ![device manager icon] and select the `loop0`-device to attach it to another qube.
+ 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:
 
-    In dom0, run `qvm-block` to display known block devices. The newly created loop device should show up:
+    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
@@ -177,12 +185,15 @@ To attach a file as block device to another qube, first turn it into a loopback
 
 ## 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).)
+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 ###
 
-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. (The next one tried will be `xvdj`, then `xvdk`, and so on ...)
+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.
+(The next one tried will be `xvdj`, then `xvdk`, and so on ...)
 
 usage example:
 
@@ -193,7 +204,8 @@ This command will attach the partition `sda1` to `work` as `/dev/xvdz`.
 
 ### read-only ###
 
-Attach device in read-only mode. Protects the block device in case you don't trust the targetVM.
+Attach device in read-only mode.
+Protects the block device in case you don't trust the targetVM.
 
 If the device is a read-only device, this option is forced true.
 
@@ -210,7 +222,8 @@ The two commands are equivalent.
 
 ### devtype ###
 
-Usually, a block device is attached as disk. In case you need to attach a block device as cdrom, this option allows that.
+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:
 

user/common-tasks/copy-paste.md

@@ -11,23 +11,34 @@ redirect_from:
 Copy and Paste between domains
 ==============================
 
-Qubes fully supports secure copy and paste operation between domains. In order to copy a clipboard from domain A to domain B, follow those steps:
+Qubes fully supports secure copy and paste operation between domains.
+In order to copy a clipboard from domain A to domain B, follow those steps:
 
-1.  Click on the application window in domain A where you have selected text for copying. Then use the *app-specific* hot-key (or menu option) to copy this into domain's local clipboard (in other words: do the copy operation as usual, in most cases by pressing Ctrl-C).
+1.  Click on the application window in domain A where you have selected text for copying.
-2.  Then (when the app in domain A is still in focus) press Ctrl-Shift-C magic hot-key. This will tell Qubes that we want to select this domain's clipboard for *global copy* between domains.
+    Then use the *app-specific* hot-key (or menu option) to copy this into domain's local clipboard (in other words: do the copy operation as usual, in most cases by pressing Ctrl-C).
-3.  Now select the destination app, running in domain B, and press Ctrl-Shift-V, another magic hot-key that will tell Qubes to make the clipboard marked in the previous step available to apps running in domain B. This step is necessary because it ensures that only domain B will get access to the clipboard copied from domain A, and not any other domain that might be running in the system.
+2.  Then (when the app in domain A is still in focus) press Ctrl-Shift-C magic hot-key.
+    This will tell Qubes that we want to select this domain's clipboard for *global copy* between domains.
+3.  Now select the destination app, running in domain B, and press Ctrl-Shift-V, another magic hot-key that will tell Qubes to make the clipboard marked in the previous step available to apps running in domain B.
+    This step is necessary because it ensures that only domain B will get access to the clipboard copied from domain A, and not any other domain that might be running in the system.
 4.  Now, in the destination app use the app-specific key combination (usually Ctrl-V) for pasting the clipboard.
 
 Note that the global clipboard will be cleared after step \#3, to prevent accidental leakage to another domain, if the user accidentally pressed Ctrl-Shift-V later.
 
-This 4-step process might look complex, but after some little practice it really is very easy and fast. At the same time it provides the user with full control over who has access to the clipboard.
+This 4-step process might look complex, but after some little practice it really is very easy and fast.
+At the same time it provides the user with full control over who has access to the clipboard.
 
-Note that only simple plain text copy/paste is supported between AppVMs. This is discussed in a bit more detail in [this message](https://groups.google.com/group/qubes-devel/msg/57fe6695eb8ec8cd).
+Note that only simple plain text copy/paste is supported between AppVMs.
+This is discussed in a bit more detail in [this message](https://groups.google.com/group/qubes-devel/msg/57fe6695eb8ec8cd).
 
 On Copy/Paste Security
 ----------------------
 
-The scheme is *secure* because it doesn't allow other VMs to steal the content of the clipboard. However, one should keep in mind that performing a copy and paste operation from *less trusted* to *more trusted* domain can always be potentially insecure, because the data that we insert might potentially try to exploit some hypothetical bug in the destination VM (e.g. the seemingly innocent link that we copy from untrusted domain, might turn out to be, in fact, a large buffer of junk that, when pasted into the destination VM's word processor could exploit a hypothetical bug in the undo buffer). This is a general problem and applies to any data transfer between *less trusted to more trusted* domains. It even applies to copying files between physically separate machines (air-gapped) systems. So, you should always copy clipboard and data only from *more trusted* to *less trusted* domains.
+The scheme is *secure* because it doesn't allow other VMs to steal the content of the clipboard.
+However, one should keep in mind that performing a copy and paste operation from *less trusted* to *more trusted* domain can always be potentially insecure, because the data that we insert might potentially try to exploit some hypothetical bug in the destination VM (e.g.
+the seemingly innocent link that we copy from untrusted domain, might turn out to be, in fact, a large buffer of junk that, when pasted into the destination VM's word processor could exploit a hypothetical bug in the undo buffer).
+This is a general problem and applies to any data transfer between *less trusted to more trusted* domains.
+It even applies to copying files between physically separate machines (air-gapped) systems.
+So, you should always copy clipboard and data only from *more trusted* to *less trusted* domains.
 
 See also [this article](https://blog.invisiblethings.org/2011/03/13/partitioning-my-digital-life-into.html) for more information on this topic, and some ideas of how we might solve this problem in some future version of Qubes.
 
@@ -47,7 +58,8 @@ The Qubes clipboard [RPC policy] is configurable in:
 /etc/qubes-rpc/policy/qubes.ClipboardPaste
 ~~~
 
-You may wish to configure this policy in order to prevent user error. For example, if you are certain that you never wish to paste *into* your "vault" AppVM (and it is highly recommended that you do not), then you should edit the policy as follows:
+You may wish to configure this policy in order to prevent user error.
+For example, if you are certain that you never wish to paste *into* your "vault" AppVM (and it is highly recommended that you do not), then you should edit the policy as follows:
 
 ~~~
 $anyvm  vault   deny

user/common-tasks/copying-files.md

@@ -23,7 +23,8 @@ GUI
 
 2. A dialog box will appear asking for the name of the destination qube (qube B). 
 
-3. A confirmation dialog box will appear(this will be displayed by Dom0, so none of the qubes can fake your consent). After you click ok, qube B will be started if it is not already running, the file copy operation will start, and the files will be copied into the following folder in qube B:
+3. A confirmation dialog box will appear(this will be displayed by Dom0, so none of the qubes can fake your consent).
+   After you click ok, qube B will be started if it is not already running, the file copy operation will start, and the files will be copied into the following folder in qube B:
 
    `/home/user/QubesIncoming/<source>`
 
@@ -45,9 +46,15 @@ qvm-move [--without-progress] file [file]+
 On inter-qube file copy security
 ----------------------------------
 
-The scheme is *secure* because it doesn't allow other qubes to steal the files that are being copied, and also doesn't allow the source qube to overwrite arbitrary files on the destination qube. Also, Qubes's file copy scheme doesn't use any sort of virtual block devices for file copy -- instead we use Xen shared memory, which eliminates lots of processing of untrusted data. For example, the receiving qube is *not* forced to parse untrusted partitions or file systems. In this respect our file copy mechanism provides even more security than file copy between two physically separated (air-gapped) machines!
+The scheme is *secure* because it doesn't allow other qubes to steal the files that are being copied, and also doesn't allow the source qube to overwrite arbitrary files on the destination qube.
+Also, Qubes's file copy scheme doesn't use any sort of virtual block devices for file copy -- instead we use Xen shared memory, which eliminates lots of processing of untrusted data.
+For example, the receiving qube is *not* forced to parse untrusted partitions or file systems.
+In this respect our file copy mechanism provides even more security than file copy between two physically separated (air-gapped) machines!
 
-However, one should keep in mind that performing a data transfer from *less trusted* to *more trusted* qubes can always be potentially insecure, because the data that we insert might potentially try to exploit some hypothetical bug in the destination qube (e.g. a seemingly innocent JPEG that we copy from an untrusted qube might contain a specially crafted exploit for a bug in JPEG parsing application in the destination qube). This is a general problem and applies to any data transfer between *less trusted to more trusted* qubes. It even applies to the scenario of copying files between air-gapped machines. So, you should always copy data only from *more trusted* to *less trusted* qubes.
+However, one should keep in mind that performing a data transfer from *less trusted* to *more trusted* qubes can always be potentially insecure, because the data that we insert might potentially try to exploit some hypothetical bug in the destination qube (e.g. a seemingly innocent JPEG that we copy from an untrusted qube might contain a specially crafted exploit for a bug in JPEG parsing application in the destination qube).
+This is a general problem and applies to any data transfer between *less trusted to more trusted* qubes.
+It even applies to the scenario of copying files between air-gapped machines.
+So, you should always copy data only from *more trusted* to *less trusted* qubes.
 
 See also [this article](https://blog.invisiblethings.org/2011/03/13/partitioning-my-digital-life-into.html) for more information on this topic, and some ideas of how we might solve this problem in some future version of Qubes.
 

user/common-tasks/device-handling.md

@@ -11,14 +11,18 @@ redirect_from:
 
 # 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.
+This is an overview of device handling in Qubes OS.
+For specific devices ([block], [USB] and [PCI] devices), please visit their respective pages.
 
-**Important security warning:** Device handling comes with many security implications. Please make sure you carefully read and understand the **[security considerations]**.
+**Important security warning:** Device handling comes with many security implications.
+Please make sure you carefully read and understand the **[security considerations]**.
 
 
 ## Introduction ##
 
-The interface to deal with devices of all sorts was unified in Qubes 4.0 with the `qvm-device` command and the Qubes Devices Widget. In Qubes 3.X, the Qubes VM Manager dealt with attachment as well. This functionality was moved to the Qubes Device Widget, the tool tray icon with a yellow square located in the top right of your screen by default.
+The interface to deal with devices of all sorts was unified in Qubes 4.0 with the `qvm-device` command and the Qubes Devices Widget.
+In Qubes 3.X, the Qubes VM Manager dealt with attachment as well.
+This functionality was moved to the Qubes Device Widget, the tool tray icon with a yellow square located in the top right of your screen by default.
 
 There are currently four categories of devices Qubes understands:
  - Microphones
@@ -26,31 +30,41 @@ There are currently four categories of devices Qubes understands:
  - USB devices
  - PCI devices
 
-Microphones, block devices and USB devices can be attached with the GUI-tool. PCI devices can be attached using the Qube Settings, but require a VM reboot.
+Microphones, block devices and USB devices can be attached with the GUI-tool.
+PCI devices can be attached using the Qube Settings, but require a VM reboot.
 
 
 ## General Qubes Device Widget Behavior And Handling ##
 
-When clicking on the tray icon (which looks similar to this): ![SD card and thumbdrive][device manager icon] several device-classes separated by lines are displayed as tooltip. Block devices are displayed on top, microphones one below and USB-devices at the bottom.
+When clicking on the tray icon (which looks similar to this): ![SD card and thumbdrive][device manager icon] several device-classes separated by lines are displayed as tooltip.
+Block devices are displayed on top, microphones one below and USB-devices at the bottom.
 
 On most laptops, integrated hardware such as cameras and fingerprint-readers are implemented as USB-devices and can be found here.
 
 
 ### Attaching Using The Widget ###
 
-Click the tray icon. Hover on a device you want to attach to a VM. A list of running VMs (except dom0) appears. Click on one and your device will be attached!
+Click the tray icon.
+Hover on a device you want to attach to a VM.
+A list of running VMs (except dom0) appears.
+Click on one and your device will be attached!
 
 
 ### Detaching Using The Widget ###
 
-To detach a device, click the Qubes Devices Widget icon again. Attached devices are displayed in bold. Hover the one you want to detach. A list of VMs appears, one showing the eject symbol: ![eject icon]
+To detach a device, click the Qubes Devices Widget icon again.
+Attached devices are displayed in bold.
+Hover the one you want to detach.
+A list of VMs appears, one showing the eject symbol: ![eject icon]
 
 
 ### Attaching a Device to Several VMs ###
 
-Only `mic` should be attached to more than one running VM. You may *assign* a device to more than one VM (using the [`--persistent`][#attaching-devices] option), however, only one of them can be started at the same time.
+Only `mic` should be attached to more than one running VM.
+You may *assign* a device to more than one VM (using the [`--persistent`][#attaching-devices] option), however, only one of them can be started at the same time.
 
-But be careful: There is a [bug in `qvm-device block` or `qvm-block`][i4692] which will allow you to *attach* a block device to two running VMs. Don't do that!
+But be careful: There is a [bug in `qvm-device block` or `qvm-block`][i4692] which will allow you to *attach* a block device to two running VMs.
+Don't do that!
 
 
 ## General `qvm-device` Command Line Tool Behavior ##
@@ -60,7 +74,8 @@ All devices, including PCI-devices, may be attached from the commandline using t
 
 ### Device Classes ###
 
-`qvm-device` expects DEVICE_CLASS as first argument. DEVICE_CLASS can be one of
+`qvm-device` expects DEVICE_CLASS as first argument.
+DEVICE_CLASS can be one of
 
  - `pci`
  - `usb`
@@ -85,7 +100,9 @@ These three options are always available:
 - `--verbose`, `-v` - increase verbosity
 - `--quiet`, `-q` - decrease verbosity
 
-A full command consists of one DEVICE_CLASS and one action. If no action is given, list is implied. DEVICE_CLASS however is required.
+A full command consists of one DEVICE_CLASS and one action.
+If no action is given, list is implied.
+DEVICE_CLASS however is required.
 
 **SYNOPSIS**:
 `qvm-device DEVICE_CLASS {action} [action-specific arguments] [options]`
@@ -98,12 +115,16 @@ Actions are applicable to every DEVICE_CLASS and expose some additional options.
 
 ### Listing Devices ###
 
-The `list` action lists known devices in the system. `list` accepts VM-names to narrow down listed devices. Devices available in, as well as attached to the named VMs will be listed.
+The `list` action lists known devices in the system.
+`list` accepts VM-names to narrow down listed devices.
+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`. No VM-name implies `--all`.
+ - `--all` - equivalent to specifying every VM name after `list`.
- - `--exclude` - exclude VMs from `--all`. Requires `--all`.
+No VM-name implies `--all`.
+ - `--exclude` - exclude VMs from `--all`.
+Requires `--all`.
 
 **SYNOPSIS**
 `qvm-device DEVICE_CLASS {list|ls|l} [--all [--exclude VM [VM [...]]] | VM [VM [...]]]`
@@ -111,11 +132,15 @@ The `list` action lists known devices in the system. `list` accepts VM-names to
 
 ### Attaching Devices ###
 
-The `attach` action assigns an exposed device to a VM. This makes the device available in the VM it's attached to. Required argument are targetVM and sourceVM:deviceID. (sourceVM:deviceID can be determined from `list` output)
+The `attach` action assigns an exposed device to a VM.
+This makes the device available in the VM it's attached to.
+Required argument are targetVM and sourceVM:deviceID.
+(sourceVM:deviceID can be determined from `list` output)
 
 `attach` accepts two options:
 
- - `--persistent` - attach device on targetVM-boot. If the device is unavailable (physically missing or sourceVM not started), booting the targetVM fails.
+ - `--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.
 
 **SYNOPSIS**
@@ -124,7 +149,9 @@ The `attach` action assigns an exposed device to a VM. This makes the device ava
 
 ### Detaching Devices ###
 
-The `detach` action removes an assigned device from a targetVM. It won't be available afterwards anymore. Though it tries to do so gracefully, beware that data-connections might be broken unexpectedly, so close any transaction before detaching a device!
+The `detach` action removes an assigned device from a targetVM.
+It won't be available afterwards anymore.
+Though it tries to do so gracefully, beware that data-connections might be broken unexpectedly, so close any transaction before detaching a device!
 
 If no specific `sourceVM:deviceID` combination is given, *all devices of that DEVICE_CLASS will be detached.*
 

user/common-tasks/disposablevm.md

@@ -68,7 +68,8 @@ This is a change in behaviour from R3.2, where DisposableVMs would inherit the s
 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.
 For example, if an AppVM uses sys-net as its NetVM, but the default system DisposableVM uses sys-whonix, any DisposableVM launched from this AppVM will have sys-whonix as its NetVM.
 
-**Warning:** The opposite is also true. This means if you have changed anon-whonix's `default_dispvm` to use the system default, and the system default DisposableVM uses sys-net, launching a DisposableVM from inside anon-whonix will result in the DisposableVM using sys-net.
+**Warning:** The opposite is also true.
+This means if you have changed anon-whonix's `default_dispvm` to use the system default, and the system default DisposableVM uses sys-net, launching a DisposableVM from inside anon-whonix will result in the DisposableVM using sys-net.
 
 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.
@@ -118,7 +119,8 @@ Note that the `qvm-open-in-dvm` process will not exit until you close the applic
 
 ## Starting an arbitrary program in a DisposableVM from an AppVM ##
 
-Sometimes it can be useful to start an arbitrary program in a DisposableVM. This can be done from an AppVM by running
+Sometimes it can be useful to start an arbitrary program in a DisposableVM.
+This can be done from an AppVM by running
 
 ~~~
 [user@vault ~]$ qvm-run '$dispvm' xterm

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

@@ -14,7 +14,9 @@ Enabling Full Screen Mode for select VMs
 What is full screen mode?
 -------------------------
 
-Normally Qubes GUI virtualization daemon restricts the VM from "owning" the full screen, ensuring that there are always clearly marked decorations drawn by the trusted Window Manager around each of the VMs window. This allows the user to easily realize to which domain a specific window belongs. See the [screenshots](/doc/QubesScreenshots/) for better understanding.
+Normally Qubes GUI virtualization daemon restricts the VM from "owning" the full screen, ensuring that there are always clearly marked decorations drawn by the trusted Window Manager around each of the VMs window.
+This allows the user to easily realize to which domain a specific window belongs.
+See the [screenshots](/doc/QubesScreenshots/) for better understanding.
 
 Why is full screen mode potentially dangerous?
 ----------------------------------------------
@@ -24,8 +26,12 @@ If one allowed one of the VMs to "own" the full screen, e.g. to show a movie on
 Secure use of full screen mode
 ------------------------------
 
-However, it is possible to deal with full screen mode in a secure way assuming there are mechanisms that can be used at any time to show the full desktop, and which cannot be intercepted by the VM. An example of such a mechanism is the KDE's "Present Windows" and "Desktop Grid" effects, which are similar to Mac's "Expose" effect, and which can be used to immediately detect potential "GUI forgery", as they cannot be intercepted by any of the VM (as the GUID never passes down the key combinations that got consumed by KDE Window Manager), and so the VM cannot emulate those. Those effects are enabled by default in KDE once Compositing gets enabled in KDE (System Settings -\> Desktop -\> Enable Desktop Effects), which is recommended anyway. By default they are triggered by Ctrl-F8 and Ctrl-F9 key combinations, but can also be reassigned to other shortcuts.
+However, it is possible to deal with full screen mode in a secure way assuming there are mechanisms that can be used at any time to show the full desktop, and which cannot be intercepted by the VM.
-Another option is to use Alt+Tab for switching windows. This shortcut is also handled by dom0.
+An example of such a mechanism is the KDE's "Present Windows" and "Desktop Grid" effects, which are similar to Mac's "Expose" effect, and which can be used to immediately detect potential "GUI forgery", as they cannot be intercepted by any of the VM (as the GUID never passes down the key combinations that got consumed by KDE Window Manager), and so the VM cannot emulate those.
+Those effects are enabled by default in KDE once Compositing gets enabled in KDE (System Settings -\> Desktop -\> Enable Desktop Effects), which is recommended anyway.
+By default they are triggered by Ctrl-F8 and Ctrl-F9 key combinations, but can also be reassigned to other shortcuts.
+Another option is to use Alt+Tab for switching windows.
+This shortcut is also handled by dom0.
 
 Enabling full screen mode for select VMs
 ----------------------------------------
@@ -60,11 +66,8 @@ global: {
 Be sure to restart the VM(s) after modifying this file, for the changes to take effect.
 
 
-**Note:** Regardless of the settings above, you can always put a window into
+**Note:** Regardless of the settings above, you can always put a window into fullscreen mode in Xfce4 using the trusted window manager by right-clicking on a window's title bar and selecting "Fullscreen".
-fullscreen mode in Xfce4 using the trusted window manager by right-clicking on
+This functionality should still be considered safe, since a VM window still can't voluntarily enter fullscreen mode.
-a window's title bar and selecting "Fullscreen". This functionality should still
+The user must select this option from the trusted window manager in dom0.
-be considered safe, since a VM window still can't voluntarily enter fullscreen
+To exit fullscreen mode from here, press `alt` + `space` to bring up the title bar menu again, then select "Leave Fullscreen".
-mode. The user must select this option from the trusted window manager in dom0.
-To exit fullscreen mode from here, press `alt` + `space` to bring up the title
-bar menu again, then select "Leave Fullscreen".  
 For StandaloneHVMs, you should set the screen resolution in the qube to that of the host, (or larger), *before* setting fullscreen mode in Xfce4.

user/common-tasks/optical-discs.md

@@ -18,5 +18,8 @@ Currently, the only options for reading and recording optical discs (e.g., CDs,
  3. Use a SATA optical drive attached to dom0.
     (**Caution:** This option is [potentially dangerous](/doc/security-guidelines/#dom0-precautions).)
 
-To access an optical disc via USB follow the [typical procedure for attaching a USB device](/doc/usb-devices/#with-the-command-line-tool), then check with the **Qubes Devices** widget to see what device in the target qube the USB optical drive was attached to. 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`.
+To access an optical disc via USB follow the [typical procedure for attaching a USB device](/doc/usb-devices/#with-the-command-line-tool), then check with the **Qubes Devices** widget to see what device in the target qube the USB optical drive was attached to.
+Typically this would be `sr0`.
+For example, if `sys-usb` has device `3-2` attached to the `work` qube's `sr0`, you would mount it with `mount /dev/sr0 /mnt/removable`.
+You could also write to a disc with `wodim -v dev=/dev/sr0 -eject /home/user/Qubes.iso`.
 

user/common-tasks/pci-devices.md

@@ -13,19 +13,24 @@ redirect_from:
 
 *This page is part of [device handling in qubes].*
 
-**Warning:** Only dom0 exposes PCI devices. Some of them are strictly required in dom0 (e.g., the host bridge).
+**Warning:** Only dom0 exposes PCI devices.
+Some of them are strictly required in dom0 (e.g., the host bridge).
 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.
+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 ##
 
-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.
+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.
 
 The Qubes installer attaches all network class controllers to `sys-net` and all USB controllers to `sys-usb` by default, if you chose to create the network and USB qube during install.
 While this covers most use cases, there are some occasions when you may want to manually attach one NIC to `sys-net` and another to a custom NetVM, or have some other type of PCI controller you want to manually attach.
 
-Some devices expose multiple functions with distinct BDF-numbers. Limits imposed by the PC and VT-d architectures may require all functions belonging to the same device to be attached to the same VM. This requirement can be dropped with the `no-strict-reset` option during attachment, bearing in mind the aforementioned [security considerations].
+Some devices expose multiple functions with distinct BDF-numbers.
+Limits imposed by the PC and VT-d architectures may require all functions belonging to the same device to be attached to the same VM.
+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. 
@@ -35,7 +40,8 @@ This can be useful if, for example, you have only one USB controller, but you ha
 
 ## Attaching Devices Using the GUI ##
 
-The qube settings for a VM offers the "Devices"-tab. There you can attach PCI-devices to a qube.
+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
 
@@ -45,13 +51,16 @@ The qube settings for a VM offers the "Devices"-tab. There you can attach PCI-de
 
  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.
+ 4. You're done.
- 5. In case it doesn't work out, first try disabling memory-balancing in the settings ("Advanced" tab). If that doesn't help, read on to learn how to disable the strict reset requirement!
+    If 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 ##
 
-The `qvm-pci` tool allows PCI attachment and detachment. It's a shortcut for [`qvm-device pci`][qvm-device].
+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:
 
@@ -99,14 +108,17 @@ Both can be achieved during attachment with `qvm-pci` as described below.
 
 ## 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).)
+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).)
 
-`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!**
+`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 ###
 
-Do not require PCI device to be reset before attaching it to another VM. This may leak usage data even without malicious intent!
+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:
 
@@ -115,7 +127,8 @@ usage example:
 
 ### permissive ###
 
-Allow write access to full PCI config space instead of whitelisted registers. This increases attack surface and possibility of [side channel attacks].
+Allow write access to full PCI config space instead of whitelisted registers.
+This increases attack surface and possibility of [side channel attacks].
 
 usage example:
 

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

@@ -14,7 +14,10 @@ Installing and updating software in dom0
 Why would one want to install or update software in dom0?
 ---------------------------------------------------------
 
-Normally, there should be few reasons for installing or updating software in dom0. This is because there is no networking in dom0, which means that even if some bugs are discovered e.g. in the dom0 Desktop Manager, this really is not a problem for Qubes, because none of the third-party software running in dom0 is accessible from VMs or the network in any way. Some exceptions to this include: Qubes GUI daemon, Xen store daemon, and disk back-ends. (We plan move the disk backends to an untrusted domain in a future Qubes release.) Of course, we believe this software is reasonably secure, and we hope it will not need patching.
+Normally, there should be few reasons for installing or updating software in dom0.
+This is because there is no networking in dom0, which means that even if some bugs are discovered e.g. in the dom0 Desktop Manager, this really is not a problem for Qubes, because none of the third-party software running in dom0 is accessible from VMs or the network in any way.
+Some exceptions to this include: Qubes GUI daemon, Xen store daemon, and disk back-ends.
+(We plan move the disk backends to an untrusted domain in a future Qubes release.) Of course, we believe this software is reasonably secure, and we hope it will not need patching.
 
 However, we anticipate some other situations in which installing or updating dom0 software might be necessary or desirable:
 
@@ -25,18 +28,25 @@ However, we anticipate some other situations in which installing or updating dom
 How is software installed and updated securely in dom0?
 -------------------------------------------------------
 
-The install/update process is split into two phases: "resolve and download" and "verify and install." The "resolve and download" phase is handled by the "UpdateVM." (The role of UpdateVM can be assigned to any VM in the Qubes VM Manager, and there are no significant security implications in this choice. By default, this role is assigned to the firewallvm.) After the UpdateVM has successfully downloaded new packages, they are sent to dom0, where they are verified and installed. This separation of duties significantly reduces the attack surface, since all of the network and metadata processing code is removed from the TCB.
+The install/update process is split into two phases: "resolve and download" and "verify and install." The "resolve and download" phase is handled by the "UpdateVM." (The role of UpdateVM can be assigned to any VM in the Qubes VM Manager, and there are no significant security implications in this choice.
+By default, this role is assigned to the firewallvm.) After the UpdateVM has successfully downloaded new packages, they are sent to dom0, where they are verified and installed.
+This separation of duties significantly reduces the attack surface, since all of the network and metadata processing code is removed from the TCB.
 
-Although this update scheme is far more secure than directly downloading updates in dom0, it is not invulnerable. For example, there is nothing that the Qubes project can feasibly do to prevent a malicious RPM from exploiting a hypothetical bug in GPG's `--verify` operation. At best, we could switch to a different distro or package manager, but any of them could be vulnerable to the same (or a similar) attack. While we could, in theory, write a custom solution, it would only be effective if Qubes repos included all of the regular TemplateVM distro's updates, and this would be far too costly for us to maintain.
+Although this update scheme is far more secure than directly downloading updates in dom0, it is not invulnerable.
+For example, there is nothing that the Qubes project can feasibly do to prevent a malicious RPM from exploiting a hypothetical bug in GPG's `--verify` operation.
+At best, we could switch to a different distro or package manager, but any of them could be vulnerable to the same (or a similar) attack.
+While we could, in theory, write a custom solution, it would only be effective if Qubes repos included all of the regular TemplateVM distro's updates, and this would be far too costly for us to maintain.
 
 How to install and update software in dom0
 ------------------------------------------
 
 ### How to update dom0
 
-In the Qube Manager, simply select dom0 in the VM list, then click the **Update VM system** button (the blue, downward-pointing arrow). In addition, updating dom0 has been made more convenient: You will be prompted on the desktop whenever new dom0 updates are available and given the choice to run the update with a single click.
+In the Qube Manager, simply select dom0 in the VM list, then click the **Update VM system** button (the blue, downward-pointing arrow).
+In addition, updating dom0 has been made more convenient: You will be prompted on the desktop whenever new dom0 updates are available and given the choice to run the update with a single click.
 
-Alternatively, command-line tools are available for accomplishing various update-related tasks (some of which are not available via Qubes VM Manager). In order to update dom0 from the command line, start a console in dom0 and then run one of the following commands:
+Alternatively, command-line tools are available for accomplishing various update-related tasks (some of which are not available via Qubes VM Manager).
+In order to update dom0 from the command line, start a console in dom0 and then run one of the following commands:
 
 To check and install updates for dom0 software:
 
@@ -48,7 +58,8 @@ To install additional packages in dom0 (usually not recommended):
 
     $ 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.
+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.
 You can also pass commands to `dnf` using `--action=...`.
 
 ### How to downgrade a specific package
@@ -87,7 +98,8 @@ You can re-install in a similar fashion to downgrading.
     sudo dnf reinstall package
     ~~~
 
-    Note that `dnf` will only re-install if the installed and downloaded versions match. You can ensure they match by either updating the package to the latest version, or specifying the package version in the first step using the form `package-version`.
+    Note that `dnf` will only re-install if the installed and downloaded versions match.
+    You can ensure they match by either updating the package to the latest version, or specifying the package version in the first step using the form `package-version`.
 
 ### How to uninstall a package
 
@@ -106,8 +118,8 @@ There are three Qubes dom0 testing repositories:
 * `qubes-dom0-unstable` -- packages that are not intended to land in the stable (`qubes-dom0-current`)
   repository; mostly experimental debugging packages
 
-To temporarily enable any of these repos, use the `--enablerepo=<repo-name>`
+To temporarily enable any of these repos, use the `--enablerepo=<repo-name>` option.
-option. Example commands:
+Example commands:
 
 ~~~
 sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing
@@ -120,8 +132,10 @@ To enable or disable any of these repos permanently, change the corresponding `e
 
 ### Kernel Upgrade ###
 
-Install newer kernel for dom0 and VMs. The package `kernel` is for dom0 and the package `kernel-qubes-vm`
+Install newer kernel for dom0 and VMs.
-is needed for the VMs. (Note that the following example enables the unstable repo.)
+The package `kernel` is for dom0 and the package `kernel-qubes-vm`
+is needed for the VMs.
+(Note that the following example enables the unstable repo.)
 
 ~~~
 sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable kernel kernel-qubes-vm
@@ -151,7 +165,10 @@ to do a lot of work yourself](https://groups.google.com/d/msg/qubes-users/m8sWoy
 
 Requires installed [Whonix](/doc/privacy/whonix/).
 
-Go to Qubes VM Manager -> System -> Global Settings. See the UpdateVM setting. Choose your desired Whonix-Gateway ProxyVM from the list. For example: sys-whonix.
+Go to Qubes VM Manager -> System -> Global Settings.
+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
 

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

@@ -157,7 +157,8 @@ qvm-create --class StandaloneVM --label <label> --property virt_mode=hvm <vmname
 
 ... or click appropriate options in the Qubes Manager's Create VM window.
 
-(Note: Technically, `virt_mode=hvm` is not necessary for every StandaloneVM. However, it makes sense if you want to use a kernel from within the VM.)
+(Note: Technically, `virt_mode=hvm` is not necessary for every StandaloneVM.
+However, it makes sense if you want to use a kernel from within the VM.)
 
 
 Using more than one template

user/common-tasks/usb-devices.md

@@ -12,7 +12,9 @@ redirect_from:
 
 If you are looking to handle USB *storage* devices (thumbdrives or USB-drives), please have a look at the [block device] page.
 
-**Important security warning:** USB passthrough comes with many security implications. Please make sure you carefully read and understand the **[security considerations]**. Whenever possible, attach a [block device] instead.
+**Important security warning:** USB passthrough comes with many security implications.
+Please make sure you carefully read and understand the **[security considerations]**.
+Whenever possible, attach a [block device] instead.
 
 Examples of valid cases for USB-passthrough:
 
@@ -20,7 +22,8 @@ Examples of valid cases for USB-passthrough:
  - [external audio devices]
  - [optical drives] for recording
 
-(If you are thinking to use a two-factor-authentication device, [there is an app for that][qubes u2f proxy]. But it has some [issues][4661].)
+(If you are thinking to use a two-factor-authentication device, [there is an app for that][qubes u2f proxy].
+But it has some [issues][4661].)
 
 
 ## Attaching And Detaching a USB Device ##
@@ -29,11 +32,14 @@ Examples of valid cases for USB-passthrough:
 ### With Qubes Device Manager ###
 
 Click the device-manager-icon: ![device manager icon]  
-A list of available devices appears. USB-devices have a USB-icon to their right: ![usb icon]
+A list of available devices appears.
+USB-devices have a USB-icon to their right: ![usb icon]
 
 Hover on one device to display a list of VMs you may attach it to.
 
-Click one of those. The USB device will be attached to it. You're done.
+Click one of those.
+The USB device will be attached to it.
+You're done.
 
 After you finished using the USB-device, you can detach it the same way by clicking on the Devices Widget.
 You will see an entry in bold for your device such as **`sys-usb:2-5 - 058f_USB_2.0_Camera`**.
@@ -81,13 +87,15 @@ When you finish, detach the device.
 
 ### Creating And Using a USB qube ###
 
-If you've selected to install a usb-qube during system installation, everything is already set up for you in `sys-usb`. If you've later decided to create a usb-qube, please follow [this guide][USB-qube howto].
+If you've selected to install a usb-qube during system installation, everything is already set up for you in `sys-usb`.
+If you've later decided to create a usb-qube, please follow [this guide][USB-qube howto].
 
 
 ### Installation Of `qubes-usb-proxy` ###
 
 To use this feature, the[`qubes-usb-proxy`][qubes-usb-proxy] package needs to be installed in the templates used for the USB qube and qubes you want to connect USB devices to.
-This section exists for reference or in case something broke and you need to reinstall `qubes-usb-proxy`. Under normal conditions, `qubes-usb-proxy` should already be installed and good to go.
+This section exists for reference or in case something broke and you need to reinstall `qubes-usb-proxy`.
+Under normal conditions, `qubes-usb-proxy` should already be installed and good to go.
 
 If you receive this error: `ERROR: qubes-usb-proxy not installed in the VM`, you can install the `qubes-usb-proxy` with the package manager in the VM you want to attach the USB device to.
 Note: you cannot pass through devices from dom0 (in other words: a [USB qube][USB-qube howto] is required).