Improve device handling rework content

- Remove deprecated 3.2 pages
- Normalize names, text, formatting, and URLs
- Fix Markdown syntax
- Miscellanous cleanups and improvements

common-tasks/block-devices.md

@@ -1,19 +1,23 @@
 ---
 layout: doc
-title: Block or Storage Devices in Qubes R4.0
+title: Block (Storage) Devices
 permalink: /doc/block-devices/
 redirect_from:
-- /doc/block-devices-in-qubes-R4.0/
+- /doc/stick-mounting/
+- /en/doc/stick-mounting/
+- /doc/StickMounting/
+- /wiki/StickMounting/
 ---
 
-Block or Storage Devices in Qubes R4.0
+# Block (Storage) Devices #
-======================================
+
-*This page is part of [device handling in qubes]*
+*This page is part of [device handling in qubes].*
-(In case you were looking for the [R3.2 documentation](/doc/usb/).)
 
 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.)
 
@@ -33,7 +37,9 @@ 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 ~
@@ -49,7 +55,9 @@ 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`.
 
 `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.
@@ -96,7 +104,9 @@ In case of a USB-drive, make sure it's attached to your computer. If you don't s
 
  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
@@ -107,7 +117,9 @@ To recover from this error state, in dom0 run
 
 However, if the block device originated in dom0, you will have to refer to the [old way][detach dom0 device].
 
-# 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
@@ -134,10 +146,14 @@ To attach a file as block device to another qube, first turn it into a loopback
 
         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. (The next one tried will be `xvdj`, then `xvdk`, and so on ...)
 
 usage example:
@@ -146,7 +162,9 @@ usage example:
 
 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.
 
 If the device is a read-only device, this option is forced true.
@@ -161,7 +179,9 @@ There exists a shortcut to set read-only `true`, `--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:
@@ -179,4 +199,5 @@ This option accepts `cdrom` and `disk`, default is `disk`.
 [premature removal]: https://github.com/QubesOS/qubes-issues/issues/1082
 [detach dom0 device]: /doc/usb/#what-if-i-removed-the-device-before-detaching-it-from-the-vm
 [losetup]: https://linux.die.net/man/8/losetup
-[USB]:/doc/usb-devices-in-qubes-R4.0/
+[USB]:/doc/usb-devices/
+

common-tasks/device-handling.md

@@ -1,21 +1,24 @@
 ---
 layout: doc
-title: Device Handling in Qubes R4.0
+title: Device Handling
 permalink: /doc/device-handling/
 redirect_from:
-- /doc/device-handling-in-qubes-R4.0/
+- /doc/external-device-mount-point/
+- /en/doc/external-device-mount-point/
+- /doc/ExternalDeviceMountPoint/
+- /wiki/ExternalDeviceMountPoint/
 ---
 
-Device Handling in Qubes R4.0
+# Device Handling #
-=============================
 
-**Note:** This is an overview for device-handling in QubesOS. For specific devices ([block], [USB] and [PCI] devices), please visit the respective page.
+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 understood the **[security considerations]**!
+**Important security warning:** Device handling comes with many security implications. Please make sure you carefully read and understand the **[security considerations]**.
 
-----------------------
 
-The interface to deal with devices of all sorts was unified in Q4.0 with the `qvm-device` command and the Qubes Devices Widget. In Q3.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.
+## 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.
 
 There are currently four categories of devices Qubes understands:
  - Microphones
@@ -25,26 +28,38 @@ There are currently four categories of devices Qubes understands:
 
 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 (looking 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.
+## 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.
 
 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 ##
+
+### 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!
 
-## Detaching Using The Widget ##
+
+### 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]
 
-## Attaching a Device to Several VMs ##
+
+### 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.
 
 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 #
+
+## General `qvm-device` Command Line Tool Behavior ##
+
 All devices, including PCI-devices, may be attached from the commandline using the `qvm-device`-tools.
 
-## Device Classes ##
+
+### Device Classes ###
+
 `qvm-device` expects DEVICE_CLASS as first argument. DEVICE_CLASS can be one of
 
  - `pci`
@@ -52,7 +67,9 @@ All devices, including PCI-devices, may be attached from the commandline using t
  - `block`
  - `mic`
 
-## Actions ##
+
+### Actions ###
+
 `qvm-device` supports three actions:
 
  - `list` (ls, l) - list all devices of DEVICE_CLASS
@@ -60,23 +77,27 @@ All devices, including PCI-devices, may be attached from the commandline using t
  - `detach` (dt, d) - detach a specific device of DEVICE_CLASS
 
 
-## Global Options ##
+### Global Options ###
+
 These three options are always available:
 
 - `--help`, `-h` - show help message and exit
 - `--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.
 
 **SYNOPSIS**:
 `qvm-device DEVICE_CLASS {action} [action-specific arguments] [options]`
 
+
 ## Actions ##
+
 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.
 
 `list` accepts two options:
@@ -87,7 +108,9 @@ The `list` action lists known devices in the system. `list` accepts VM-names to
 **SYNOPSIS**
 `qvm-device DEVICE_CLASS {list|ls|l} [--all [--exclude VM [VM [...]]] | VM [VM [...]]]`
 
+
 ### 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)
 
 `attach` accepts two options:
@@ -98,7 +121,9 @@ The `attach` action assigns an exposed device to a VM. This makes the device ava
 **SYNOPSIS**
 `qvm-device DEVICE_CLASS {attach|at|a} targetVM sourceVM:deviceID [options]`
 
+
 ### 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!
 
 If no specific `sourceVM:deviceID` combination is given, *all devices of that DEVICE_CLASS will be detached.*
@@ -109,11 +134,11 @@ If no specific `sourceVM:deviceID` combination is given, *all devices of that DE
 `qvm-device DEVICE_CLASS {detach|dt|d} targetVM [sourceVM:deviceID]`
 
 
-[block]:/doc/block-devices-in-qubes-R4.0/
+[block]:/doc/block-devices/
-[USB]:/doc/usb-devices-in-qubes-R4.0/
+[USB]:/doc/usb-devices/
-[PCI]:/doc/pci-devices-in-qubes-R4.0/
+[PCI]:/doc/pci-devices/
-
+[security considerations]: /doc/device-handling-security/
-[security considerations]: /doc/device-considerations/
 [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
+

common-tasks/pci-devices.md

@@ -1,20 +1,24 @@
 ---
 layout: doc
-title: PCI Devices in Qubes R4.0
+title: PCI Devices
 permalink: /doc/pci-devices/
 redirect_from:
-- /doc/pci-devices-in-qubes-R4.0/
+- /doc/assigning-devices/
+- /en/doc/assigning-devices/
+- /doc/AssigningDevices/
+- /wiki/AssigningDevices/
 ---
 
-PCI Devices in Qubes R4.0
+# PCI Devices #
-=========================
-*This page is part of [device handling in qubes]*
-(In case you were looking for the [R3.2 documentation](/doc/assigning-devices/).)
 
-**Warning:** Only dom0 exposes PCI devices. Some of them are strictly required in dom0! (e.g. host bridge)
+*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).
 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.
 
-**Security warning:** PCI passthrough should be safe by default, but non-default options may be required. Please make sure you carefully read and understood 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.
 
@@ -28,7 +32,9 @@ While PCI device can only be used by one powered on VM at a time, it *is* possib
 This means that you can use the device in one VM, shut that VM down, start up a different VM (to which the same device is now attached), then use the device in that VM.
 This can be useful if, for example, you have only one USB controller, but you have multiple security domains which all require the use of different USB devices.
 
-# Attaching Devices Using the GUI #
+
+## Attaching Devices Using the GUI ##
+
 The qube settings for a VM offers the "Devices"-tab. There you can attach PCI-devices to a qube.
 
  1. To reach the settings of any qube either
@@ -42,7 +48,9 @@ The qube settings for a VM offers the "Devices"-tab. There you can attach PCI-de
  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:
@@ -62,9 +70,10 @@ For example, if `00_1a.0` is the BDF of the device you want to attach to the "wo
     qvm-pci attach work dom0:00_1a.0 --persistent
 
 
-# Possible Issues #
+## Possible Issues ##
 
-## DMA Buffer Size ##
+
+### DMA Buffer Size ###
 
 VMs with attached PCI devices in Qubes have allocated a small buffer for DMA operations (called swiotlb).
 By default it is 2MB, but some devices need a larger buffer.
@@ -77,7 +86,8 @@ To change this allocation, edit VM's kernel parameters (this is expressed in 512
 
 This is [known to be needed][ml1] for the Realtek RTL8111DL Gigabit Ethernet Controller.
 
-## PCI Passthrough Issues ##
+
+### PCI Passthrough Issues ###
 
 Sometimes the PCI arbitrator is too strict. 
 There is a way to enable permissive mode for it.
@@ -87,19 +97,24 @@ At other times, you may instead need to disable the FLR requirement on a device.
 Both can be achieved during attachment with `qvm-pci` as described below.
 
 
-# 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).)
 
 `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
 
-## 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:
@@ -107,8 +122,8 @@ usage example:
     qvm-pci a work dom0:00_1a.0 --persistent -o no-strict-reset=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.
 
 This is an intended feature.
@@ -133,9 +148,9 @@ or
 
 
 [device handling in qubes]: /doc/device-handling/
-[security considerations]: /doc/device-considerations/#pci-security
+[security considerations]: /doc/device-handling-security/#pci-security
-[block]:/doc/block-devices-in-qubes-R4.0/
+[block]:/doc/block-devices/
-[USB]:/doc/usb-devices-in-qubes-R4.0/
+[USB]:/doc/usb-devices/
 [appmenu]: /attachment/wiki/Devices/qubes-appmenu-select.png
 [domain manager icon]: /attachment/wiki/Devices/qubes-logo-icon.png
 [qvm-device]: /doc/device-handling/#general-qubes-device-widget-behavior-and-handling
@@ -143,3 +158,4 @@ or
 [ml1]: https://groups.google.com/group/qubes-devel/browse_thread/thread/631c4a3a9d1186e3
 [ml2]: https://groups.google.com/forum/#!topic/qubes-users/Fs94QAc3vQI
 [PCI passthrough]: https://wiki.xen.org/wiki/Xen_PCI_Passthrough
+

common-tasks/usb-devices.md

@@ -1,30 +1,33 @@
 ---
 layout: doc
-title: USB Devices in Qubes R4.0
+title: USB Devices
 permalink: /doc/usb-devices/
 redirect_from:
-- /doc/usb-devices-in-qubes-R4.0/
+- /doc/usb/
 ---
 
-USB  Devices in Qubes R4.0
+# USB Devices #
-==========================
-*This page is part of [device handling in qubes]*
-(In case you were looking for the [R3.2 documentation](/doc/usb/).)
 
-If you are looking to handle USB-*storage*-devices (thumbdrives or USB-drives), please have a look at [storage device handling][block-device].
+*This page is part of [device handling in qubes].*
 
-**Important security warning:** USB passthrough comes with many security implications! Please make sure you carefully read and understood the **[security considerations]**! Especially, whenever possible, attach a [block device] instead!
+If you are looking to handle USB *storage* devices (thumbdrives or USB-drives), please have a look at the [block device] page.
 
-Examples for valid cases for USB-passthrough:
+**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:
 
  - [microcontroller programming]
- - using [external audio devices]
+ - [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].)
 
-# Attaching And Detaching a USB Device #
+
-## With Qubes Device Manager ##
+## Attaching And Detaching a USB Device ##
+
+
+### 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]
 
@@ -38,7 +41,9 @@ Hover on the attached device to display a list of running VMs.
 The one to which your device is connected will have an eject button ![eject icon] next to it.
 Click that and your device will be detached.
 
-## With The Command Line Tool ##
+
+### With The Command Line Tool ###
+
 In dom0, you can use `qvm-usb` from the commandline to attach and detach devices.
 
 Listing available USB devices:
@@ -70,12 +75,17 @@ When you finish, detach the device.
     sys-usb:2-5     058f:3822 058f_USB_2.0_Camera
     sys-usb:2-1     03f0:0641 PixArt_Optical_Mouse
 
-# Maintenance And Customisation #
 
-## Creating And Using a USB qube ##
+## Maintenance And Customisation ##
+
+
+### Creating And Using a USB qube ###
+
 If you've selected to install a usb-qube during system installation, everything is already set up for you in `sys-usb`. If you've later decided to create a usb-qube, please follow [this guide][USB-qube howto].
 
-## Installation Of `qubes-usb-proxy` ##
+
+### Installation Of `qubes-usb-proxy` ###
+
 To use this feature, the[`qubes-usb-proxy`][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.
 
@@ -87,13 +97,14 @@ Note: you cannot pass through devices from dom0 (in other words: a [USB qube][US
 - Debian/Ubuntu: `sudo apt-get install qubes-usb-proxy`
 
 
-## Using USB Keyboards And Other Input Devices ##
+### Using USB Keyboards And Other Input Devices ###
+
 **Warning:** especially keyboards need to be accepted by default when using them to login! Please make sure you carefully read and understood the **[security considerations]** before continuing!
 
 Mouse and keyboard setup are part of [setting up a USB-qube][keyboard setup].
 
 
-## Finding The Right USB Controller ##
+### Finding The Right USB Controller ###
 
 Some USB devices are not compatible with the USB pass-through method Qubes employs.
 In situations like these, you can try to pass through the entire USB controller to a qube as PCI device.
@@ -131,8 +142,8 @@ Strip the leading `0000:` and pass the rest to the [`qvm-pci` tool][qvm-pci] to
 
 
 [device handling in qubes]: /doc/device-handling/
-[block device]: /doc/block-devices-in-qubes-R4.0/
+[block device]: /doc/block-devices/
-[security considerations]: /doc/device-considerations/#usb-security
+[security considerations]: /doc/device-handling-security/#usb-security
 [usb-challenges]: https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html
 [usb icon]: /attachment/wiki/Devices/generic-usb.png
 [microcontroller programming]: https://www.arduino.cc/en/Main/Howto
@@ -143,6 +154,6 @@ Strip the leading `0000:` and pass the rest to the [`qvm-pci` tool][qvm-pci] to
 [device manager icon]:/attachment/wiki/Devices/media-removable.png
 [eject icon]:/attachment/wiki/Devices/media-eject.png
 [Installation Section]:#installation-of-qubes-usb-proxy
-[USB-qube howto]: /doc/usb-qube-howto/
+[USB-qube howto]: /doc/usb-qubes/
-[keyboard setup]: /doc/usb-qube-howto/#enable-a-usb-keyboard-for-login
+[keyboard setup]: /doc/usb-qubes/#enable-a-usb-keyboard-for-login
-[qvm-pci]: /doc/pci-devices-in-qubes-R4.0/
+[qvm-pci]: /doc/pci-devices/

common-tasks/usb.md

@@ -1,203 +0,0 @@
----
-layout: doc
-title: Using and Managing USB Devices in R3.2
-permalink: /doc/usb/
-redirect_from:
-- /doc/stick-mounting/
-- /en/doc/stick-mounting/
-- /doc/StickMounting/
-- /wiki/StickMounting/
-- /doc/external-device-mount-point/
-- /en/doc/external-device-mount-point/
-- /doc/ExternalDeviceMountPoint/
-- /wiki/ExternalDeviceMountPoint/
-- /doc/usbvm/
-- /en/doc/usbvm/
-- /doc/USBVM/
-- /wiki/USBVM/
-- /doc/sys-usb/
----
-
-Using and Managing USB Devices in R3.2
-======================================
-(In case you were looking for the [R4.0 documentation](/doc/usb-devices/).)
-
-How to attach USB drives
-------------------------
-
-(**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 one or more of its partitions) to any qube easily, no matter which qube actually handles the USB controller.
-
-USB drive mounting is integrated into the Qubes VM Manager GUI.
-Simply insert your USB drive, right-click on the desired qube in the Qubes VM Manager list, click **Attach/detach block devices**, and select your desired action and device.
-However, this only works for the whole device.
-If you would like to attach individual partitions, you must use the command-line tool.
-
-Note that attaching individual partitions can be slightly more secure because it doesn't force the target AppVM to parse the partition table.
-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.
-    
-The command-line tool you may use to mount whole USB drives or their partitions is `qvm-block`.
-This tool can be used to assign a USB drive to a qube as follows:
-
- 1. Insert your USB drive.
-
- 2. In a dom0 console (running as a normal user), list all available block devices:
-
-        qvm-block
-
-    This will list all available block devices connected to any USB controller in your system, no matter which qube hosts the controller.
-    The name of the qube hosting the USB controller is displayed before the colon in the device name.
-    The string after the colon is the name of the device used within the qube, like so:
-
-        dom0:sdb1     Cruzer () 4GiB
-        
-        usbVM:sdb1    Disk () 2GiB
-
-    **Note:** If your device is not listed here, you may refresh the list by calling from the qube to which the device is connected (typically `sys-usb`):
-
-        sudo udevadm trigger --action=change
-
- 3.  Assuming your USB drive is attached to `sys-usb` and is `sdb`, we attach the device to a qube with the name `personal` like so:
-
-         qvm-block -a personal sys-usb:sdb
-
-     This will attach the device to the qube as `/dev/xvdi` if that name is not 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 after `sdb`.
-     This is slightly more secure because it does not force the target AppVM to parse the partition table.
-
-     **Warning:** when working with single partitions, it is possible to assign the same partition to multiple qubes.
-     For example, you could attach `sdb1` to qube1 and then `sdb` to qube2.
-     It is up to the user not to make this mistake.
-     The Xen block device framework currently does not provide an easy way around this.
-     Point 2 of [this comment on issue 1072][1072-comm2] gives details about this.
-
- 4.  The USB drive 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, you may need to manually mount before it becomes visible:
-     ```
-     cd ~
-     mkdir mnt
-     sudo mount /dev/xvdi mnt
-     ```
-   
- 5.  When you finish using your USB drive, click the eject button or right-click and select **Unmount**.
-     If you've manually mounted a single partition in the above step, use:
-     `sudo umount mnt`
-
- 6.  In a dom0 console, detach the stick
-
-         qvm-block -d <device>
-         
-     or
-     
-         qvm-block -d <vmname>
-
- 7.  You may now remove the device.
-
-**Warning:** Do not remove the device before detaching it from the VM!
-Otherwise, you will not be able to attach it anywhere later.
-See issue [1082] for details.
-
-If the device does not appear in Nautilus, you will need to mount it manually.
-The device will show up as `/dev/xvdi` (or `/dev/xvdj` if there is already one device attached -- if two, `/dev/xvdk`, and so on).
-
-
-### 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`).
-
- 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
-
-    In above example, all `xl block-attach` parameters can be deduced from the output of `qvm-block`.
-    In order:
-
-    * `testvm` - name of target qube to which device was attached - listed in brackets by `qvm-block` command
-    * `phy:/dev/sda` - physical path at which device appears in source qube (just after source qube name in `qvm-block` output)
-    * `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.
-
-
-Attaching a single USB device to a qube (USB passthrough)
----------------------------------------------------------
-
-Starting with Qubes 3.2, it is possible to attach a single USB device to any Qube.
-While this is a useful feature, it should be used with care, because there are [many security implications][usb-challenges] from using USB devices and USB passthrough will **expose your target qube** to most of them.
-If possible, use a method specific for particular device type (for example, block devices described above), instead of this generic one.
-
-### Installation of qubes-usb-proxy ###
-[installation]: #installation-of-qubes-usb-proxy
-
-Note, you cannot pass through devices from dom0 (in other words: a USB VM is required).
-
-To use this feature, you need to have the [`qubes-usb-proxy`][qubes-usb-proxy] package installed in the template used for the USB qube and in the qube to which you want to connect USB devices. ( If the qube is TemplateBased then it should be installed in the relevant template as usual. )
-If you do not have the package installed you will see this error: `ERROR: qubes-usb-proxy not installed in the VM`.
-
-`qubes-usb-proxy` should be installed by default in the standard Fedora and Debian templates.
-
-You install the `qubes-usb-proxy` package using the package manager as usual.
-
-- Fedora: `sudo dnf install qubes-usb-proxy`
-- Debian/Ubuntu: `sudo apt-get install qubes-usb-proxy`
-
-### Usage of qubes-usb-proxy ###
-
-Listing available USB devices:
-
-    [user@dom0 ~]$ qvm-usb
-    sys-usb:2-4     04ca:300d 04ca_300d
-    sys-usb:2-5     058f:3822 058f_USB_2.0_Camera
-    sys-usb:2-1     03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
-
-Attaching selected USB device:
-
-    [user@dom0 ~]$ qvm-usb -a conferences sys-usb:2-5
-    [user@dom0 ~]$ qvm-usb
-    conferences:2-1 058f:3822 058f_USB_2.0_Camera
-    sys-usb:2-4     04ca:300d 04ca_300d
-    sys-usb:2-5     058f:3822 058f_USB_2.0_Camera (attached to conferences)
-    sys-usb:2-1     03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
-
-Now, you can use your USB device (camera in this case) in the `conferences` qube.
-If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section][installation].
-
-When you finish, detach the device:
-
-    [user@dom0 ~]$ qvm-usb -d sys-usb:2-5
-    [user@dom0 ~]$ qvm-usb
-    sys-usb:2-4     04ca:300d 04ca_300d
-    sys-usb:2-5     058f:3822 058f_USB_2.0_Camera
-    sys-usb:2-1     03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
-
-This feature is not available in Qubes Manager.
-
-Additional Reading:
--------------------
-
- - [Creating a USB qube]
- - [Using a USB keyboard]
-
-[mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class
-[1072-comm2]: https://github.com/QubesOS/qubes-issues/issues/1072#issuecomment-124119309
-[1082]: https://github.com/QubesOS/qubes-issues/issues/1082
-[usb-challenges]: https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html
-[YubiKey]: /doc/YubiKey/
-[Creating a USB qube]: /doc/usb-qube-howto/
-[Using a USB keyboard]: /doc/usb-qube-howto/#enable-a-usb-keyboard-for-login
-[qubes-usb-proxy]: https://github.com/QubesOS/qubes-app-linux-usb-proxy

configuration/assigning-devices.md

@@ -1,112 +0,0 @@
----
-layout: doc
-title: Assigning Devices in R3.2
-permalink: /doc/assigning-devices/
-redirect_from:
-- /en/doc/assigning-devices/
-- /doc/AssigningDevices/
-- /wiki/AssigningDevices/
----
-
-Assigning Devices to VMs in R3.2
-================================
-(In case you were looking for the [R4.0 documentation](/doc/pci-devices/).)
-
-Sometimes you may need to assign an entire PCI or PCI Express device directly to a qube.
-This is also known as PCI passthrough.
-The Qubes installer does this by default for `sys-net` (assigning all network class controllers), as well as `sys-usb` (assigning all USB controllers) if you chose to create the USB qube during install.
-While this covers most use cases, there are some occasions when you may want to manually assign one NIC to `sys-net` and another to a custom NetVM, or have some other type of PCI controller you want to manually assign.
-
-Note that one can only assign full PCI or PCI Express devices by default.
-This limit is imposed by the PC and VT-d architectures.
-This means if a PCI device has multiple functions, all instances of it need to be assigned to the same qube unless you have disabled the strict requirement for FLR with the `no-strict-reset` (R4.0) or `pci_strictreset` (R3.2) option.
-In the steps below, you can tell if this is needed if you see the BDF for the same device listed multiple times with only the number after the "." changing.
-
-While PCI device can only be used by one powered on VM at a time, it *is* possible to *assign* the same device to more than one VM at a time. 
-This means that you can use the device in one VM, shut that VM down, start up a different VM (to which the same device is also assigned), then use the device in that VM.
-This can be useful if, for example, you have only one USB controller, but you have multiple security domains which all require the use of different USB devices.
-
-Using the Command Line
-------------------------
-
-In order to assign a whole PCI(e) device to a VM, one should use the `qvm-pci` tool.
-First, list the available PCI devices:
-
-~~~
-lspci
-~~~
-
-This will show you the BDF address of each PCI device.
-It will look something like `00:1a.0`. 
-Once you've found the BDF address of the device you want to assign, then attach it like so:
-
-~~~
-qvm-pci -a <vmname> <bdf>
-~~~
-
-For example, if `00:1a.0` is the BDF of the device you want to assign to the "personal" domain, you would do this:
-
-~~~
-qvm-pci -a personal 00:1a.0
-~~~
-
-Using Qubes Manager
--------------------
-
-The above steps can also be done in Qubes Manager.
-Simply go into the VM settings of your desired VM, then go to the "Devices" tab.
-This will show you a list of available devices, which you can select to be assigned to that VM.
-
-
-Finding the right USB controller
---------------------------------
-This was moved to the [current documentation][finding controller].
-
-Possible issues
----------------
-Please refer to the [current documentation][possible issues] for an issue description and carefully read the [security implications]!
-Return here for a guide on how to enable permissive mode and disable strict reset!
-
-Enabling permissive mode
-------------------------
-
-Permissive mode is enabled system wide per device.
-
-Create `/etc/systemd/system/qubes-pre-netvm.service`:
-
-~~~
-[Unit]
-Description=Netvm fixup
-Before=qubes-netvm.service
-
-[Service]
-ExecStart=/bin/sh -c 'echo 0000:04:00.0 > /sys/bus/pci/drivers/pciback/permissive'
-Type=oneshot
-RemainAfterExit=yes
-
-[Install]
-WantedBy=multi-user.target
-~~~
-
-Then enable it with `systemctl enable qubes-pre-netvm.service`
-
-The strict reset option is set for all devices attached to a VM with:
-
-```
-qvm-prefs usbVM -s pci_strictreset false
-```
-
-**Note** again that in most cases you should not need either of these options set.
-Only set one or more of them as required to get your device to function, or replace the device with one that functions properly with Qubes.
-
-Bringing PCI device back to dom0
---------------------------------
-This was moved to the [current documentation][bring back devices].
-
-
-
-[usb]: /doc/usb/
-[finding controller]: /doc/usb-devices/#finding-the-right-usb-controller
-[possible issues]: /doc/pci-devices/#possible-issues
-[security implications]: /doc/device-considerations/#pci-security
-[bring back devices]: /doc/pci-devices/#bringing-pci-devices-back-to-dom0

configuration/usb-qubes.md

@@ -1,17 +1,23 @@
 ---
 layout: doc
-title:  USB Qube HowTo
+title:  USB Qubes
-permalink: /doc/usb-qube-howto/
+permalink: /doc/usb-qubes/
+redirect_from:
+- /doc/usbvm/
+- /en/doc/usbvm/
+- /doc/USBVM/
+- /wiki/USBVM/
+- /doc/sys-usb/
 ---
 
-USB Qube HowTo
+# USB Qubes #
-==============
+
 If during installation you enabled the creation of a USB-qube, your system should be setup already and none of the mentioned steps here should be necessary. (Unless you want to [remove your USB-qube].) If for any reason no USB-qube was created during installation, this guide will show you how to do so.
 
 **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
+
------------------------------
+## Creating and Using a USB qube ##
 
 **Warning:** This has the potential to prevent you from connecting a keyboard to Qubes via USB.
 There are problems with doing this in an encrypted install (LUKS).
@@ -48,8 +54,7 @@ Alternatively, you can create a USB qube manually as follows:
 If the USB qube will not start, please have a look at the [faq].
 
 
-Enable a USB keyboard for login
+## Enable a USB keyboard for login ##
--------------------------------
 
 **Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding!
 
@@ -57,6 +62,7 @@ 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 ###
 R4.0 only! R3.2 users please read the [manual setup] below!
 
@@ -72,6 +78,7 @@ 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.
@@ -96,8 +103,8 @@ For a confirmation dialog each time the USB keyboard is connected, *which will e
 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
+
-----------------------
+## Auto Enabling A USB Mouse ##
 
 **Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding.
 
@@ -120,8 +127,7 @@ In case you are absolutely sure you do not want to confirm mouse access from `sy
 (Change `sys-usb` to your desired USB qube.)
 
 
-How to hide all USB controllers from dom0
+## How to hide all USB controllers from dom0 ##
------------------------------------------
 
 (Note: Beginning with R3.2, `rd.qubes.hide_all_usb` is set automatically if you opt to create a USB qube during installation.
 This also occurs automatically if you choose to [create a USB qube] using the `qubesctl` method, which is the
@@ -162,8 +168,7 @@ The procedure to hide all USB controllers from dom0 is as follows:
  5. Reboot.
 
 
-Removing a USB qube
+## Removing a USB qube ##
--------------------
 
 **Warning:** This procedure will result in your USB controller(s) being attached directly to dom0.
 
@@ -189,18 +194,17 @@ Removing a USB qube
  7. Reboot.
 
 
-
-
 [remove your USB-qube]: #removing-a-usb-qube
-[security implications]: /doc/device-considerations/#usb-security
+[security implications]: /doc/device-handling-security/#usb-security
 [enable your keyboard for login]: #enable-a-usb-keyboard-for-login
 [2270-comm23]: https://github.com/QubesOS/qubes-issues/issues/2270#issuecomment-242900312
-[PCI Devices]: /doc/pci-devices-in-qubes-R4.0/
+[PCI Devices]: /doc/pci-devices/
 [usb-controller]: /doc/usb-devices/#finding-the-right-usb-controller
 [faq]: /faq/#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot
-[Security Warning about USB Input Devices]: /doc/device-considerations/#security-warning-on-usb-input-devices
+[Security Warning about USB Input Devices]: /doc/device-handling-security/#security-warning-on-usb-input-devices
 [manual setup]: #manual-setup
 [install dom0 updates]: /doc/software-update-dom0/#how-to-update-dom0
 [hiding USB controllers from dom0]: #how-to-hide-all-usb-controllers-from-dom0
 [AEM]: /doc/anti-evil-maid/
 [create a USB qube]: #creating-and-using-a-usb-qube
+

customization/disposablevm-customization.md

@@ -248,7 +248,7 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe
   
        [user@dom0 ~]$ qvm-prefs disp-sys-usb autostart true
 
-7. Users should now follow instructions on [How to hide USB controllers from dom0](/doc/usb-qube-howto/#how-to-hide-all-usb-controllers-from-dom0)
+7. Users should now follow instructions on [How to hide USB controllers from dom0](/doc/usb-qubes/#how-to-hide-all-usb-controllers-from-dom0)
 
 8. At this point, your mouse may not work.
    Edit the `qubes.InputMouse` policy file in dom0, which is located here:

doc.md

@@ -66,9 +66,10 @@ redirect_from:
  * [Installing and Updating Software in VMs](/doc/software-update-vm/)
  * [Backup, Restoration, and Migration](/doc/backup-restore/)
  * [Using DisposableVMs](/doc/disposablevm/)
- * [Using and Managing USB Devices in R3.2](/doc/usb/)
+ * [Block (or Storage) Devices](/doc/block-devices/)
- * [Using Block or Storage Devices in Qubes R4.0](/doc/block-devices/)
+ * [USB Devices](/doc/usb-devices)
- * [Using USB  Devices in Qubes R4.0](/doc/usb-devices)
+ * [PCI Devices](/doc/pci-devices/)
+ * [Device Handling](/doc/device-handling/)
  * [Optical Discs](/doc/optical-discs/)
  * [Managing Application Shortcuts](/doc/managing-appvm-shortcuts/)
  * [Enabling Fullscreen Mode](/doc/full-screen-mode/)
@@ -108,7 +109,7 @@ redirect_from:
  * [How to Set Up a Split Bitcoin Wallet in Qubes](/doc/split-bitcoin/)
  * [[Unofficial] Split dm-crypt](https://github.com/rustybird/qubes-split-dm-crypt)
  * [Configuring YubiKey for user authentication](/doc/yubi-key/)
- * [Implications of using devices](/doc/device-considerations/)
+ * [Security Considerations When Handling Devices](/doc/device-handling-security/)
  * [Note regarding password-less root access in VM](/doc/vm-sudo/)
 
 
@@ -139,8 +140,7 @@ redirect_from:
  * [Creating Custom NetVMs and ProxyVMs](https://theinvisiblethings.blogspot.com/2011/09/playing-with-qubes-networking-for-fun.html)
  * [How to make proxy for individual tcp connection from networkless VM](https://groups.google.com/group/qubes-devel/msg/4ca950ab6d7cd11a)
  * [Adding Bridge Support to the NetVM (EXPERIMENTAL)](/doc/network-bridge-support/)
- * [Assigning PCI Devices to AppVMs](/doc/pci-devices/)
+ * [USB Qubes](/doc/usb-qubes/)
- * [Creating a USB qube](/doc/usb-qube-howto/)
  * [Enabling TRIM for SSD disks](/doc/disk-trim/)
  * [Configuring a Network Printer](/doc/network-printer/)
  * [Using External Audio Devices](/doc/external-audio/)
@@ -188,7 +188,6 @@ redirect_from:
  * [Command-Line Tools: Qubes 3.2, domU](/doc/tools/3.2/domU/)
  * [Command-Line Tools: Qubes 4.0, dom0](/doc/tools/4.0/dom0/)
  * [Command-Line Tools: Qubes 4.0, domU](/doc/tools/4.0/domU/)
- * [Device Handling in Qubes 4.0](/doc/device-handling/)
  * [Glossary of Qubes Terminology](/doc/glossary/)
  * [Qubes Service Framework](/doc/qubes-service/)
  * [Command Execution in VMs (and Qubes RPC)](/doc/qrexec/)

installing/install-security.md

@@ -83,6 +83,6 @@ switch might be the option.
 [verify]: /security/verifying-signatures/
 [classic problem]: https://www.ece.cmu.edu/~ganger/712.fall02/papers/p761-thompson.pdf
 [solutions]: https://www.dwheeler.com/trusting-trust/
-[USB qube]: /doc/usb-qube-howto/#creating-and-using-a-usb-qube
+[USB qube]: /doc/usb-qubes/#creating-and-using-a-usb-qube
 [BadUSB]: https://srlabs.de/badusb/
 

security/device-handling-security.md

@@ -1,22 +1,20 @@
 ---
 layout: doc
-title: Security Considerations When Handling Devices
+title: Device Handling Security
-permalink: /doc/device-considerations/
+permalink: /doc/device-handling-security/
 ---
 
-Security Considerations When Handling Devices
+# Device Handling Security #
-=============================================
+
-General Words of Caution
-------------------------
 Any additional ability a VM gains is additional attack surface. It's a good idea to always attach the minimum entity required in a VM.
 
-Attaching a full USB-device offers [more attack surface than attaching a single block device][USB security].  
+For example, attaching a full USB-device offers [more attack surface than attaching a single block device][USB security], while
-Attaching a full block device (e.g. `sda`) again offers more attack surface than attaching a single partition (e.g. `sda1`), since the targetVM doesn't have to parse the partition-table.
+attaching a full block device (e.g. `sda`) again offers more attack surface than attaching a single partition (e.g. `sda1`), since the targetVM doesn't have to parse the partition-table.
-
 (Attaching a full block device offers the advantage that most file-managers will mount and display them correctly, whereas they don't expect single partitions to be added and therefore don't handle them correctly.)
 
-PCI Security
+
-------------
+## PCI Security ##
+
 Attaching a PCI device to a qube has serious security implications. It exposes the device driver running in the qube to an external device (and sourceVM, which contains the device - e.g. `sys-usb`). In many cases a malicious device can choose what driver will be loaded (for example by manipulating device metadata like vendor and product identifiers) - even if the intended driver is sufficiently secure, the device may try to attack a different, less secure driver.
 Furthermore that VM has full control of the device and may be able to exploit bugs or malicious implementation of the hardware, as well as plain security problems the hardware may pose. (For example, if you attach a USB controller, all the security implications of USB passthrough apply as well.)
 
@@ -29,8 +27,9 @@ In case device reset is disabled for any reason, detaching the device should be
 Additionally, Qubes restricts the config-space a VM may use to communicate with a PCI device. Only whitelisted registers are accessible. However, some devices or applications require full PCI access. In these cases, the whole config-space may be allowed. you're potentially weakening the device isolation, especially if your system is not equipped with a VT-d Interrupt Remapping unit.  This increases the VM's ability to run a [side channel attack] and vulnerability to the same. <!--TODO: really? It seems obvious, but I'm missing citation.-->
 See [Software Attacks on Intel VT-d] \(page 7) for more details.
 
-USB Security
+
-------------
+## USB Security ##
+
 The connection of an untrusted USB device to dom0 is a security risk since the device can attack an arbitrary USB driver (which are included in the linux kernel), exploit bugs during partition-table-parsing or simply pretend to be a keyboard. There are many ready-to-use implementations of such attacks, e.g. a [USB Rubber Ducky][rubber duck].
 The whole USB stack is put to work to parse the data presented by the USB device in order to determine if it is a USB mass storage device, to read its configuration, etc.
 This happens even if the drive is then assigned and mounted in another qube.
@@ -40,8 +39,9 @@ To avoid this risk, use a [USB qube].
 Attaching a USB device to a VM (USB passthrough) will **expose your target qube** to most of the [security issues][USB security] associated with the USB-stack.
 If possible, use a method specific for particular device type (for example, block devices described above), instead of this generic one.
 
-**Security Warning On USB Input Devices**
+
------------------------------------------
+## Security Warning On USB Input Devices 
+
 If you connect USB input devices (keyboard and mouse) to a VM, that VM will effectively have control over your system.
 Because of this, the benefits of using a [USB qube] entrusted with a keyboard or other interface device are much smaller than using a fully untrusted USB qube.
 In addition to having control over your system, such a VM can also sniff all the input you enter there (for example, passwords in the case of a USB keyboard).
@@ -59,11 +59,13 @@ One way to achieve this is to use a [YubiKey], or some other hardware token, or
 
 Support for [two factor authentication][qubes u2f proxy] was recently added, though there are [issues][4661].
 
-[USB security]:https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html "invisiblethings blog on USB security"
+
+[USB security]:https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html "ITL blog post on USB security"
 [rubber duck]: https://shop.hak5.org/products/usb-rubber-ducky-deluxe
-[USB qube]: /doc/usb-qube-howto/
+[USB qube]: /doc/usb-qubes/
 [YubiKey]: /doc/YubiKey/
 [qubes u2f proxy]: https://www.qubes-os.org/news/2018/09/11/qubes-u2f-proxy/
 [4661]: https://github.com/QubesOS/qubes-issues/issues/4661
 [side channel attack]: https://en.wikipedia.org/wiki/Side-channel_attack
 [Software Attacks on Intel VT-d]: https://invisiblethingslab.com/resources/2011/Software%20Attacks%20on%20Intel%20VT-d.pdf
+

security/yubi-key.md

@@ -11,7 +11,7 @@ Using YubiKey to Qubes authentication
 =====================================
 
 You can use YubiKey to enhance Qubes user authentication, for example to mitigate
-risk of snooping the password. This can also slightly improve security when you have [USB keyboard](/doc/device-considerations/#security-warning-on-usb-input-devices).
+risk of snooping the password. This can also slightly improve security when you have [USB keyboard](/doc/device-handling-security/#security-warning-on-usb-input-devices).
 
 There (at least) two possible configurations: using OTP mode and using challenge-response mode.