From e2258ac74cda4de93f3384975947b9d6d4101f0c Mon Sep 17 00:00:00 2001 From: GammaSQ Date: Sat, 5 Jan 2019 10:30:04 +0100 Subject: [PATCH 01/25] Added rearranged documentation on devices in R4.0 --- common-tasks/block-devices.md | 164 +++++++++++++++++++++++ common-tasks/device-handling.md | 118 +++++++++++++++++ common-tasks/pci-devices.md | 146 +++++++++++++++++++++ common-tasks/usb-devices.md | 142 ++++++++++++++++++++ configuration/usb-qube-howto.md | 210 ++++++++++++++++++++++++++++++ security/device-considerations.md | 61 +++++++++ 6 files changed, 841 insertions(+) create mode 100644 common-tasks/block-devices.md create mode 100644 common-tasks/device-handling.md create mode 100644 common-tasks/pci-devices.md create mode 100644 common-tasks/usb-devices.md create mode 100644 configuration/usb-qube-howto.md create mode 100644 security/device-considerations.md diff --git a/common-tasks/block-devices.md b/common-tasks/block-devices.md new file mode 100644 index 00000000..ef78ff0d --- /dev/null +++ b/common-tasks/block-devices.md @@ -0,0 +1,164 @@ +--- +layout: doc +title: Block or Storage Devices in Qubes R4.0 +permalink: /doc/block-devices/ +redirect_from: +- /doc/block-devices-in-qubes-R4.0/ +--- + +Block or Storage Devices in Qubes R4.0 +====================================== +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 +(**Note:** In the present context, the term "USB drive" denotes any [USB mass storage device][mass-storage]. +In addition to smaller flash memory sticks, this includes things like USB external hard drives.) + +Qubes OS supports the ability to attach a USB drive (or just its partitions) to any qube easily, no matter which qube handles the USB controller. + +Attaching USB drives is integrated into the Devices Widget: ![device manager icon] +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`). + +The simplest option is to attach the entire block drive. +In our example, this is `sys-usb:sda`, so hover over it. +This will pop up a submenu showing running VMs to which the USB drive can be connected. +Click on one and your USB drive will be attached! + +**Note:** attaching individual partitions (e.g. `sys-usb:sda1`) 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. + +#Block Devices in VMs +If not specified otherwise, block devices will show up as `/dev/xvdi*` in a linux VM, where `*` may be the partition-number. If a block device isn't automatically mounted after attaching, open a terminal in the VM and execute: + + cd ~ + mkdir mnt + sudo mount /dev/xvdi2 mnt + +where `xvdi2` needs to be replaced with the partition you want to mount. +This will make your drive content accessible under `~/mnt`. + +Beware that when you attach a whole block device, partitions can be identified by their trailing integer (i.e. `/dev/xvdi2` for the second partition, `/dev/xvdi` for the whole device), whereas if you attach a single parition, the partition has *no trailing integer*. + +If several different block-devices are attached to a single VM, the last letter of the device node name is advanced through the alphabet, so after `xvdi` the next device will be named `xvdj`, the next `xvdk`, and so on. + +To specify this device node name, you can pass `--option frontend-dev=[custom-node-name]` to `qvm-block attach`. + +#Commandline 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` only sees device-nodes and may not use names you expect! So make sure to have the drive available in the sourceVM before listing available block devices (step 1.) to find out it's its ID. + +In case of a USB-drive, make sure it's attached to your computer. If you don't see anything that looks like your drive, run `sudo udevadm trigger --action=change` in your USB-qube (typically `sys-usb`) + + 1. In a dom0 console (running as a normal user), list all available block devices: + + qvm-block + + This will list all available block devices in your system across all VMs, no matter whether hosted by a USB controller or `losetup`. + The name of the qube hosting the block device is displayed before the colon in the device ID. + The string after the colon is the ID of the device used within the qube, like so: + + sourceVM:sdb Cruzer () 4GiB + sourceVM:sdb1 Disk () 2GiB + + 2. Assuming your block device is attached to `sys-usb` and its device node is `sdb`, we attach the device to a qube with the name `work` like so: + + qvm-block attach work sys-usb:sdb + + This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc. + + You may also mount one partition at a time by using the same command with the partition number, e.g. `sdb1`. + + 3. The block device is now attached to the qube. + If using a default qube, you may open the Nautilus file manager in the qube, and your drive should be visible in the **Devices** panel on the left. + If you've attached a single partition (e.g. `sdb2` instead of `sdb` in our example), you may need to manually mount before it becomes visible: + + cd ~ + mkdir mnt + sudo mount /dev/xvdi mnt + + + 4. When you finish using the block device, click the eject button or right-click and select **Unmount**. + + If you've manually mounted a single partition in the above step, use: + + sudo umount mnt + + 5. In a dom0 console, detach the device + + qvm-block detach work sys-usb:sdb + + 6. You may now remove the device or attach it to another qube. + + +#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 + + sudo losetup /dev/loop0 /path/to/file + + (increase the trailing integer if `loop0` is already in use or use other name. This is just a generic device-id.) + + 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 commandline, continue: + + In dom0, run `qvm-block` to display known block devices. The newly created loop device should show up: + + ~]$ qvm-block + BACKEND:DEVID DESCRIPTION USED BY + sourceVM:loop0 /path/to/file + + 3. Attach the `loop0`-device using qvm-block as usual: + + qvm-block a targetVM sourceVM:loop0 + + 4. After detaching, destroy the loop-device inside the sourceVM as follows: + + sudo losetup -d /dev/loop0 + +#Additional Attach Options +Attaching a block device through the commandline 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 ...) + +usage example: + + qvm-block a work sys-usb:sda1 -o frontend-dev=xvdz + +This command will attach the partition `sda1` to `work` as `/dev/xvdz`. + +##read-only +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. + +usage example: + + qvm-block a work sys-usb:sda1 -o read-only=true + +There exists a shortcut to set read-only `true`, `--ro`: + + qvm-block a work sys-usb:sda1 --ro + +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. + +usage example: + + qvm-block a work sys-usb:sda1 -o devtype=cdrom + +This option accepts `cdrom` and `disk`, default is `disk`. + + + +[mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class +[device manager icon]:https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/devices/media-removable.png +[USB]:/dock/usb-devices-in-qubes-R4.0/ \ No newline at end of file diff --git a/common-tasks/device-handling.md b/common-tasks/device-handling.md new file mode 100644 index 00000000..48d1d968 --- /dev/null +++ b/common-tasks/device-handling.md @@ -0,0 +1,118 @@ +--- +layout: doc +title: Device Handling in Qubes R4.0 +permalink: /doc/device-handling/ +redirect_from: +- /doc/device-handling-in-qubes-R4.0/ +--- + +Device Handling in Qubes R4.0 +============================= + +**Note:** This is an overview for device-handling in QubesOS. For specific devices ([block], [USB] and [PCI] devices), please visit the respective page. + +**Important security warning:** Device handling comes with many security implications! Please make sure you carefully read and understood 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. + +There are currently four categories of devices Qubes understands: + - Microphones + - Block devices + - USB devices + - PCI devices + +Microphones, block devices and USB devices can be attached with the GUI-tool. PCI devices require the command line tool. + +#Security Considerations + + +#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 seperated 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! + +##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 + + +#General `qvm-device` Commandline Tool Behavior +All devices, including PCI-devices, may be attached from the commandline using the `qvm-device`-tools. + +##Device Classes +`qvm-device` expects DEVICE_CLASS as first argument. DEVICE_CLASS can be one of + + - `pci` + - `usb` + - `block` + - `mic` + +##Actions +`qvm-device` supports three actions: + + - `list` (ls, l) - list all devices of DEVICE_CLASS + - `attach` (at, a) - attach a specific device of DEVICE_CLASS + - `detach` (dt, d) - detach a specific device of DEVICE_CLASS + + +##Global Options +These three options are allways available: + +- `--help`, `-h` - show help message and exit +- `--verbose`, `-v` - increase verbosity +- `--quiet`, `-q` - decrease verbosity + + +A full command consits 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. + +`list` accepts two options: + + - `--all` - equivalent to specifying every VM name after `list`. 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 [...]]]` + +###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: + + - `--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** +`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 deatching a device! + +`detach` accepts no options. + +**SYNOPSIS** +`qvm-device DEVICE_CLASS {detach|dt|d} targetVM sourceVM:deviceID` + + + +[block]:/doc/block-devices-in-qubes-R4.0/ +[USB]:/dock/usb-devices-in-qubes-R4.0/ +[PCI]:/doc/pci-devices-in-qubes-R4.0/ + +[security considerations]: /doc/device-considerations/ +[device manager icon]: https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/devices/media-removable.png +[eject icon]: https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/actions/media-eject.png \ No newline at end of file diff --git a/common-tasks/pci-devices.md b/common-tasks/pci-devices.md new file mode 100644 index 00000000..649f18ed --- /dev/null +++ b/common-tasks/pci-devices.md @@ -0,0 +1,146 @@ +--- +layout: doc +title: PCI Devices in Qubes R4.0 +permalink: /doc/pci-devices/ +redirect_from: +- /doc/pci-devices-in-qubes-R4.0/ +--- + +PCI Devices in Qubes R4.0 +====================================== +(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) +You may end up with an unusable system by attaching the wrong PCI device to a VM. + +**Security warning:** PCI passthrough should be safe by default, but none-default options may be required. Please make sure you carefully read and understood the **[security considerations]** before deviating from default behavior! + +Unlike other devices ([USB], [block], mic), PCI devices need to be attached on VM-bootup. Similar to how you can't attach a new soundcard after your computer booted (and expect it to work properly), attaching PCI devices to already booted VMs isn't possible in any meaningful way. + +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. + +Note that one can only attach 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 attached to the same qube unless you have disabled the strict requirement with the `no-strict-reset` option during attachment. +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 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 +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 + + - Press Alt+F3 to open the application finder, type in the VM name, select the "![appmenu]\[VM-name\]: Qube Settings" menu entry and press enter or click "Launch"! + - Select the VM in Qube Manager and click the settings-button or right-click the VM and select `Qube settings`. + - Click the Domain Manager ![device manager icon], hover the VM you want to assing a device to and select "settings" in the additional menu. (only running VMs!) + + 2. Select the "Devices" tab on the top bar. + 3. Select a device you want to attach to the qube and click the single arrow right! (`>`) + 4. You're done. If everything worked out, once the qube boots (or reboots if it's running) it will start with the pci device attached. + 5. In case it doesn't work out, first try disabeling 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]. + +To figure out what device to attach, first list the available PCI devices by running (as user) in dom0: + + qvm-pci + +This will show you the `backend:BDF` (Bus_Device.Function) address of each PCI device. +It will look something like `dom0:00_1a.0`. +Once you've found the address of the device you want to attach, then attach it like this: + + qvm-pci attach targetVM sourceVM:[BDF] --persistent + +Since PCI devices have to be attached on bootup, attaching has to happen with the `--persistant` option. + +For example, if `00_1a.0` is the BDF of the device you want to attach to the "work" domain, you would do this: + + qvm-pci attach work dom0:00_1a.0 --persistent + + +#Possible Issues + +##DMA Buffer Size + +VMs with assigned 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. +To change this allocation, edit VM's kernel parameters (this is expressed in 512B chunks): + + # qvm-prefs netvm |grep kernelopts + kernelopts : iommu=soft swiotlb=2048 (default) + # qvm-prefs -s netvm kernelopts "iommu=soft swiotlb=8192" + + +This is [known to be needed][ml1] for the Realtek RTL8111DL Gigabit Ethernet Controller. + +##PCI Passthrough Issues + +Sometimes the PCI arbitrator is too strict. +There is a way to enable permissive mode for it. +See also: [this thread][ml2] and the Xen wiki's [PCI passthrough] page. +At other times, you may instead need to disable the FLR requirement on a device. + +Both can be acchieved 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).) + +`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! + +usage example: + + qvm-pci a work dom0:00_1a.0 --persistent -o no-strict-reset=true + +##permissive +Allow write access to full PCI config space instead of whitlisted registers. This increases attack surface and possibility of [side channel attacks]. + +usage example: + + qvm-pci a work dom0:00_1a.0 --persistent -o no-strict-reset=true + + + +#Bringing PCI device 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. + +A device which was previously assigned to a VM less trusted than dom0 (which, in Qubes, is *all* of them) could attack dom0 if it were automatically reassigned there. + +In order to re-enable the device in dom0, either: + + * Reboot the physical machine. (Best practice) + +or + + * Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver, and attach it back to the original driver. + Replace `` with your full device, for example `0000:00:1c.2`: + + echo > /sys/bus/pci/drivers/pciback/unbind + MODALIAS=`cat /sys/bus/pci/devices//modalias` + MOD=`modprobe -R $MODALIAS | head -n 1` + echo > /sys/bus/pci/drivers/$MOD/bind + + It is **strongly discouraged to reattach PCI devices to dom0**, especially if they don't support resetting! + + + +[security considerations]: /doc/device-considerations/#pci-security +[block]:/doc/block-devices-in-qubes-R4.0/ +[USB]:/dock/usb-devices-in-qubes-R4.0/ +[appmenu]: https://raw.githubusercontent.com/QubesOS/qubes-artwork/master/icons/32x32/apps/qubes-appmenu-select.png +[domain manager icon]: https://raw.githubusercontent.com/QubesOS/qubes-artwork/master/icons/32x32/apps/qubes-logo-icon.png +[qvm-device]: /doc/device-handling-in-qubes-R4.0/#general-qubes-device-widget-behavior-and-handling +[side channel attacks]: https://en.wikipedia.org/wiki/Side-channel_attack +[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 \ No newline at end of file diff --git a/common-tasks/usb-devices.md b/common-tasks/usb-devices.md new file mode 100644 index 00000000..6b5566d6 --- /dev/null +++ b/common-tasks/usb-devices.md @@ -0,0 +1,142 @@ +--- +layout: doc +title: USB Devices in Qubes R4.0 +permalink: /doc/usb-devices/ +redirect_from: +- /doc/usb-devices-in-qubes-R4.0/ +--- + +USB Devices in Qubes R4.0 +========================== +(In case you were looking for the [R3.2 documentation](/doc/usb/).) + +**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! + +Examples for valid cases for USB-passthrough: + + - [microcontroller programming] + - using [extarnal audio devices] + - [optical drives] for recording + +(If you are thinking to use a two-factor-authentification 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 +Click the device-manager-icon: ![device manager icon] +A list of available devices appears. USB-devices have a USB-icon to their right. + +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. + +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`**. +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 +In dom0, you can use `qvm-usb` from the commandline to attach and detach devices. + +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 attach work sys-usb:2-5 + [user@dom0 ~]$ qvm-usb + work: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 work) + 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 `work` qube. +If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section]. + +When you finish, detach the device. + + [user@dom0 ~]$ qvm-usb detach work sys-usb:2-5 + [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 + +#Maintainence 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, plese 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. + +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). +`qubes-usb-proxy` should be installed by default in the template VM. + +- Fedora: `sudo dnf install qubes-usb-proxy` +- Debian/Ubuntu: `sudo apt-get install qubes-usb-proxy` + + +##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 + + +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. +However, with this approach one cannot attach single USB devices but has to attach the whole USB controller with whatever USB devices are connected to it. + +If you have multiple USB controllers, you must first figure out which PCI device is the right controller. + +First, find out which USB bus the device is connected to (note that these steps need to be run from a terminal inside your USB qube): + + lsusb + +For example, I want to attach a broadband modem to the NetVM. +In the output of `lsusb` it may be listed as something like: + + Bus 003 Device 003: ID 413c:818d Dell Computer Corp. + +(In this case, the device isn't fully identified) + +The device is connected to USB bus \#3. +Check which other devices are connected to the same bus, since *all* of them will be attach to the same VM. + +To find the right controller, follow the usb bus: + + readlink /sys/bus/usb/devices/usb3 + + +This should output something like: + + ../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3 + + +Now you see the BDF address in the path (right before final `usb3`). +Strip the leading `0000:` and pass the rest to the [`qvm-pci` tool][qvm-pci] to attach the controller to the targetVM. + + + +[block device]: /doc/block-devices-in-qubes-R4.0/ +[security considerations]: /doc/device-considerations/#usb-security +[usb-challenges]: https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html +[microcontroller programming]: https://www.arduino.cc/en/Main/Howto +[extarnal audio devices]: /doc/external-audio/ +[optical drives]: /doc/recording-optical-discs/ +[qubes u2f proxy]: https://www.qubes-os.org/news/2018/09/11/qubes-u2f-proxy/ +[4661]: https://github.com/QubesOS/qubes-issues/issues/4661 +[device manager icon]:https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/devices/media-removable.png +[eject icon]:https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/actions/media-eject.png +[Installation Section]:#installation-of-qubes-usb-proxy +[USB-qube howto]: /doc/usb-qube-howto/ +[keyboard setup]: /doc/usb-qube-howto/#enable-a-usb-keyboard-for-login +[qvm-pci]: /doc/pci-devices-in-qubes-R4.0/ \ No newline at end of file diff --git a/configuration/usb-qube-howto.md b/configuration/usb-qube-howto.md new file mode 100644 index 00000000..047a9a0e --- /dev/null +++ b/configuration/usb-qube-howto.md @@ -0,0 +1,210 @@ +--- +layout: doc +title: USB Qube HowTo +permalink: /doc/usb-qube-how-to/ +--- + +USB Qube HowTo +============== +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 necessarry. (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 possiblity to lock yourself out! To avoid this problem [enable your keyboard for login]! + +Creating and Using a USB qube +----------------------------- + +**Warning:** This has the potential to prevent you from connecting a keyboard to Qubes via USB. +There are problems with doing this in an encrypted install (LUKS). +If you find yourself in this situation, see this [issue][2270-comm23]. + +The connection of an untrusted USB device to dom0 is a security risk since dom0, like almost every OS, reads partition tables automatically. +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. + +To avoid this risk, it is possible to prepare and utilize a USB qube. + +A USB qube acts as a secure handler for potentially malicious USB devices, preventing them from coming into contact with dom0 (which could otherwise be fatal to the security of the whole system). +With a USB qube, every time you connect an untrusted USB drive to a USB port managed by that USB controller, you will have to attach it to the qube in which you wish to use it (if different from the USB qube itself), either by using Qubes VM Manager or the command line (see instructions above). +The USB controller may be assigned on the **Devices** tab of a qube's settings page in Qubes VM Manager or by using the [qvm-pci][PCI Devices] command. +For guidance on finding the correct USB controller, see the [according passage on PCI-devices][usb-controller]. +You can create a USB qube using the management stack by performing the following steps as root in dom0: + + sudo qubesctl state.sls qvm.sys-usb + +Alternatively, you can create a USB qube manually as follows: + + 1. Read the [PCI Devices] page to learn how to list and identify your USB controllers. + Carefully check whether you have a USB controller that would be appropriate to assign to a USB qube. + Note that it should be free of input devices, programmable devices, and any other devices that must be directly available to dom0. + If you find a free controller, note its name and proceed to step 2. + 2. Create a new qube. + Give it an appropriate name and color label (recommended: `sys-usb`, red). + 3. In the qube's settings, go to the "Devices" tab. + Find the USB controller that you identified in step 1 in the "Available" list. + Move it to the "Selected" list by highlighting it and clicking the single arrow `>` button. + + **Caution:** By assigning a USB controller to a USB qube, it will no longer be available to dom0. + This can make your system unusable if, for example, you have only one USB controller, and you are running Qubes off of a USB drive. + + 4. Click `OK`. + Restart the qube. + 5. Recommended: Check the box on the "Basic" tab which says "Start VM automatically on boot". + (This will help to mitigate attacks in which someone forces your system to reboot, then plugs in a malicious USB device.) + +If the USB qube will not start, please have a look at the [faq]. + + +Enable a USB keyboard for login +------------------------------- + +**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding! + +If you use USB keyboard, automatic USB qube creation during installation is disabled. +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! + +To allow USB keyboard usage (including early boot for LUKS passphrase), make sure you have the latest `qubes-mgmt-salt-dom0-virtual-machines` package (simply [install dom0 updates]) and execute in dom0: + + sudo qubesctl state.sls qvm.usb-keyboard + +The above command will take care of all required configuration, including creating USB qube if not present. +Note that it will expose dom0 to USB devices while entering LUKS passphrase. +Users are advised to physically disconnect other devices from the system for that time, to minimize the risk. + + +If you wish to perform only subset of this configuration (for example do not enable USB keyboard during boot), see manual instructions below. + +### Manual setup ### + + + +In order to use a USB keyboard, you must first attach it to a USB qube, then give that qube permission to pass keyboard input to dom0. +Edit the `qubes.InputKeyboard` policy file in dom0, which is located here: + + /etc/qubes-rpc/policy/qubes.InputKeyboard + +Add a line like this one to the top of the file: + + sys-usb dom0 allow,user=root + +(Change `sys-usb` to your desired USB qube.) + +You can now use your USB keyboard. + +For a confirmation dialog each time the USB keyboard is connected, change this line to: + + sys-usb dom0 ask,default_target=dom0 + +Additionally, if you want to use USB keyboard to enter LUKS passphrase, it is incompatible with [hiding USB controllers from dom0]. +You need to revert that procedure (remove `rd.qubes.hide_all_usb` option from files mentioned there) and employ alternative protection during system boot - disconnect other devices during startup. + +Auto Enabling A USB Mouse +---------------------- + +**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding. + +Handling a USB mouse isn't as critical as handling a keyboard, since you can login using the keyboard and accept the popup dialogue using your keyboard alone. + +If you want to attach the USB mouse automatically anyway, you have to edit the `qubes.InputMouse` policy file in dom0, located at: + + /etc/qubes-rpc/policy/qubes.InputMouse + +The first line should read similar to: + + sys-usb dom0 ask,default_target=dom0 + +which will ask for conformation each time a USB mouse is attached. If the file is empty or does not exist, maybe something went wrong during setup, try to rerun `qubesctl state.sls qvm.sys-usb` in dom0. + +In case you are absolutely sure you do not want to confirm mouse access from `sys-usb` to `dom0`, you may add the following line on top of the file: + + sys-usb dom0 allow,user=root + +(Change `sys-usb` to your desired USB qube.) + + +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 +first pair of steps in the linked section.) + +**Warning:** A USB keyboard cannot be used to type the disk passphrase if USB controllers were hidden from dom0. +Before hiding USB controllers, make sure your laptop keyboard is not internally connected via USB (by checking output of the `lsusb` command) or that you have a PS/2 keyboard at hand (if using a desktop PC). +Failure to do so will render your system unusable. + +If you create a USB qube manually, there will be a brief period of time during the boot process when dom0 will be exposed to your USB controllers (and any attached devices). +This is a potential security risk, since even brief exposure to a malicious USB device could result in dom0 being compromised. +There are two approaches to this problem: + +1. Physically disconnect all USB devices whenever you reboot the host. +2. Hide (i.e., blacklist) all USB controllers from dom0. + +**Warning:** If you use a USB [AEM] device, do not use the second option. +Using a USB AEM device requires dom0 to have access to the USB controller to which your USB AEM device is attached. +If dom0 cannot read your USB AEM device, AEM will hang. + +The procedure to hide all USB controllers from dom0 is as follows: + + * GRUB2 + + 1. Open the file `/etc/default/grub` in dom0. + 2. Find the line that begins with `GRUB_CMDLINE_LINUX`. + 3. Add `rd.qubes.hide_all_usb` to that line. + 4. Save and close the file. + 5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0. + 6. Reboot. + + * EFI + + 1. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0. + 2. Find the lines that begin with `kernel=`. There may be more than one. + 3. Add `rd.qubes.hide_all_usb` to those lines. + 4. Save and close the file. + 5. Reboot. + + +Removing a USB qube +------------------- + +**Warning:** This procedure will result in your USB controller(s) being attached directly to dom0. + + * GRUB2 + + 1. Shut down the USB qube. + 2. In Qubes Manager, right-click on the USB qube and select "Remove VM." + 3. Open the file `/etc/default/grub` in dom0. + 4. Find the line(s) that begins with `GRUB_CMDLINE_LINUX`. + 5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it. + 6. Save and close the file. + 7. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0. + 8. Reboot. + + * EFI + + 1. Shut down the USB qube. + 2. In Qubes Manager, right-click on the USB qube and select "Remove VM." + 3. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0. + 4. Find the line(s) that begins with `kernel=`. + 5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it. + 6. Save and close the file. + 7. Reboot. + + + + +[remove your USB-qube]: #removing-a-usb-qube +[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/ +[usb-controller]: +See [Software Attacks on Intel VT-d] (page 7) for more details. + +USB Security +------------ +While PCI devices generally are part of your computer and thereby hard to manipulate physically, USB devices are attached all the time on the fly and thereby pose a much easier accessible attack vector. + +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** +----------------------------------------- +If you connect USB input devices (keyboard and mouse) to a VM, that VM will effectively have control over your system. +Because of this, the benefits of using a [USB qube] are much smaller than using a fully untrusted USB qube. +In addition to having control over your system, such a VM can also sniff all the input you enter there (for example, passwords in the case of a USB keyboard). + +There is no simple way to protect against sniffing, but you can make it harder to exploit control over input devices. + +If you have only a USB mouse connected to a USB qube, but the keyboard is connected directly to dom0 (using a PS/2 connector, for example), you simply need to lock the screen when you are away from your computer. +You must do this every time you leave your computer unattended, even if there no risk of anyone else having direct physical access to your computer. +This is because you are guarding the system not only against anyone with local access, but also against possible actions from a potentially compromised USB qube. + +If your keyboard is also connected to a USB qube, things are much harder. +Locking the screen (with a traditional password) does not solve the problem, because the USB qube can simply sniff this password and later easily unlock the screen. +One possibility is to set up the screen locker to require an additional step to unlock (i.e., two-factor authentication). +One way to achieve this is to use a [YubiKey], or some other hardware token, or even to manually enter a one-time password. + +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 qube]: /doc/usb-qube-how-to/ +[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 \ No newline at end of file From ea9236234e7d9a5c4dd67d9c8b968226c72ae60d Mon Sep 17 00:00:00 2001 From: GammaSQ Date: Sat, 5 Jan 2019 10:46:12 +0100 Subject: [PATCH 02/25] Added referential links --- common-tasks/block-devices.md | 4 ++++ common-tasks/pci-devices.md | 4 +++- common-tasks/usb-devices.md | 2 ++ 3 files changed, 9 insertions(+), 1 deletion(-) diff --git a/common-tasks/block-devices.md b/common-tasks/block-devices.md index ef78ff0d..76af054a 100644 --- a/common-tasks/block-devices.md +++ b/common-tasks/block-devices.md @@ -8,6 +8,9 @@ redirect_from: Block or Storage Devices in Qubes R4.0 ====================================== +*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 @@ -159,6 +162,7 @@ This option accepts `cdrom` and `disk`, default is `disk`. +[device handling in qubes]: /doc/device-handling/ [mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class [device manager icon]:https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/devices/media-removable.png [USB]:/dock/usb-devices-in-qubes-R4.0/ \ No newline at end of file diff --git a/common-tasks/pci-devices.md b/common-tasks/pci-devices.md index 649f18ed..53ac0a83 100644 --- a/common-tasks/pci-devices.md +++ b/common-tasks/pci-devices.md @@ -7,7 +7,8 @@ redirect_from: --- PCI Devices in Qubes R4.0 -====================================== +========================= +*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) @@ -134,6 +135,7 @@ or +[device handling in qubes]: /doc/device-handling/ [security considerations]: /doc/device-considerations/#pci-security [block]:/doc/block-devices-in-qubes-R4.0/ [USB]:/dock/usb-devices-in-qubes-R4.0/ diff --git a/common-tasks/usb-devices.md b/common-tasks/usb-devices.md index 6b5566d6..a150d46a 100644 --- a/common-tasks/usb-devices.md +++ b/common-tasks/usb-devices.md @@ -8,6 +8,7 @@ redirect_from: USB Devices in Qubes R4.0 ========================== +*This page is part of [device handling in qubes]* (In case you were looking for the [R3.2 documentation](/doc/usb/).) **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! @@ -126,6 +127,7 @@ 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/ [security considerations]: /doc/device-considerations/#usb-security [usb-challenges]: https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html From 8b1c519d6f902df4b8501c746fffca7832257f58 Mon Sep 17 00:00:00 2001 From: GammaSQ Date: Sat, 5 Jan 2019 11:05:46 +0100 Subject: [PATCH 03/25] title casing remaining titles --- common-tasks/pci-devices.md | 2 +- common-tasks/usb-devices.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/common-tasks/pci-devices.md b/common-tasks/pci-devices.md index 53ac0a83..01a21df8 100644 --- a/common-tasks/pci-devices.md +++ b/common-tasks/pci-devices.md @@ -110,7 +110,7 @@ usage example: -#Bringing PCI device 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. diff --git a/common-tasks/usb-devices.md b/common-tasks/usb-devices.md index a150d46a..d555c4e8 100644 --- a/common-tasks/usb-devices.md +++ b/common-tasks/usb-devices.md @@ -89,7 +89,7 @@ Note: you cannot pass through devices from dom0 (in other words: a [USB qube][US 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. From 30e58b17b512d422a8bedbc9d811e47b103d71bc Mon Sep 17 00:00:00 2001 From: GammaSQ Date: Sat, 5 Jan 2019 11:20:48 +0100 Subject: [PATCH 04/25] Added new pages to doc.md --- doc.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/doc.md b/doc.md index b719a547..31aa67fc 100644 --- a/doc.md +++ b/doc.md @@ -67,7 +67,9 @@ Common Tasks * [Updating and Installing Software in VMs](/doc/software-update-vm/) * [Backup, Restoration, and Migration](/doc/backup-restore/) * [Using Disposable VMs](/doc/dispvm/) - * [Using and Managing USB Devices](/doc/usb/) + * [Using and Managing USB Devices in R3.2](/doc/usb/) + * [Using Block or Storage Devices in Qubes R4.0](/doc/block-devices/) + * [Using USB Devices in Qubes R4.0](/doc/usb-devices) * [Recording Optical Discs](/doc/recording-optical-discs/) * [Managing Application Shortcuts](/doc/managing-appvm-shortcuts/) * [Enabling Fullscreen Mode](/doc/full-screen-mode/) @@ -105,6 +107,7 @@ Security Guides * [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/) * [Note regarding password-less root access in VM](/doc/vm-sudo/) @@ -133,7 +136,8 @@ Configuration Guides * [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/assigning-devices/) + * [Assigning PCI Devices to AppVMs](/doc/pci-devices/) + * [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/) @@ -179,6 +183,7 @@ Reference Pages * [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/) From 706498d9761c4570ad418f47d885e9a88b2a5c0f Mon Sep 17 00:00:00 2001 From: GammaSQ Date: Sat, 5 Jan 2019 11:21:30 +0100 Subject: [PATCH 05/25] Removed documentation from deprecated pages --- common-tasks/usb.md | 343 +---------------------------- configuration/assigning-devices.md | 159 ++----------- 2 files changed, 26 insertions(+), 476 deletions(-) diff --git a/common-tasks/usb.md b/common-tasks/usb.md index bc1af09c..a42fccdd 100644 --- a/common-tasks/usb.md +++ b/common-tasks/usb.md @@ -1,6 +1,6 @@ --- layout: doc -title: Using and Managing USB Devices +title: Using and Managing USB Devices in R3.2 permalink: /doc/usb/ redirect_from: - /doc/stick-mounting/ @@ -18,82 +18,18 @@ redirect_from: - /doc/sys-usb/ --- -Using and Managing USB Devices -============================== +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. -### R4.0 ### - -USB drive mounting is integrated into the Devices Widget. -This is the tool tray icon with a yellow square located in the top right of your screen by default. -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. -The simplest (but slightly less secure, see note below about attaching individual partitions) option is to attach the entire block drive. -In our example, this is `sda`, so hover over it. -This will pop up a submenu showing running VMs to which the USB drive can be connected. -Click on one and your USB drive will be attached! - -Note that attaching individual partitions can be slightly more secure because it doesn't 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 attach 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`. - - 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 detach - - 7. You may now remove the device. - -### R3.2 ### - 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. @@ -170,7 +106,7 @@ 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? (R3.2) ### +### 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. @@ -216,52 +152,7 @@ However, if you receive this error: `ERROR: qubes-usb-proxy not installed in the - Fedora: `sudo dnf install qubes-usb-proxy` - Debian/Ubuntu: `sudo apt-get install qubes-usb-proxy` -### Usage of qubes-usb-proxy (R4.0) ### - -This feature is also available from the Devices Widget. -This is the tool tray icon with a yellow square located in the top right of your screen by default. -Simply insert your USB device and click on the widget. -You will see an entry for your device such as `sys-usb:2-5 - 058f_USB_2.0_Camera` for example. -Hover over it. -This will pop up a submenu showing running VMs to which the USB device can be connected. -Click on one and your device will be attached! -You may also use the command line: - -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 attach 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. -This can be done in the GUI 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`**. -Hover over it. -This will pop up a submenu showing running VMs. -The one to which your device is connected will have an Eject button next to it. -Click that and your device will be detached. -You may also use the command line: - - [user@dom0 ~]$ qvm-usb detach conferences sys-usb:2-5 - [user@dom0 ~]$ qvm-usb - 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 - -### Usage of qubes-usb-proxy (R3.2) ### +### Usage of qubes-usb-proxy ### Listing available USB devices: @@ -292,226 +183,16 @@ When you finish, detach the device: This feature is not available in Qubes Manager. -Creating and Using a USB qube ------------------------------ - -**Warning:** This has the potential to prevent you from connecting a keyboard to Qubes via USB. -There are problems with doing this in an encrypted install (LUKS). -If you find yourself in this situation, see this [issue][2270-comm23]. - -The connection of an untrusted USB device to dom0 is a security risk since dom0, like almost every OS, reads partition tables automatically. -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. - -To avoid this risk, it is possible to prepare and utilize a USB qube. - -A USB qube acts as a secure handler for potentially malicious USB devices, preventing them from coming into contact with dom0 (which could otherwise be fatal to the security of the whole system). -With a USB qube, every time you connect an untrusted USB drive to a USB port managed by that USB controller, you will have to attach it to the qube in which you wish to use it (if different from the USB qube itself), either by using Qubes VM Manager or the command line (see instructions above). -The USB controller may be assigned on the **Devices** tab of a qube's settings page in Qubes VM Manager or by using the [qvm-pci][Assigning Devices] command. -For guidance on finding the correct USB controller, see [here][usb-controller]. -You can create a USB qube using the management stack by performing the following steps as root in dom0: - - sudo qubesctl state.sls qvm.sys-usb - -Alternatively, you can create a USB qube manually as follows: - - 1. Read the [Assigning Devices] page to learn how to list and identify your USB controllers. - Carefully check whether you have a USB controller that would be appropriate to assign to a USB qube. - Note that it should be free of input devices, programmable devices, and any other devices that must be directly available to dom0. - If you find a free controller, note its name and proceed to step 2. - 2. Create a new qube. - Give it an appropriate name and color label (recommended: `sys-usb`, red). - If you need to attach a networking device, it might make sense to create a NetVM. - If not, an AppVM might make more sense. - (The default `sys-usb` is a NetVM.) - 3. In the qube's settings, go to the "Devices" tab. - Find the USB controller that you identified in step 1 in the "Available" list. - Move it to the "Selected" list. - - **Caution:** By assigning a USB controller to a USB qube, it will no longer be available to dom0. - This can make your system unusable if, for example, you have only one USB controller, and you are running Qubes off of a USB drive. - - 4. Click `OK`. - Restart the qube. - 5. Recommended: Check the box on the "Basic" tab which says "Start VM automatically on boot". - (This will help to mitigate attacks in which someone forces your system to reboot, then plugs in a malicious USB device.) - -If the USB qube will not start, see [here][faq-usbvm]. - -How to hide all USB controllers from dom0 ------------------------------------------ - -If you create a USB qube manually, there will be a brief period of time during the boot process when dom0 will be exposed to your USB controllers (and any attached devices). -This is a potential security risk, since even brief exposure to a malicious USB device could result in dom0 being compromised. -There are two approaches to this problem: - -1. Physically disconnect all USB devices whenever you reboot the host. -2. Hide (i.e., blacklist) all USB controllers from dom0. - -**Warning:** If you use a USB [AEM] device, do not use the second option. -Using a USB AEM device requires dom0 to have access to the USB controller to which your USB AEM device is attached. -If dom0 cannot read your USB AEM device, AEM will hang. - -The procedure to hide all USB controllers from dom0 is as follows: - - * GRUB2 - - 1. Open the file `/etc/default/grub` in dom0. - 2. Find the line that begins with `GRUB_CMDLINE_LINUX`. - 3. Add `rd.qubes.hide_all_usb` to that line. - 4. Save and close the file. - 5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0. - 6. Reboot. - - * EFI - - 1. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0. - 2. Find the lines that begin with `kernel=`. There may be more than one. - 3. Add `rd.qubes.hide_all_usb` to those lines. - 4. Save and close the file. - 5. Reboot. - -(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 -first pair of steps in the linked section.) - -**Warning:** A USB keyboard cannot be used to type the disk passphrase if USB controllers were hidden from dom0. -Before hiding USB controllers, make sure your laptop keyboard is not internally connected via USB (by checking output of the `lsusb` command) or that you have a PS/2 keyboard at hand (if using a desktop PC). -Failure to do so will render your system unusable. - - -Removing a USB qube +Additional Reading: ------------------- -**Warning:** This procedure will result in your USB controller(s) being attached directly to dom0. - - * GRUB2 - - 1. Shut down the USB qube. - 2. In Qubes Manager, right-click on the USB qube and select "Remove VM." - 3. Open the file `/etc/default/grub` in dom0. - 4. Find the line(s) that begins with `GRUB_CMDLINE_LINUX`. - 5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it. - 6. Save and close the file. - 7. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0. - 8. Reboot. - - * EFI - - 1. Shut down the USB qube. - 2. In Qubes Manager, right-click on the USB qube and select "Remove VM." - 3. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0. - 4. Find the line(s) that begins with `kernel=`. - 5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it. - 6. Save and close the file. - 7. Reboot. - -Security Warning about USB Input Devices ----------------------------------------- - -**Important security warning. Please read this section carefully!** - -If you connect USB input devices (keyboard and mouse) to a VM, that VM will effectively have control over your system. -Because of this, the benefits of using a USB qube are much smaller than using a fully untrusted USB qube. -In addition to having control over your system, such a VM can also sniff all the input you enter there (for example, passwords in the case of a USB keyboard). - -There is no simple way to protect against sniffing, but you can make it harder to exploit control over input devices. - -If you have only a USB mouse connected to a USB qube, but the keyboard is connected directly to dom0 (using a PS/2 connector, for example), you simply need to lock the screen when you are away from your computer. -You must do this every time you leave your computer unattended, even if there no risk of anyone else having direct physical access to your computer. -This is because you are guarding the system not only against anyone with local access, but also against possible actions from a potentially compromised USB qube. - -If your keyboard is also connected to a USB qube, things are much harder. -Locking the screen (with a traditional password) does not solve the problem, because the USB qube can simply sniff this password and later easily unlock the screen. -One possibility is to set up the screen locker to require an additional step to unlock (i.e., two-factor authentication). -One way to achieve this is to use a [YubiKey], or some other hardware token, or even to manually enter a one-time password. - -How to use a USB keyboard -------------------------- - -**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding. - -If you use USB keyboard, automatic USB qube creation during installation is disabled. -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]. - -### R4.0, using salt ### - -To allow USB keyboard usage (including early boot for LUKS passphrase), make sure you have the latest `qubes-mgmt-salt-dom0-virtual-machines` package (simply [install dom0 updates][dom0-updates]) and execute in dom0: - - sudo qubesctl state.sls qvm.usb-keyboard - -The above command will take care of all required configuration, including creating USB qube if not present. -Note that it will expose dom0 to USB devices while entering LUKS passphrase. -Users are advised to physically disconnect other devices from the system for that time, to minimize the risk. - -If you wish to perform only subset of this configuration (for example do not enable USB keyboard during boot), see manual instructions below. - -### R3.2, manual ### - -In order to use a USB keyboard, you must first attach it to a USB qube, then give that qube permission to pass keyboard input to dom0. -Edit the `qubes.InputKeyboard` policy file in dom0, which is located here: - - /etc/qubes-rpc/policy/qubes.InputKeyboard - -Add a line like this one to the top of the file: - - sys-usb dom0 allow,user=root - -(Change `sys-usb` to your desired USB qube.) - -You can now use your USB keyboard. - -For a confirmation dialog each time the USB keyboard is connected, change this line to: -``` -sys-usb dom0 ask,default_target=dom0 -``` - -Additionally, if you want to use USB keyboard to enter LUKS passphrase, it is incompatible with [hiding USB controllers from dom0][How to hide all 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. - -How to use a USB mouse ----------------------- - -**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding. - -In order to use a USB mouse, you must first attach it to a USB qube, then give that qube permission to pass mouse input to dom0. -The following steps are already done by default if you created the sys-usb qube with `qubesctl state.sls qvm.sys-usb` above, or let Qubes create it for you on first boot. -However, if you've created the USB qube manually: - -Edit the `qubes.InputMouse` policy file in dom0, which is located here: - - /etc/qubes-rpc/policy/qubes.InputMouse - -Add a line like this to the top of the file: - - sys-usb dom0 allow,user=root - -(Change `sys-usb` to your desired USB qube.) - -You can now use your USB mouse. - -For a confirmation dialog each time the USB mouse is connected, change this line to: -``` -sys-usb dom0 ask,default_target=dom0 -``` + - [Creating a USB qube] + - [Using a USB keyboard] [mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class -[Assigning Devices]: /doc/assigning-devices/ -[usb-controller]: /doc/assigning-devices/#finding-the-right-usb-controller -[623]: https://github.com/QubesOS/qubes-issues/issues/623 -[1072-comm1]: https://github.com/QubesOS/qubes-issues/issues/1072#issuecomment-124270051 [1072-comm2]: https://github.com/QubesOS/qubes-issues/issues/1072#issuecomment-124119309 -[2270-comm23]: https://github.com/QubesOS/qubes-issues/issues/2270#issuecomment-242900312 [1082]: https://github.com/QubesOS/qubes-issues/issues/1082 -[hide-usb]: #how-to-hide-all-usb-controllers-from-dom0 -[faq-usbvm]: /faq/#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot -[AEM]: /doc/anti-evil-maid/ -[1618]: https://github.com/QubesOS/qubes-issues/issues/1618 -[create a USB qube]: #creating-and-using-a-usb-qube [usb-challenges]: https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html [YubiKey]: /doc/YubiKey/ -[Security Warning about USB Input Devices]: #security-warning-about-usb-input-devices -[How to hide all USB controllers from dom0]: #how-to-hide-all-usb-controllers-from-dom0 -[qubes-usb-proxy]: https://github.com/QubesOS/qubes-app-linux-usb-proxy -[dom0-updates]: /doc/software-update-dom0/#how-to-update-software-in-dom0 +[Creating a USB qube]: /doc/usb-qube-how-to/ +[Using a USB keyboard]: /doc/usb-qube-how-to/#enable-a-usb-keyboard-for-login \ No newline at end of file diff --git a/configuration/assigning-devices.md b/configuration/assigning-devices.md index d2ee6543..44791fe4 100644 --- a/configuration/assigning-devices.md +++ b/configuration/assigning-devices.md @@ -1,6 +1,6 @@ --- layout: doc -title: Assigning Devices +title: Assigning Devices in R3.2 permalink: /doc/assigning-devices/ redirect_from: - /en/doc/assigning-devices/ @@ -8,8 +8,9 @@ redirect_from: - /wiki/AssigningDevices/ --- -Assigning Devices to VMs -======================== +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 pass-through. @@ -25,31 +26,7 @@ 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 also assigned), then use the device in that VM. This can be useful if, for example, you have only one USB controller, but you have multiple security domains which all require the use of different USB devices. -R4.0 ------------------------- - -In order to assign a whole PCI(e) device to a VM, one should use the `qvm-pci` tool. -First, list the available PCI devices: - -~~~ -qvm-pci -~~~ - -This will show you the `backend:BDF` address of each PCI device. -It will look something like `dom0:00_1a.0`. -Once you've found the address of the device you want to assign, then attach it like so: - -~~~ -qvm-pci attach --persistent : -~~~ - -For example, if `00_1a.0` is the BDF of the device you want to assign to the "personal" domain, you would do this: - -~~~ -qvm-pci attach --persistent personal dom0:00_1a.0 -~~~ - -R3.2 +Using the Commandline ------------------------ In order to assign a whole PCI(e) device to a VM, one should use the `qvm-pci` tool. @@ -83,103 +60,14 @@ This will show you a list of available devices, which you can select to be assig Finding the right USB controller -------------------------------- - -Some USB devices are not compatible with the USB pass-through method Qubes employs. -In situations like this, you can still often get the USB device to work by passing through the entire USB controller to a qube. -However, with this approach one cannot assign single USB devices, only the whole USB controller with whatever USB devices are connected to it. -More information on using and managing USB devices with qubes is available on the [USB] page. -If you want assign a certain USB device to a VM by attaching the whole USB controller, you need to figure out which PCI device is the right controller. -First, check to which USB bus the device is connected (note that these steps need to be run from a terminal inside `dom0`): - -~~~ -lsusb -~~~ - -For example, I want assign a broadband modem to the NetVM. -In the output of `lsusb` it can be listed as something like this. -(In this case, the device isn't fully identified): - -~~~ -Bus 003 Device 003: ID 413c:818d Dell Computer Corp. -~~~ - -The device is connected to USB bus \#3. -Then check which other devices are connected to the same bus, since *all* of them will be assigned to the same VM. -Now is the time to find the right USB controller: - -~~~ -readlink /sys/bus/usb/devices/usb3 -~~~ - -This should output something like: - -~~~ -../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3 -~~~ - -Now you see the BDF address in the path (right before final `usb3`). -Strip the leading `0000:` and pass the rest to the `qvm-pci` tool to attach the controller with the version specific steps above. +This was moved to the [current documentation][finding controller]. Possible issues --------------- +Please refere 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! -### DMA buffer size - -VMs with assigned 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. -To change this allocation, edit VM's kernel parameters (this is expressed in 512B chunks): - -~~~ -# qvm-prefs netvm |grep kernelopts -kernelopts : iommu=soft swiotlb=2048 (default) -# qvm-prefs -s netvm kernelopts "iommu=soft swiotlb=8192" -~~~ - -This is [known to be needed][ml1] for the Realtek RTL8111DL Gigabit Ethernet Controller. - -### PCI passthrough issues - -Sometimes the PCI arbitrator is too strict. -There is a way to enable permissive mode for it. -See also: [this thread][ml2] and the Xen wiki's [PCI passthrough] page. - -**NOTE:** By setting the permissive flag for the PCI device, you're potentially weakening the device isolation, especially if your system is not equipped with a VT-d Interrupt Remapping unit. -See [Software Attacks on Intel VT-d] (page 7) -for more details. - -At other times, you may instead need to disable the FLR requirement on a device. -This will also weaken device isolation; see the "I created a usbVM..." entry in the [FAQ](/doc/user-faq/) for more details. - -R4.0 ------------------------- - -Permissive mode and strict reset are options set as part of PCI device attachment. -If you've already attached the PCI device to a VM, detach it first either with Qube Manager or `qvm-pci`, then list the available PCI devices: - -~~~ -qvm-pci -~~~ - -This will show you the `backend:BDF` address of each PCI device. -It will look something like `dom0:00_1a.0`. -Once you've found the address of the device you want to assign, then attach it like so: - -~~~ -qvm-pci attach --persistent --option [--option ] : -~~~ - -For example, if `00_1a.0` is the BDF of the device you want to assign to the "personal" domain, and it is particularly difficult to pass through you would do this: - -~~~ -qvm-pci attach --persistent --option permissive=true --option no-strict-reset=true personal dom0:00_1a.0 -~~~ - -Running `qvm-pci` again should then show your PCI device attached with both the `permissive` and `no-strict-reset` options set. - -**Note** again that in most cases you should not need either of these options set. -Only set one or more of them as required to get your device to function, or replace the device with one that functions properly with Qubes. - -R3.2 +Enabling permissive mode ------------------------ Permissive mode is enabled system wide per device. @@ -213,31 +101,12 @@ Only set one or more of them as required to get your device to function, or repl Bringing PCI device back to dom0 -------------------------------- +This was moved to the [current documentation][bring back devices]. -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. -A device which was previously assigned to a VM less trusted than dom0 (which, in Qubes, is *all* of them) could attack dom0 if it were automatically reassigned there. - -In order to re-enable the device in dom0, either: - - * Reboot the physical machine. - -or - - * Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver, and attach it back to the original driver. - Replace `` with your full device, for example `0000:00:1c.2`: - - ~~~ - echo > /sys/bus/pci/drivers/pciback/unbind - MODALIAS=`cat /sys/bus/pci/devices//modalias` - MOD=`modprobe -R $MODALIAS | head -n 1` - echo > /sys/bus/pci/drivers/$MOD/bind - ~~~ [usb]: /doc/usb/ -[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 -[Software Attacks on Intel VT-d]: https://invisiblethingslab.com/resources/2011/Software%20Attacks%20on%20Intel%20VT-d.pdf - +[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 \ No newline at end of file From f4fa25d6bff8303c69648ebf54c158622bfdbf3b Mon Sep 17 00:00:00 2001 From: GammaSQ Date: Sat, 5 Jan 2019 14:40:48 +0100 Subject: [PATCH 06/25] fixed typos --- common-tasks/block-devices.md | 6 +++--- common-tasks/device-handling.md | 10 +++++----- common-tasks/pci-devices.md | 14 +++++++------- common-tasks/usb-devices.md | 12 ++++++------ configuration/assigning-devices.md | 4 ++-- configuration/usb-qube-howto.md | 4 ++-- security/device-considerations.md | 4 ++-- 7 files changed, 27 insertions(+), 27 deletions(-) diff --git a/common-tasks/block-devices.md b/common-tasks/block-devices.md index 76af054a..57a49f2b 100644 --- a/common-tasks/block-devices.md +++ b/common-tasks/block-devices.md @@ -49,7 +49,7 @@ If several different block-devices are attached to a single VM, the last letter To specify this device node name, you can pass `--option frontend-dev=[custom-node-name]` to `qvm-block attach`. -#Commandline 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` only sees device-nodes and may not use names you expect! So make sure to have the drive available in the sourceVM before listing available block devices (step 1.) to find out it's its ID. @@ -108,7 +108,7 @@ To attach a file as block device to another qube, first turn it into a loopback 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 commandline, continue: + 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: @@ -125,7 +125,7 @@ To attach a file as block device to another qube, first turn it into a loopback sudo losetup -d /dev/loop0 #Additional Attach Options -Attaching a block device through the commandline 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 ...) diff --git a/common-tasks/device-handling.md b/common-tasks/device-handling.md index 48d1d968..351ade83 100644 --- a/common-tasks/device-handling.md +++ b/common-tasks/device-handling.md @@ -29,7 +29,7 @@ Microphones, block devices and USB devices can be attached with the GUI-tool. PC #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 seperated 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 (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. On most laptops, integrated hardware such as cameras and fingerprint-readers are implemented as USB-devices and can be found here. @@ -42,7 +42,7 @@ To detach a device, click the Qubes Devices Widget icon again. Attached devices ##Attaching a Device to Several VMs -#General `qvm-device` Commandline 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 @@ -62,14 +62,14 @@ All devices, including PCI-devices, may be attached from the commandline using t ##Global Options -These three options are allways available: +These three options are always available: - `--help`, `-h` - show help message and exit - `--verbose`, `-v` - increase verbosity - `--quiet`, `-q` - decrease verbosity -A full command consits 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]` @@ -100,7 +100,7 @@ The `attach` action assigns an exposed device to a VM. This makes the device ava `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 deatching 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! `detach` accepts no options. diff --git a/common-tasks/pci-devices.md b/common-tasks/pci-devices.md index 01a21df8..e65932e8 100644 --- a/common-tasks/pci-devices.md +++ b/common-tasks/pci-devices.md @@ -16,7 +16,7 @@ You may end up with an unusable system by attaching the wrong PCI device to a VM **Security warning:** PCI passthrough should be safe by default, but none-default options may be required. Please make sure you carefully read and understood the **[security considerations]** before deviating from default behavior! -Unlike other devices ([USB], [block], mic), PCI devices need to be attached on VM-bootup. Similar to how you can't attach a new soundcard after your computer booted (and expect it to work properly), attaching PCI devices to already booted VMs isn't possible in any meaningful way. +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 possible in any meaningful way. 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. @@ -37,12 +37,12 @@ The qube settings for a VM offers the "Devices"-tab. There you can attach PCI-de - Press Alt+F3 to open the application finder, type in the VM name, select the "![appmenu]\[VM-name\]: Qube Settings" menu entry and press enter or click "Launch"! - Select the VM in Qube Manager and click the settings-button or right-click the VM and select `Qube settings`. - - Click the Domain Manager ![device manager icon], hover the VM you want to assing a device to and select "settings" in the additional menu. (only running VMs!) + - Click the Domain Manager ![device manager icon], hover the VM you want to attach a device to and select "settings" in the additional menu. (only running VMs!) 2. Select the "Devices" tab on the top bar. 3. Select a device you want to attach to the qube and click the single arrow right! (`>`) 4. You're done. If everything worked out, once the qube boots (or reboots if it's running) it will start with the pci device attached. - 5. In case it doesn't work out, first try disabeling memory-balancing in the settings ("Advanced" tab). If that doesn't help, read on to learn how to disable the strict reset requirement! + 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]. @@ -68,7 +68,7 @@ For example, if `00_1a.0` is the BDF of the device you want to attach to the "wo ##DMA Buffer Size -VMs with assigned PCI devices in Qubes have allocated a small buffer for DMA operations (called swiotlb). +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. To change this allocation, edit VM's kernel parameters (this is expressed in 512B chunks): @@ -86,7 +86,7 @@ There is a way to enable permissive mode for it. See also: [this thread][ml2] and the Xen wiki's [PCI passthrough] page. At other times, you may instead need to disable the FLR requirement on a device. -Both can be acchieved during attachment with `qvm-pci` as described below. +Both can be achieved during attachment with `qvm-pci` as described below. #Additional Attach Options @@ -102,7 +102,7 @@ usage example: qvm-pci a work dom0:00_1a.0 --persistent -o no-strict-reset=true ##permissive -Allow write access to full PCI config space instead of whitlisted 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: @@ -115,7 +115,7 @@ By default, when a device is detached from a VM (or when a VM with an attached P This is an intended feature. -A device which was previously assigned to a VM less trusted than dom0 (which, in Qubes, is *all* of them) could attack dom0 if it were automatically reassigned there. +A device which was previously attached to a VM less trusted than dom0 (which, in Qubes, is *all* of them) could attack dom0 if it were automatically reattached there. In order to re-enable the device in dom0, either: diff --git a/common-tasks/usb-devices.md b/common-tasks/usb-devices.md index d555c4e8..f7dbb2eb 100644 --- a/common-tasks/usb-devices.md +++ b/common-tasks/usb-devices.md @@ -16,10 +16,10 @@ USB Devices in Qubes R4.0 Examples for valid cases for USB-passthrough: - [microcontroller programming] - - using [extarnal audio devices] + - using [external audio devices] - [optical drives] for recording -(If you are thinking to use a two-factor-authentification 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 ##With Qubes Device Manager @@ -66,10 +66,10 @@ When you finish, detach the device. sys-usb:2-5 058f:3822 058f_USB_2.0_Camera sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse -#Maintainence And Customisation +#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, plese 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. @@ -132,9 +132,9 @@ Strip the leading `0000:` and pass the rest to the [`qvm-pci` tool][qvm-pci] to [security considerations]: /doc/device-considerations/#usb-security [usb-challenges]: https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html [microcontroller programming]: https://www.arduino.cc/en/Main/Howto -[extarnal audio devices]: /doc/external-audio/ +[external audio devices]: /doc/external-audio/ [optical drives]: /doc/recording-optical-discs/ -[qubes u2f proxy]: https://www.qubes-os.org/news/2018/09/11/qubes-u2f-proxy/ +[qubes u2f proxy]: /doc/u2f-proxy/ [4661]: https://github.com/QubesOS/qubes-issues/issues/4661 [device manager icon]:https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/devices/media-removable.png [eject icon]:https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/actions/media-eject.png diff --git a/configuration/assigning-devices.md b/configuration/assigning-devices.md index 44791fe4..70955ef8 100644 --- a/configuration/assigning-devices.md +++ b/configuration/assigning-devices.md @@ -26,7 +26,7 @@ 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 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 Commandline +Using the Command Line ------------------------ In order to assign a whole PCI(e) device to a VM, one should use the `qvm-pci` tool. @@ -64,7 +64,7 @@ This was moved to the [current documentation][finding controller]. Possible issues --------------- -Please refere to the [current documentation][possible issues] for an issue description and carefully read the [security implications]! +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 diff --git a/configuration/usb-qube-howto.md b/configuration/usb-qube-howto.md index 047a9a0e..0e7b0a20 100644 --- a/configuration/usb-qube-howto.md +++ b/configuration/usb-qube-howto.md @@ -6,9 +6,9 @@ permalink: /doc/usb-qube-how-to/ USB Qube HowTo ============== -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 necessarry. (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. +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 possiblity to lock yourself out! To avoid this problem [enable your keyboard for login]! +**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 ----------------------------- diff --git a/security/device-considerations.md b/security/device-considerations.md index a2d3f3ad..f47a0b42 100644 --- a/security/device-considerations.md +++ b/security/device-considerations.md @@ -19,9 +19,9 @@ PCI Security ------------ Attaching a PCI device to a qube gives it full control of that device and is vulnerable to any bug 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.) -By default, Qubes requires any PCI device to be resettable from the outside (i.e. via the hyperviser), which completely reinitialises the device. This ensures that any device that was attached to a compromised VM, even if that VM was able to use bugs in the PCI device to inject malicious code, can be trusted again. (Or at least as trusted as it was when Qubes booted.) +By default, Qubes requires any PCI device to be resettable from the outside (i.e. via the hypervisor), which completely reinitialises the device. This ensures that any device that was attached to a compromised VM, even if that VM was able to use bugs in the PCI device to inject malicious code, can be trusted again. (Or at least as trusted as it was when Qubes booted.) -Some devices do not implement a reset option. In these cases, Qubes by default does not allow attaching the device to any VM. If you decide to override this precausion, beware that the device may only be trusted when attached to the first VM. Afterwards, it should be **considered tainted** until the whole system is shut down. Even without malicious intent, uage data may be leaked. +Some devices do not implement a reset option. In these cases, Qubes by default does not allow attaching the device to any VM. If you decide to override this precaution, beware that the device may only be trusted when attached to the first VM. Afterwards, it should be **considered tainted** until the whole system is shut down. Even without malicious intent, usage data may be leaked. 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. See [Software Attacks on Intel VT-d] (page 7) for more details. From 0d6f5c2248d21190b7e99ef710382859dd5318b4 Mon Sep 17 00:00:00 2001 From: GammaSQ Date: Wed, 9 Jan 2019 11:54:47 +0100 Subject: [PATCH 07/25] Changes requested /w obvious solution --- common-tasks/block-devices.md | 28 +++++++++++++++++++++------- common-tasks/device-handling.md | 19 ++++++++++--------- common-tasks/pci-devices.md | 3 +-- common-tasks/usb-devices.md | 16 +++++++++------- configuration/usb-qube-howto.md | 13 ++++--------- security/device-considerations.md | 12 +++++++++--- 6 files changed, 54 insertions(+), 37 deletions(-) diff --git a/common-tasks/block-devices.md b/common-tasks/block-devices.md index 57a49f2b..71c22a68 100644 --- a/common-tasks/block-devices.md +++ b/common-tasks/block-devices.md @@ -43,11 +43,11 @@ If not specified otherwise, block devices will show up as `/dev/xvdi*` in a linu where `xvdi2` needs to be replaced with the partition you want to mount. This will make your drive content accessible under `~/mnt`. -Beware that when you attach a whole block device, partitions can be identified by their trailing integer (i.e. `/dev/xvdi2` for the second partition, `/dev/xvdi` for the whole device), whereas if you attach a single parition, the partition has *no trailing integer*. +Beware that when you attach a whole block device, partitions can be identified by their trailing integer (i.e. `/dev/xvdi2` for the second partition, `/dev/xvdi` for the whole device), whereas if you attach a single parition, the partition has *no trailing integer*. If several different block-devices are attached to a single VM, the last letter of the device node name is advanced through the alphabet, so after `xvdi` the next device will be named `xvdj`, the next `xvdk`, and so on. -To specify this device node name, you can pass `--option frontend-dev=[custom-node-name]` to `qvm-block attach`. +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 The command-line tool you may use to mount whole USB drives or their partitions is `qvm-block`, a shortcut for `qvm-device block`. @@ -60,7 +60,7 @@ In case of a USB-drive, make sure it's attached to your computer. If you don't s qvm-block - This will list all available block devices in your system across all VMs, no matter whether hosted by a USB controller or `losetup`. + This will list all available block devices in your system across all VMs. The name of the qube hosting the block device is displayed before the colon in the device ID. The string after the colon is the ID of the device used within the qube, like so: @@ -95,16 +95,26 @@ In case of a USB-drive, make sure it's attached to your computer. If you don't s qvm-block detach work sys-usb:sdb 6. You may now remove the device or attach it to another qube. - + +#Recovering From Premature Device Destruction +If the you fail to detach the device before it's destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), [there will be problems][premature removal]. + +To recover from this error state, in dom0 run + + virsh detach-disk targetVM xvdi + +(where `targetVM` is to be replaced with the VM name you attached the device to and `xvdi` is to be replaced with the used [frontend device node][frontend-dev].) + +However, if the block device originated in dom0, you will have to refer to the [old way][detach dom0 device]. #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 - sudo losetup /dev/loop0 /path/to/file + sudo losetup -f --show /path/to/file - (increase the trailing integer if `loop0` is already in use or use other name. This is just a generic device-id.) + [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. @@ -165,4 +175,8 @@ This option accepts `cdrom` and `disk`, default is `disk`. [device handling in qubes]: /doc/device-handling/ [mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class [device manager icon]:https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/devices/media-removable.png -[USB]:/dock/usb-devices-in-qubes-R4.0/ \ No newline at end of file +[frontend-dev]: #frontend-dev +[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]:/dock/usb-devices-in-qubes-R4.0/ diff --git a/common-tasks/device-handling.md b/common-tasks/device-handling.md index 351ade83..ca5eaab3 100644 --- a/common-tasks/device-handling.md +++ b/common-tasks/device-handling.md @@ -23,10 +23,7 @@ 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 require the command line tool. - -#Security Considerations - +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. @@ -40,7 +37,9 @@ Click the tray icon. Hover on a device you want to attach to a VM. A list of run 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. + +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 All devices, including PCI-devices, may be attached from the commandline using the `qvm-device`-tools. @@ -78,7 +77,7 @@ A full command consists of one DEVICE_CLASS and one action. If no action is give 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. +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: @@ -102,11 +101,12 @@ 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! +If no specific `sourceVM:deviceID` combination is given, *all devices of that DEVICE_CLASS will be detached.* + `detach` accepts no options. **SYNOPSIS** -`qvm-device DEVICE_CLASS {detach|dt|d} targetVM sourceVM:deviceID` - +`qvm-device DEVICE_CLASS {detach|dt|d} targetVM [sourceVM:deviceID]` [block]:/doc/block-devices-in-qubes-R4.0/ @@ -115,4 +115,5 @@ The `detach` action removes an assigned device from a targetVM. It won't be avai [security considerations]: /doc/device-considerations/ [device manager icon]: https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/devices/media-removable.png -[eject icon]: https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/actions/media-eject.png \ No newline at end of file +[eject icon]: https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/actions/media-eject.png +[i4692]: https://github.com/QubesOS/qubes-issues/issues/4692 diff --git a/common-tasks/pci-devices.md b/common-tasks/pci-devices.md index e65932e8..49fe5e65 100644 --- a/common-tasks/pci-devices.md +++ b/common-tasks/pci-devices.md @@ -132,7 +132,6 @@ or echo > /sys/bus/pci/drivers/$MOD/bind It is **strongly discouraged to reattach PCI devices to dom0**, especially if they don't support resetting! - [device handling in qubes]: /doc/device-handling/ @@ -145,4 +144,4 @@ or [side channel attacks]: https://en.wikipedia.org/wiki/Side-channel_attack [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 \ No newline at end of file +[PCI passthrough]: https://wiki.xen.org/wiki/Xen_PCI_Passthrough diff --git a/common-tasks/usb-devices.md b/common-tasks/usb-devices.md index f7dbb2eb..20d3a3ce 100644 --- a/common-tasks/usb-devices.md +++ b/common-tasks/usb-devices.md @@ -24,7 +24,7 @@ Examples for valid cases for USB-passthrough: #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. +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. @@ -42,6 +42,7 @@ In dom0, you can use `qvm-usb` from the commandline to attach and detach devices Listing available USB devices: [user@dom0 ~]$ qvm-usb + BACKEND:DEVID DESCRIPTION USED BY 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 @@ -50,10 +51,10 @@ Attaching selected USB device: [user@dom0 ~]$ qvm-usb attach work sys-usb:2-5 [user@dom0 ~]$ qvm-usb - work:2-1 058f:3822 058f_USB_2.0_Camera + BACKEND:DEVID DESCRIPTION USED BY sys-usb:2-4 04ca:300d 04ca_300d - sys-usb:2-5 058f:3822 058f_USB_2.0_Camera (attached to work) - sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse + sys-usb:2-5 058f:3822 058f_USB_2.0_Camera work + sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse Now, you can use your USB device (camera in this case) in the `work` qube. If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section]. @@ -62,9 +63,10 @@ When you finish, detach the device. [user@dom0 ~]$ qvm-usb detach work sys-usb:2-5 [user@dom0 ~]$ qvm-usb + BACKEND:DEVID DESCRIPTION USED BY 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 + sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse #Maintenance And Customisation @@ -90,7 +92,6 @@ Mouse and keyboard setup are part of [setting up a USB-qube][keyboard setup]. ##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,6 +132,7 @@ Strip the leading `0000:` and pass the rest to the [`qvm-pci` tool][qvm-pci] to [block device]: /doc/block-devices-in-qubes-R4.0/ [security considerations]: /doc/device-considerations/#usb-security [usb-challenges]: https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html +[usb icon]: https://raw.githubusercontent.com/QubesOS/qubes-desktop-linux-manager/master/icons/22x22/generic-usb.png [microcontroller programming]: https://www.arduino.cc/en/Main/Howto [external audio devices]: /doc/external-audio/ [optical drives]: /doc/recording-optical-discs/ @@ -141,4 +143,4 @@ Strip the leading `0000:` and pass the rest to the [`qvm-pci` tool][qvm-pci] to [Installation Section]:#installation-of-qubes-usb-proxy [USB-qube howto]: /doc/usb-qube-howto/ [keyboard setup]: /doc/usb-qube-howto/#enable-a-usb-keyboard-for-login -[qvm-pci]: /doc/pci-devices-in-qubes-R4.0/ \ No newline at end of file +[qvm-pci]: /doc/pci-devices-in-qubes-R4.0/ diff --git a/configuration/usb-qube-howto.md b/configuration/usb-qube-howto.md index 0e7b0a20..fac73ecf 100644 --- a/configuration/usb-qube-howto.md +++ b/configuration/usb-qube-howto.md @@ -17,13 +17,7 @@ Creating and Using a USB qube There are problems with doing this in an encrypted install (LUKS). If you find yourself in this situation, see this [issue][2270-comm23]. -The connection of an untrusted USB device to dom0 is a security risk since dom0, like almost every OS, reads partition tables automatically. -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. - -To avoid this risk, it is possible to prepare and utilize a USB qube. - -A USB qube acts as a secure handler for potentially malicious USB devices, preventing them from coming into contact with dom0 (which could otherwise be fatal to the security of the whole system). +A USB qube acts as a secure handler for potentially malicious USB devices, preventing them from coming into contact with dom0 (which could otherwise be fatal to the security of the whole system). It thereby mitigates some of the [security implications] of using USB devices. With a USB qube, every time you connect an untrusted USB drive to a USB port managed by that USB controller, you will have to attach it to the qube in which you wish to use it (if different from the USB qube itself), either by using Qubes VM Manager or the command line (see instructions above). The USB controller may be assigned on the **Devices** tab of a qube's settings page in Qubes VM Manager or by using the [qvm-pci][PCI Devices] command. For guidance on finding the correct USB controller, see the [according passage on PCI-devices][usb-controller]. @@ -120,9 +114,9 @@ which will ask for conformation each time a USB mouse is attached. If the file i In case you are absolutely sure you do not want to confirm mouse access from `sys-usb` to `dom0`, you may add the following line on top of the file: - sys-usb dom0 allow,user=root + sys-usb dom0 allow -(Change `sys-usb` to your desired USB qube.) +(Change `sys-usb` to your desired USB qube.) How to hide all USB controllers from dom0 @@ -197,6 +191,7 @@ Removing a USB qube [remove your USB-qube]: #removing-a-usb-qube +[security implications]: /doc/device-considerations/#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/ diff --git a/security/device-considerations.md b/security/device-considerations.md index f47a0b42..906ef611 100644 --- a/security/device-considerations.md +++ b/security/device-considerations.md @@ -17,7 +17,8 @@ Attaching a full block device (e.g. `sda`) again offers more attack surface than PCI Security ------------ -Attaching a PCI device to a qube gives it full control of that device and is vulnerable to any bug 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.) +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 controll 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.) By default, Qubes requires any PCI device to be resettable from the outside (i.e. via the hypervisor), which completely reinitialises the device. This ensures that any device that was attached to a compromised VM, even if that VM was able to use bugs in the PCI device to inject malicious code, can be trusted again. (Or at least as trusted as it was when Qubes booted.) @@ -28,7 +29,11 @@ See [Software Attacks on Intel VT-d] (page 7) for more details. USB Security ------------ -While PCI devices generally are part of your computer and thereby hard to manipulate physically, USB devices are attached all the time on the fly and thereby pose a much easier accessible attack vector. +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. + +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. @@ -36,7 +41,7 @@ If possible, use a method specific for particular device type (for example, bloc **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] are much smaller than using a fully untrusted USB qube. +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). There is no simple way to protect against sniffing, but you can make it harder to exploit control over input devices. @@ -53,6 +58,7 @@ 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" +[rubber duck]: https://shop.hak5.org/products/usb-rubber-ducky-deluxe [USB qube]: /doc/usb-qube-how-to/ [YubiKey]: /doc/YubiKey/ [qubes u2f proxy]: https://www.qubes-os.org/news/2018/09/11/qubes-u2f-proxy/ From e53477238850d8e3c5644cfdcd7e314f76efdb65 Mon Sep 17 00:00:00 2001 From: GammaSQ Date: Wed, 9 Jan 2019 12:10:03 +0100 Subject: [PATCH 08/25] Further requested changes These changes are with reservations. I'm not 100% sure I understood what was requested. --- configuration/usb-qube-howto.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/configuration/usb-qube-howto.md b/configuration/usb-qube-howto.md index fac73ecf..b7b0fbd1 100644 --- a/configuration/usb-qube-howto.md +++ b/configuration/usb-qube-howto.md @@ -67,14 +67,13 @@ To allow USB keyboard usage (including early boot for LUKS passphrase), make sur The above command will take care of all required configuration, including creating USB qube if not present. Note that it will expose dom0 to USB devices while entering LUKS passphrase. Users are advised to physically disconnect other devices from the system for that time, to minimize the risk. - -If you wish to perform only subset of this configuration (for example do not enable USB keyboard during boot), see manual instructions below. +To undo these changes, please follow the section on [**Removing a USB qube**][remove your USB-qube]! + +If you wish to perform only a subset of this configuration (for example do not enable USB keyboard during boot), see manual instructions below. ### Manual setup ### - - In order to use a USB keyboard, you must first attach it to a USB qube, then give that qube permission to pass keyboard input to dom0. Edit the `qubes.InputKeyboard` policy file in dom0, which is located here: @@ -82,16 +81,18 @@ Edit the `qubes.InputKeyboard` policy file in dom0, which is located here: Add a line like this one to the top of the file: - sys-usb dom0 allow,user=root + sys-usb dom0 allow (Change `sys-usb` to your desired USB qube.) -You can now use your USB keyboard. +You can now use your USB keyboard to login and for LUKS decryption during boot. -For a confirmation dialog each time the USB keyboard is connected, change this line to: +For a confirmation dialog each time the USB keyboard is connected, *which will effectively disable your USB keyboard for login and LUKS decryption*, change this line to: sys-usb dom0 ask,default_target=dom0 +*Don't do that if you want to unlock your device with a USB keyboard!* + Additionally, if you want to use USB keyboard to enter LUKS passphrase, it is incompatible with [hiding USB controllers from dom0]. You need to revert that procedure (remove `rd.qubes.hide_all_usb` option from files mentioned there) and employ alternative protection during system boot - disconnect other devices during startup. From f6e5afae23222aa743920f96782baacfbd2e1300 Mon Sep 17 00:00:00 2001 From: GammaSQ Date: Wed, 9 Jan 2019 12:26:51 +0100 Subject: [PATCH 09/25] forgot to save some files --- common-tasks/block-devices.md | 2 +- configuration/usb-qube-howto.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/common-tasks/block-devices.md b/common-tasks/block-devices.md index 71c22a68..6340dd08 100644 --- a/common-tasks/block-devices.md +++ b/common-tasks/block-devices.md @@ -52,7 +52,7 @@ To specify this device node name, you need to use the command line tool and its #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` only sees device-nodes and may not use names you expect! So make sure to have the drive available in the sourceVM before listing available block devices (step 1.) to find out it's its ID. +`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`) diff --git a/configuration/usb-qube-howto.md b/configuration/usb-qube-howto.md index b7b0fbd1..6d3815cd 100644 --- a/configuration/usb-qube-howto.md +++ b/configuration/usb-qube-howto.md @@ -196,7 +196,7 @@ Removing a USB qube [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/ -[usb-controller]: +[device manager icon]: https://raw.githubusercontent.com/GammaSQ/qubes-attachment/doc-device-rework/wiki/Devices/media-removable.png [eject icon]: https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/actions/media-eject.png [i4692]: https://github.com/QubesOS/qubes-issues/issues/4692 diff --git a/common-tasks/pci-devices.md b/common-tasks/pci-devices.md index 49fe5e65..2660bb80 100644 --- a/common-tasks/pci-devices.md +++ b/common-tasks/pci-devices.md @@ -14,16 +14,14 @@ PCI Devices in Qubes R4.0 **Warning:** Only dom0 exposes PCI devices. Some of them are strictly required in dom0! (e.g. host bridge) You may end up with an unusable system by attaching the wrong PCI device to a VM. -**Security warning:** PCI passthrough should be safe by default, but none-default options may be required. Please make sure you carefully read and understood 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! -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 possible in any meaningful way. +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. -Note that one can only attach 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 attached to the same qube unless you have disabled the strict requirement with the `no-strict-reset` option during attachment. +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 aformentioned [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. diff --git a/common-tasks/usb-devices.md b/common-tasks/usb-devices.md index 20d3a3ce..ae7c2601 100644 --- a/common-tasks/usb-devices.md +++ b/common-tasks/usb-devices.md @@ -138,7 +138,7 @@ Strip the leading `0000:` and pass the rest to the [`qvm-pci` tool][qvm-pci] to [optical drives]: /doc/recording-optical-discs/ [qubes u2f proxy]: /doc/u2f-proxy/ [4661]: https://github.com/QubesOS/qubes-issues/issues/4661 -[device manager icon]:https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/devices/media-removable.png +[device manager icon]:https://raw.githubusercontent.com/GammaSQ/qubes-attachment/doc-device-rework/wiki/Devices/media-removable.png [eject icon]:https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/actions/media-eject.png [Installation Section]:#installation-of-qubes-usb-proxy [USB-qube howto]: /doc/usb-qube-howto/ diff --git a/security/device-considerations.md b/security/device-considerations.md index 906ef611..c70647a6 100644 --- a/security/device-considerations.md +++ b/security/device-considerations.md @@ -24,8 +24,10 @@ By default, Qubes requires any PCI device to be resettable from the outside (i.e Some devices do not implement a reset option. In these cases, Qubes by default does not allow attaching the device to any VM. If you decide to override this precaution, beware that the device may only be trusted when attached to the first VM. Afterwards, it should be **considered tainted** until the whole system is shut down. Even without malicious intent, usage data may be leaked. +In case device reset is disabled for any reason, detaching the device should be considered a risk. Ideally, devices for which the `no-strict-reset` option is set are attached once to a VM which isn't shut down until the system is shut down. + 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. -See [Software Attacks on Intel VT-d] (page 7) for more details. +See [Software Attacks on Intel VT-d] \(page 7) for more details. USB Security ------------ From 6f8693ad20736d1968b2c66bbbaf5d0ada3ed53c Mon Sep 17 00:00:00 2001 From: GammaSQ Date: Wed, 27 Feb 2019 14:32:46 +0100 Subject: [PATCH 11/25] Changed media-removable url to local /attachment/-url --- common-tasks/device-handling.md | 2 +- common-tasks/usb-devices.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/common-tasks/device-handling.md b/common-tasks/device-handling.md index 1ef63fc4..da6119f8 100644 --- a/common-tasks/device-handling.md +++ b/common-tasks/device-handling.md @@ -114,6 +114,6 @@ If no specific `sourceVM:deviceID` combination is given, *all devices of that DE [PCI]:/doc/pci-devices-in-qubes-R4.0/ [security considerations]: /doc/device-considerations/ -[device manager icon]: https://raw.githubusercontent.com/GammaSQ/qubes-attachment/doc-device-rework/wiki/Devices/media-removable.png +[device manager icon]: /attachment/wiki/Devices/media-removable.png [eject icon]: https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/actions/media-eject.png [i4692]: https://github.com/QubesOS/qubes-issues/issues/4692 diff --git a/common-tasks/usb-devices.md b/common-tasks/usb-devices.md index ae7c2601..0b7d256c 100644 --- a/common-tasks/usb-devices.md +++ b/common-tasks/usb-devices.md @@ -138,7 +138,7 @@ Strip the leading `0000:` and pass the rest to the [`qvm-pci` tool][qvm-pci] to [optical drives]: /doc/recording-optical-discs/ [qubes u2f proxy]: /doc/u2f-proxy/ [4661]: https://github.com/QubesOS/qubes-issues/issues/4661 -[device manager icon]:https://raw.githubusercontent.com/GammaSQ/qubes-attachment/doc-device-rework/wiki/Devices/media-removable.png +[device manager icon]:/attachment/wiki/Devices/media-removable.png [eject icon]:https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/actions/media-eject.png [Installation Section]:#installation-of-qubes-usb-proxy [USB-qube howto]: /doc/usb-qube-howto/ From a600c1863b7c9587a90a0473ca4424f4f3a7dcfb Mon Sep 17 00:00:00 2001 From: GammaSQ Date: Mon, 4 Mar 2019 17:50:21 +0100 Subject: [PATCH 12/25] changed .png-links to qubes-attachment links --- common-tasks/device-handling.md | 2 +- common-tasks/pci-devices.md | 4 ++-- common-tasks/usb-devices.md | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/common-tasks/device-handling.md b/common-tasks/device-handling.md index da6119f8..fbdab2c1 100644 --- a/common-tasks/device-handling.md +++ b/common-tasks/device-handling.md @@ -115,5 +115,5 @@ If no specific `sourceVM:deviceID` combination is given, *all devices of that DE [security considerations]: /doc/device-considerations/ [device manager icon]: /attachment/wiki/Devices/media-removable.png -[eject icon]: https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/actions/media-eject.png +[eject icon]: /attachment/wiki/Devices/media-eject.png [i4692]: https://github.com/QubesOS/qubes-issues/issues/4692 diff --git a/common-tasks/pci-devices.md b/common-tasks/pci-devices.md index 2660bb80..089d4bbb 100644 --- a/common-tasks/pci-devices.md +++ b/common-tasks/pci-devices.md @@ -136,8 +136,8 @@ or [security considerations]: /doc/device-considerations/#pci-security [block]:/doc/block-devices-in-qubes-R4.0/ [USB]:/dock/usb-devices-in-qubes-R4.0/ -[appmenu]: https://raw.githubusercontent.com/QubesOS/qubes-artwork/master/icons/32x32/apps/qubes-appmenu-select.png -[domain manager icon]: https://raw.githubusercontent.com/QubesOS/qubes-artwork/master/icons/32x32/apps/qubes-logo-icon.png +[appmenu]: /attachment/wiki/Devices/qubes-appmenu-select.png +[domain manager icon]: /attachment/wiki/Devices/qubes-logo-icon.png [qvm-device]: /doc/device-handling-in-qubes-R4.0/#general-qubes-device-widget-behavior-and-handling [side channel attacks]: https://en.wikipedia.org/wiki/Side-channel_attack [ml1]: https://groups.google.com/group/qubes-devel/browse_thread/thread/631c4a3a9d1186e3 diff --git a/common-tasks/usb-devices.md b/common-tasks/usb-devices.md index 0b7d256c..7b7a2ee2 100644 --- a/common-tasks/usb-devices.md +++ b/common-tasks/usb-devices.md @@ -132,14 +132,14 @@ Strip the leading `0000:` and pass the rest to the [`qvm-pci` tool][qvm-pci] to [block device]: /doc/block-devices-in-qubes-R4.0/ [security considerations]: /doc/device-considerations/#usb-security [usb-challenges]: https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html -[usb icon]: https://raw.githubusercontent.com/QubesOS/qubes-desktop-linux-manager/master/icons/22x22/generic-usb.png +[usb icon]: /attachment/wiki/Devices/generic-usb.png [microcontroller programming]: https://www.arduino.cc/en/Main/Howto [external audio devices]: /doc/external-audio/ [optical drives]: /doc/recording-optical-discs/ [qubes u2f proxy]: /doc/u2f-proxy/ [4661]: https://github.com/QubesOS/qubes-issues/issues/4661 [device manager icon]:/attachment/wiki/Devices/media-removable.png -[eject icon]:https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/actions/media-eject.png +[eject icon]:/attachment/wiki/Devices/media-eject.png [Installation Section]:#installation-of-qubes-usb-proxy [USB-qube howto]: /doc/usb-qube-howto/ [keyboard setup]: /doc/usb-qube-howto/#enable-a-usb-keyboard-for-login From af4c726b289e08e6c705f5a1c9c4363fc240f36b Mon Sep 17 00:00:00 2001 From: GammaSQ Date: Mon, 4 Mar 2019 19:46:10 +0100 Subject: [PATCH 13/25] Linked block-devices in USB-device-page --- common-tasks/usb-devices.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/common-tasks/usb-devices.md b/common-tasks/usb-devices.md index 7b7a2ee2..559187d5 100644 --- a/common-tasks/usb-devices.md +++ b/common-tasks/usb-devices.md @@ -11,6 +11,8 @@ USB Devices in Qubes R4.0 *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]. + **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! Examples for valid cases for USB-passthrough: From 1789ff6ddbb16dab4781b16b194fa4fb40af867c Mon Sep 17 00:00:00 2001 From: GammaSQ Date: Mon, 4 Mar 2019 21:43:13 +0100 Subject: [PATCH 14/25] Naivly merging block-devices and usb-devices --- common-tasks/block-devices.md | 182 -------------------------------- common-tasks/device-handling.md | 4 +- common-tasks/pci-devices.md | 4 +- common-tasks/usb-devices.md | 177 ++++++++++++++++++++++++++++++- 4 files changed, 177 insertions(+), 190 deletions(-) delete mode 100644 common-tasks/block-devices.md diff --git a/common-tasks/block-devices.md b/common-tasks/block-devices.md deleted file mode 100644 index 6340dd08..00000000 --- a/common-tasks/block-devices.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -layout: doc -title: Block or Storage Devices in Qubes R4.0 -permalink: /doc/block-devices/ -redirect_from: -- /doc/block-devices-in-qubes-R4.0/ ---- - -Block or Storage Devices in Qubes R4.0 -====================================== -*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 -(**Note:** In the present context, the term "USB drive" denotes any [USB mass storage device][mass-storage]. -In addition to smaller flash memory sticks, this includes things like USB external hard drives.) - -Qubes OS supports the ability to attach a USB drive (or just its partitions) to any qube easily, no matter which qube handles the USB controller. - -Attaching USB drives is integrated into the Devices Widget: ![device manager icon] -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`). - -The simplest option is to attach the entire block drive. -In our example, this is `sys-usb:sda`, so hover over it. -This will pop up a submenu showing running VMs to which the USB drive can be connected. -Click on one and your USB drive will be attached! - -**Note:** attaching individual partitions (e.g. `sys-usb:sda1`) 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. - -#Block Devices in VMs -If not specified otherwise, block devices will show up as `/dev/xvdi*` in a linux VM, where `*` may be the partition-number. If a block device isn't automatically mounted after attaching, open a terminal in the VM and execute: - - cd ~ - mkdir mnt - sudo mount /dev/xvdi2 mnt - -where `xvdi2` needs to be replaced with the partition you want to mount. -This will make your drive content accessible under `~/mnt`. - -Beware that when you attach a whole block device, partitions can be identified by their trailing integer (i.e. `/dev/xvdi2` for the second partition, `/dev/xvdi` for the whole device), whereas if you attach a single parition, the partition has *no trailing integer*. - -If several different block-devices are attached to a single VM, the last letter of the device node name is advanced through the alphabet, so after `xvdi` the next device will be named `xvdj`, the next `xvdk`, and so on. - -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 -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. - -In case of a USB-drive, make sure it's attached to your computer. If you don't see anything that looks like your drive, run `sudo udevadm trigger --action=change` in your USB-qube (typically `sys-usb`) - - 1. In a dom0 console (running as a normal user), list all available block devices: - - qvm-block - - This will list all available block devices in your system across all VMs. - The name of the qube hosting the block device is displayed before the colon in the device ID. - The string after the colon is the ID of the device used within the qube, like so: - - sourceVM:sdb Cruzer () 4GiB - sourceVM:sdb1 Disk () 2GiB - - 2. Assuming your block device is attached to `sys-usb` and its device node is `sdb`, we attach the device to a qube with the name `work` like so: - - qvm-block attach work sys-usb:sdb - - This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc. - - You may also mount one partition at a time by using the same command with the partition number, e.g. `sdb1`. - - 3. The block device is now attached to the qube. - If using a default qube, you may open the Nautilus file manager in the qube, and your drive should be visible in the **Devices** panel on the left. - If you've attached a single partition (e.g. `sdb2` instead of `sdb` in our example), you may need to manually mount before it becomes visible: - - cd ~ - mkdir mnt - sudo mount /dev/xvdi mnt - - - 4. When you finish using the block device, click the eject button or right-click and select **Unmount**. - - If you've manually mounted a single partition in the above step, use: - - sudo umount mnt - - 5. In a dom0 console, detach the device - - qvm-block detach work sys-usb:sdb - - 6. You may now remove the device or attach it to another qube. - -#Recovering From Premature Device Destruction -If the you fail to detach the device before it's destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), [there will be problems][premature removal]. - -To recover from this error state, in dom0 run - - virsh detach-disk targetVM xvdi - -(where `targetVM` is to be replaced with the VM name you attached the device to and `xvdi` is to be replaced with the used [frontend device node][frontend-dev].) - -However, if the block device originated in dom0, you will have to refer to the [old way][detach dom0 device]. - -#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 - - sudo losetup -f --show /path/to/file - - [This command][losetup] will create the device node `/dev/loop0` or, if that is already in use, increase the trailing integer until that name is still available. Afterwards it prints the device-node-name it found. - - 2. If you want to use the GUI, you're done. 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: - - ~]$ qvm-block - BACKEND:DEVID DESCRIPTION USED BY - sourceVM:loop0 /path/to/file - - 3. Attach the `loop0`-device using qvm-block as usual: - - qvm-block a targetVM sourceVM:loop0 - - 4. After detaching, destroy the loop-device inside the sourceVM as follows: - - sudo losetup -d /dev/loop0 - -#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 -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: - - qvm-block a work sys-usb:sda1 -o frontend-dev=xvdz - -This command will attach the partition `sda1` to `work` as `/dev/xvdz`. - -##read-only -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. - -usage example: - - qvm-block a work sys-usb:sda1 -o read-only=true - -There exists a shortcut to set read-only `true`, `--ro`: - - qvm-block a work sys-usb:sda1 --ro - -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. - -usage example: - - qvm-block a work sys-usb:sda1 -o devtype=cdrom - -This option accepts `cdrom` and `disk`, default is `disk`. - - - -[device handling in qubes]: /doc/device-handling/ -[mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class -[device manager icon]:https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/devices/media-removable.png -[frontend-dev]: #frontend-dev -[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]:/dock/usb-devices-in-qubes-R4.0/ diff --git a/common-tasks/device-handling.md b/common-tasks/device-handling.md index fbdab2c1..1d09aea4 100644 --- a/common-tasks/device-handling.md +++ b/common-tasks/device-handling.md @@ -109,8 +109,8 @@ 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/ -[USB]:/dock/usb-devices-in-qubes-R4.0/ +[block]:/doc/usb-devices-in-qubes-R4.0/#drives-and-block-devices +[USB]:/dock/usb-devices-in-qubes-R4.0/#handling-other-usb-devices [PCI]:/doc/pci-devices-in-qubes-R4.0/ [security considerations]: /doc/device-considerations/ diff --git a/common-tasks/pci-devices.md b/common-tasks/pci-devices.md index 089d4bbb..4f90d521 100644 --- a/common-tasks/pci-devices.md +++ b/common-tasks/pci-devices.md @@ -134,8 +134,8 @@ or [device handling in qubes]: /doc/device-handling/ [security considerations]: /doc/device-considerations/#pci-security -[block]:/doc/block-devices-in-qubes-R4.0/ -[USB]:/dock/usb-devices-in-qubes-R4.0/ +[block]:/dock/usb-devices-in-qubes-R4.0/#drives-and-block-devices +[USB]:/dock/usb-devices-in-qubes-R4.0/#handling-other-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-in-qubes-R4.0/#general-qubes-device-widget-behavior-and-handling diff --git a/common-tasks/usb-devices.md b/common-tasks/usb-devices.md index 559187d5..29e62b07 100644 --- a/common-tasks/usb-devices.md +++ b/common-tasks/usb-devices.md @@ -6,13 +6,174 @@ redirect_from: - /doc/usb-devices-in-qubes-R4.0/ --- -USB Devices in Qubes R4.0 -========================== +USB and Storage Devices in Qubes R4.0 +===================================== *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]. +Drives And Block Devices +======================== +This part describes how to handle drives, referred to as "block device". 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 +(**Note:** In the present context, the term "USB drive" denotes any [USB mass storage device][mass-storage]. +In addition to smaller flash memory sticks, this includes things like USB external hard drives.) + +Qubes OS supports the ability to attach a USB drive (or just its partitions) to any qube easily, no matter which qube handles the USB controller. + +Attaching USB drives is integrated into the Devices Widget: ![device manager icon] +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`). + +The simplest option is to attach the entire block drive. +In our example, this is `sys-usb:sda`, so hover over it. +This will pop up a submenu showing running VMs to which the USB drive can be connected. +Click on one and your USB drive will be attached! + +**Note:** attaching individual partitions (e.g. `sys-usb:sda1`) 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. + +#Block Devices in VMs +If not specified otherwise, block devices will show up as `/dev/xvdi*` in a linux VM, where `*` may be the partition-number. If a block device isn't automatically mounted after attaching, open a terminal in the VM and execute: + + cd ~ + mkdir mnt + sudo mount /dev/xvdi2 mnt + +where `xvdi2` needs to be replaced with the partition you want to mount. +This will make your drive content accessible under `~/mnt`. + +Beware that when you attach a whole block device, partitions can be identified by their trailing integer (i.e. `/dev/xvdi2` for the second partition, `/dev/xvdi` for the whole device), whereas if you attach a single parition, the partition has *no trailing integer*. + +If several different block-devices are attached to a single VM, the last letter of the device node name is advanced through the alphabet, so after `xvdi` the next device will be named `xvdj`, the next `xvdk`, and so on. + +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 +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. + +In case of a USB-drive, make sure it's attached to your computer. If you don't see anything that looks like your drive, run `sudo udevadm trigger --action=change` in your USB-qube (typically `sys-usb`) + + 1. In a dom0 console (running as a normal user), list all available block devices: + + qvm-block + + This will list all available block devices in your system across all VMs. + The name of the qube hosting the block device is displayed before the colon in the device ID. + The string after the colon is the ID of the device used within the qube, like so: + + sourceVM:sdb Cruzer () 4GiB + sourceVM:sdb1 Disk () 2GiB + + 2. Assuming your block device is attached to `sys-usb` and its device node is `sdb`, we attach the device to a qube with the name `work` like so: + + qvm-block attach work sys-usb:sdb + + This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc. + + You may also mount one partition at a time by using the same command with the partition number, e.g. `sdb1`. + + 3. The block device is now attached to the qube. + If using a default qube, you may open the Nautilus file manager in the qube, and your drive should be visible in the **Devices** panel on the left. + If you've attached a single partition (e.g. `sdb2` instead of `sdb` in our example), you may need to manually mount before it becomes visible: + + cd ~ + mkdir mnt + sudo mount /dev/xvdi mnt + + + 4. When you finish using the block device, click the eject button or right-click and select **Unmount**. + + If you've manually mounted a single partition in the above step, use: + + sudo umount mnt + + 5. In a dom0 console, detach the device + + qvm-block detach work sys-usb:sdb + + 6. You may now remove the device or attach it to another qube. + +#Recovering From Premature Device Destruction +If the you fail to detach the device before it's destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), [there will be problems][premature removal]. + +To recover from this error state, in dom0 run + + virsh detach-disk targetVM xvdi + +(where `targetVM` is to be replaced with the VM name you attached the device to and `xvdi` is to be replaced with the used [frontend device node][frontend-dev].) + +However, if the block device originated in dom0, you will have to refer to the [old way][detach dom0 device]. + +#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 + + sudo losetup -f --show /path/to/file + + [This command][losetup] will create the device node `/dev/loop0` or, if that is already in use, increase the trailing integer until that name is still available. Afterwards it prints the device-node-name it found. + + 2. If you want to use the GUI, you're done. 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: + + ~]$ qvm-block + BACKEND:DEVID DESCRIPTION USED BY + sourceVM:loop0 /path/to/file + + 3. Attach the `loop0`-device using qvm-block as usual: + + qvm-block a targetVM sourceVM:loop0 + + 4. After detaching, destroy the loop-device inside the sourceVM as follows: + + sudo losetup -d /dev/loop0 + +#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 +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: + + qvm-block a work sys-usb:sda1 -o frontend-dev=xvdz + +This command will attach the partition `sda1` to `work` as `/dev/xvdz`. + +##read-only +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. + +usage example: + + qvm-block a work sys-usb:sda1 -o read-only=true + +There exists a shortcut to set read-only `true`, `--ro`: + + qvm-block a work sys-usb:sda1 --ro + +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. + +usage example: + + qvm-block a work sys-usb:sda1 -o devtype=cdrom + +This option accepts `cdrom` and `disk`, default is `disk`. + +Handling other USB Devices +========================== **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! Examples for valid cases for USB-passthrough: @@ -131,7 +292,7 @@ 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]: #drives-and-block-devices [security considerations]: /doc/device-considerations/#usb-security [usb-challenges]: https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html [usb icon]: /attachment/wiki/Devices/generic-usb.png @@ -146,3 +307,11 @@ Strip the leading `0000:` and pass the rest to the [`qvm-pci` tool][qvm-pci] to [USB-qube howto]: /doc/usb-qube-howto/ [keyboard setup]: /doc/usb-qube-howto/#enable-a-usb-keyboard-for-login [qvm-pci]: /doc/pci-devices-in-qubes-R4.0/ + +[device handling in qubes]: /doc/device-handling/ +[mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class +[frontend-dev]: #frontend-dev +[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]:/dock/usb-devices-in-qubes-R4.0/ From afa8308c4686bd9fdb39f5b5b11086c0941577cb Mon Sep 17 00:00:00 2001 From: GammaSQ Date: Mon, 4 Mar 2019 23:06:28 +0100 Subject: [PATCH 15/25] Merging usb & block by paragraphs --- common-tasks/device-handling.md | 4 +- common-tasks/pci-devices.md | 4 +- common-tasks/usb-devices.md | 159 +++++++++++++++----------------- 3 files changed, 79 insertions(+), 88 deletions(-) diff --git a/common-tasks/device-handling.md b/common-tasks/device-handling.md index 1d09aea4..e711b7d7 100644 --- a/common-tasks/device-handling.md +++ b/common-tasks/device-handling.md @@ -109,8 +109,8 @@ 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/usb-devices-in-qubes-R4.0/#drives-and-block-devices -[USB]:/dock/usb-devices-in-qubes-R4.0/#handling-other-usb-devices +[block]:/doc/usb-devices-in-qubes-R4.0/ +[USB]:/dock/usb-devices-in-qubes-R4.0/ [PCI]:/doc/pci-devices-in-qubes-R4.0/ [security considerations]: /doc/device-considerations/ diff --git a/common-tasks/pci-devices.md b/common-tasks/pci-devices.md index 4f90d521..f0f5dc91 100644 --- a/common-tasks/pci-devices.md +++ b/common-tasks/pci-devices.md @@ -134,8 +134,8 @@ or [device handling in qubes]: /doc/device-handling/ [security considerations]: /doc/device-considerations/#pci-security -[block]:/dock/usb-devices-in-qubes-R4.0/#drives-and-block-devices -[USB]:/dock/usb-devices-in-qubes-R4.0/#handling-other-usb-devices +[block]:/dock/usb-devices-in-qubes-R4.0/ +[USB]:/dock/usb-devices-in-qubes-R4.0/ [appmenu]: /attachment/wiki/Devices/qubes-appmenu-select.png [domain manager icon]: /attachment/wiki/Devices/qubes-logo-icon.png [qvm-device]: /doc/device-handling-in-qubes-R4.0/#general-qubes-device-widget-behavior-and-handling diff --git a/common-tasks/usb-devices.md b/common-tasks/usb-devices.md index 29e62b07..fdf5fda2 100644 --- a/common-tasks/usb-devices.md +++ b/common-tasks/usb-devices.md @@ -10,12 +10,17 @@ USB and Storage Devices in Qubes R4.0 ===================================== *This page is part of [device handling in qubes]* (In case you were looking for the [R3.2 documentation](/doc/usb/).) +**Important security warning:** Attaching devices comes with many security implications! Please make sure you carefully read and understood the **[security considerations]**! Especially, whenever possible, attach a [block device] before attaching a [USB-device][USB]! -Drives And Block Devices -======================== -This part describes how to handle drives, referred to as "block device". If you don't know what a block device is, just think of it as a fancy way to say "something that stores data". +Examples for valid cases for attaching full USB-devices: -#Using The GUI to Attach a Drive + - [microcontroller programming] + - using [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].) + +##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.) @@ -35,6 +40,20 @@ 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. +##Using The GUI to Attach a USB-Device +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] + +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. + +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`**. +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. + #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: @@ -51,7 +70,7 @@ If several different block-devices are attached to a single VM, the last letter To specify this device node name, you need to use the command line tool and its [`frontend-dev`-option][frontend-dev]. -#Command Line Tool Guide +##Attaching a Drive Using The Command-Line 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. @@ -98,47 +117,43 @@ 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 -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]. +##Attaching a Full USB-Device Using The Command-Line +In dom0, you can use `qvm-usb` from the commandline to attach and detach devices. -To recover from this error state, in dom0 run +Listing available USB devices: - virsh detach-disk targetVM xvdi + [user@dom0 ~]$ qvm-usb + BACKEND:DEVID DESCRIPTION USED BY + 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 -(where `targetVM` is to be replaced with the VM name you attached the device to and `xvdi` is to be replaced with the used [frontend device node][frontend-dev].) +Attaching selected USB device: -However, if the block device originated in dom0, you will have to refer to the [old way][detach dom0 device]. + [user@dom0 ~]$ qvm-usb attach work sys-usb:2-5 + [user@dom0 ~]$ qvm-usb + BACKEND:DEVID DESCRIPTION USED BY + sys-usb:2-4 04ca:300d 04ca_300d + sys-usb:2-5 058f:3822 058f_USB_2.0_Camera work + sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse -#Attaching a File -To attach a file as block device to another qube, first turn it into a loopback device inside the sourceVM. +Now, you can use your USB device (camera in this case) in the `work` qube. +If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section]. - 1. In the linux sourceVM run +When you finish, detach the device. - sudo losetup -f --show /path/to/file - - [This command][losetup] will create the device node `/dev/loop0` or, if that is already in use, increase the trailing integer until that name is still available. Afterwards it prints the device-node-name it found. - - 2. If you want to use the GUI, you're done. 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: - - ~]$ qvm-block - BACKEND:DEVID DESCRIPTION USED BY - sourceVM:loop0 /path/to/file - - 3. Attach the `loop0`-device using qvm-block as usual: - - qvm-block a targetVM sourceVM:loop0 - - 4. After detaching, destroy the loop-device inside the sourceVM as follows: - - sudo losetup -d /dev/loop0 + [user@dom0 ~]$ qvm-usb detach work sys-usb:2-5 + [user@dom0 ~]$ qvm-usb + BACKEND:DEVID DESCRIPTION USED BY + 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_Optical_Mouse #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).) +Note: `qvm-usb` does currently *not* support any additional options. + ##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 ...) @@ -172,66 +187,44 @@ usage example: This option accepts `cdrom` and `disk`, default is `disk`. -Handling other USB Devices -========================== -**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! +#Miscellaneous/Customisation +##Recovering From Premature Block-Device Destruction +If the you fail to detach the drive before it's destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), [there will be problems][premature removal]. -Examples for valid cases for USB-passthrough: +To recover from this error state, in dom0 run - - [microcontroller programming] - - using [external audio devices] - - [optical drives] for recording + virsh detach-disk targetVM xvdi -(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].) +(where `targetVM` is to be replaced with the VM name you attached the device to and `xvdi` is to be replaced with the used [frontend device node][frontend-dev].) -#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] +However, if the block device originated in dom0, you will have to refer to the [old way][detach dom0 device]. -Hover on one device to display a list of VMs you may attach it to. +##Attaching a File +To attach a file as block device to another qube, first turn it into a loopback device inside the sourceVM. -Click one of those. The USB device will be attached to it. You're done. + 1. In the linux sourceVM run -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`**. -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. + sudo losetup -f --show /path/to/file -##With The Command Line Tool -In dom0, you can use `qvm-usb` from the commandline to attach and detach devices. + [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. -Listing available USB devices: + 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. - [user@dom0 ~]$ qvm-usb - BACKEND:DEVID DESCRIPTION USED BY - 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 + If you rather use the command line, continue: -Attaching selected USB device: + In dom0, run `qvm-block` to display known block devices. The newly created loop device should show up: - [user@dom0 ~]$ qvm-usb attach work sys-usb:2-5 - [user@dom0 ~]$ qvm-usb - BACKEND:DEVID DESCRIPTION USED BY - sys-usb:2-4 04ca:300d 04ca_300d - sys-usb:2-5 058f:3822 058f_USB_2.0_Camera work - sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse + ~]$ qvm-block + BACKEND:DEVID DESCRIPTION USED BY + sourceVM:loop0 /path/to/file -Now, you can use your USB device (camera in this case) in the `work` qube. -If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section]. + 3. Attach the `loop0`-device using qvm-block as usual: -When you finish, detach the device. + qvm-block a targetVM sourceVM:loop0 - [user@dom0 ~]$ qvm-usb detach work sys-usb:2-5 - [user@dom0 ~]$ qvm-usb - BACKEND:DEVID DESCRIPTION USED BY - 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_Optical_Mouse + 4. After detaching, destroy the loop-device inside the sourceVM as follows: -#Maintenance And Customisation + sudo losetup -d /dev/loop0 ##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]. @@ -289,10 +282,9 @@ This should output something like: Now you see the BDF address in the path (right before final `usb3`). Strip the leading `0000:` and pass the rest to the [`qvm-pci` tool][qvm-pci] to attach the controller to the targetVM. - - +[USB]: #using-the-gui-to-attach-a-drive +[block device]: #using-the-gui-to-attach-a-usb-device [device handling in qubes]: /doc/device-handling/ -[block device]: #drives-and-block-devices [security considerations]: /doc/device-considerations/#usb-security [usb-challenges]: https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html [usb icon]: /attachment/wiki/Devices/generic-usb.png @@ -313,5 +305,4 @@ Strip the leading `0000:` and pass the rest to the [`qvm-pci` tool][qvm-pci] to [frontend-dev]: #frontend-dev [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]:/dock/usb-devices-in-qubes-R4.0/ +[losetup]: https://linux.die.net/man/8/losetup \ No newline at end of file From 48fa6ff8bb2c94bba317ca5020aa811cc4036f25 Mon Sep 17 00:00:00 2001 From: GammaSQ Date: Mon, 4 Mar 2019 23:39:37 +0100 Subject: [PATCH 16/25] fixed typos --- common-tasks/device-handling.md | 2 +- common-tasks/pci-devices.md | 4 ++-- common-tasks/usb-devices.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/common-tasks/device-handling.md b/common-tasks/device-handling.md index e711b7d7..abdcfe5c 100644 --- a/common-tasks/device-handling.md +++ b/common-tasks/device-handling.md @@ -110,7 +110,7 @@ If no specific `sourceVM:deviceID` combination is given, *all devices of that DE [block]:/doc/usb-devices-in-qubes-R4.0/ -[USB]:/dock/usb-devices-in-qubes-R4.0/ +[USB]:/doc/usb-devices-in-qubes-R4.0/ [PCI]:/doc/pci-devices-in-qubes-R4.0/ [security considerations]: /doc/device-considerations/ diff --git a/common-tasks/pci-devices.md b/common-tasks/pci-devices.md index f0f5dc91..88886233 100644 --- a/common-tasks/pci-devices.md +++ b/common-tasks/pci-devices.md @@ -134,8 +134,8 @@ or [device handling in qubes]: /doc/device-handling/ [security considerations]: /doc/device-considerations/#pci-security -[block]:/dock/usb-devices-in-qubes-R4.0/ -[USB]:/dock/usb-devices-in-qubes-R4.0/ +[block]:/doc/usb-devices-in-qubes-R4.0/ +[USB]:/doc/usb-devices-in-qubes-R4.0/ [appmenu]: /attachment/wiki/Devices/qubes-appmenu-select.png [domain manager icon]: /attachment/wiki/Devices/qubes-logo-icon.png [qvm-device]: /doc/device-handling-in-qubes-R4.0/#general-qubes-device-widget-behavior-and-handling diff --git a/common-tasks/usb-devices.md b/common-tasks/usb-devices.md index fdf5fda2..2d4cc11e 100644 --- a/common-tasks/usb-devices.md +++ b/common-tasks/usb-devices.md @@ -64,7 +64,7 @@ If not specified otherwise, block devices will show up as `/dev/xvdi*` in a linu where `xvdi2` needs to be replaced with the partition you want to mount. This will make your drive content accessible under `~/mnt`. -Beware that when you attach a whole block device, partitions can be identified by their trailing integer (i.e. `/dev/xvdi2` for the second partition, `/dev/xvdi` for the whole device), whereas if you attach a single parition, the partition has *no trailing integer*. +Beware that when you attach a whole block device, partitions can be identified by their trailing integer (i.e. `/dev/xvdi2` for the second partition, `/dev/xvdi` for the whole device), whereas if you attach a single partition, the partition has *no trailing integer*. If several different block-devices are attached to a single VM, the last letter of the device node name is advanced through the alphabet, so after `xvdi` the next device will be named `xvdj`, the next `xvdk`, and so on. From bbd702e69aae9258cf2e9343254f93d964432c34 Mon Sep 17 00:00:00 2001 From: GammaSQ Date: Tue, 5 Mar 2019 17:47:23 +0100 Subject: [PATCH 17/25] fixing links with known fix --- common-tasks/usb.md | 4 ++-- configuration/usb-qube-howto.md | 6 +++--- customization/disposablevm-customization.md | 10 +++++----- doc.md | 3 +-- installing/install-security.md | 2 +- security/yubi-key.md | 2 +- 6 files changed, 13 insertions(+), 14 deletions(-) diff --git a/common-tasks/usb.md b/common-tasks/usb.md index e0141521..02eba04a 100644 --- a/common-tasks/usb.md +++ b/common-tasks/usb.md @@ -198,6 +198,6 @@ Additional Reading: [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-how-to/ -[Using a USB keyboard]: /doc/usb-qube-how-to/#enable-a-usb-keyboard-for-login +[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 diff --git a/configuration/usb-qube-howto.md b/configuration/usb-qube-howto.md index 6d3815cd..c48eb822 100644 --- a/configuration/usb-qube-howto.md +++ b/configuration/usb-qube-howto.md @@ -1,7 +1,7 @@ --- layout: doc title: USB Qube HowTo -permalink: /doc/usb-qube-how-to/ +permalink: /doc/usb-qube-howto/ --- USB Qube HowTo @@ -198,9 +198,9 @@ Removing a USB qube [PCI Devices]: /doc/pci-devices-in-qubes-R4.0/ [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-device +[Security Warning about USB Input Devices]: /doc/device-considerations/#security-warning-on-usb-input-devices [manual setup]: #manual-setup -[install dom0 updates]: /doc/software-update-dom0/#how-to-update-software-in-dom0 +[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 \ No newline at end of file diff --git a/customization/disposablevm-customization.md b/customization/disposablevm-customization.md index e57456a4..21cfcb62 100644 --- a/customization/disposablevm-customization.md +++ b/customization/disposablevm-customization.md @@ -91,8 +91,8 @@ For example, with `qvm-prefs work netvm sys-firewall2`. To create one with a PCI device attached such as for `sys-net` or `sys-usb`, use the additional commands as follows. -**Note** You can use `qvm-pci` to [determine](/doc/assigning-devices/#r40) the ``. -Also, you will often need to include the `-o no-strict-reset=True` [option](/doc/assigning-devices/#r40-1) with USB controllers. +**Note** You can use `qvm-pci` to [determine](/doc/pci-devices/#qvm-pci-usage) the ``. +Also, you will often need to include the `-o no-strict-reset=True` [option](/doc/pci-devices/#no-strict-reset) with USB controllers. ~~~ qvm-create -C DispVM -l red @@ -240,7 +240,7 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe 5. Attach the USB controller to the `disp-sys-usb` - >_**Note:**_ Most of the commonly used USB controllers (all Intel integrated controllers) require the `-o no-strict-reset=True` option to be set. Instructions detailing how this option is set can be found [here](/doc/assigning-devices/#r40-1). + >_**Note:**_ Most of the commonly used USB controllers (all Intel integrated controllers) require the `-o no-strict-reset=True` option to be set. Instructions detailing how this option is set can be found [here](/doc/pci-devices/#no-strict-reset). [user@dom0 ~]$ qvm-pci attach --persistent disp-sys-usb : @@ -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/#how-to-hide-all-usb-controllers-from-dom0) +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) 8. At this point, your mouse may not work. Edit the `qubes.InputMouse` policy file in dom0, which is located here: @@ -273,7 +273,7 @@ Prior to starting the new VMs, users should ensure that no other VMs such as the The `disp-sys-usb` VM does not start -If the `disp-sys-usb` does not start, it could be due to a PCI passthrough problem. For more details on this issue along with possible solutions, users can look [here](/doc/assigning-devices/#pci-passthrough-issues) +If the `disp-sys-usb` does not start, it could be due to a PCI passthrough problem. For more details on this issue along with possible solutions, users can look [here](/doc/pci-devices/#pci-passthrough-issues) ### Deleting DisposableVM ### diff --git a/doc.md b/doc.md index fd7078ab..440a4dcd 100644 --- a/doc.md +++ b/doc.md @@ -67,8 +67,7 @@ redirect_from: * [Backup, Restoration, and Migration](/doc/backup-restore/) * [Using DisposableVMs](/doc/disposablevm/) * [Using and Managing USB Devices in R3.2](/doc/usb/) - * [Using Block or Storage Devices in Qubes R4.0](/doc/block-devices/) - * [Using USB Devices in Qubes R4.0](/doc/usb-devices) + * [Using USB and Storage Devices in Qubes R4.0](/doc/usb-devices) * [Optical Discs](/doc/optical-discs/) * [Managing Application Shortcuts](/doc/managing-appvm-shortcuts/) * [Enabling Fullscreen Mode](/doc/full-screen-mode/) diff --git a/installing/install-security.md b/installing/install-security.md index 1eba07e3..2620efe9 100644 --- a/installing/install-security.md +++ b/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/#creating-and-using-a-usb-qube +[USB qube]: /doc/usb-qubes-howto/#creating-and-using-a-usb-qube [BadUSB]: https://srlabs.de/badusb/ diff --git a/security/yubi-key.md b/security/yubi-key.md index 0d12ddd3..f49ae067 100644 --- a/security/yubi-key.md +++ b/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/usb/#security-warning-about-usb-input-devices). +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). There (at least) two possible configurations: using OTP mode and using challenge-response mode. From a6febd683fc8a968ad33af42b235bae7b1c7e2c6 Mon Sep 17 00:00:00 2001 From: GammaSQ Date: Tue, 5 Mar 2019 18:09:21 +0100 Subject: [PATCH 18/25] fixed typos --- installing/install-security.md | 2 +- security/device-considerations.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/installing/install-security.md b/installing/install-security.md index 2620efe9..bb7ba215 100644 --- a/installing/install-security.md +++ b/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-qubes-howto/#creating-and-using-a-usb-qube +[USB qube]: /doc/usb-qube-howto/#creating-and-using-a-usb-qube [BadUSB]: https://srlabs.de/badusb/ diff --git a/security/device-considerations.md b/security/device-considerations.md index c70647a6..69b3547a 100644 --- a/security/device-considerations.md +++ b/security/device-considerations.md @@ -61,7 +61,7 @@ Support for [two factor authentication][qubes u2f proxy] was recently added, tho [USB security]:https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html "invisiblethings blog on USB security" [rubber duck]: https://shop.hak5.org/products/usb-rubber-ducky-deluxe -[USB qube]: /doc/usb-qube-how-to/ +[USB qube]: /doc/usb-qube-howto/ [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 From c70b35999a901f428258c8932237cc28c97511da Mon Sep 17 00:00:00 2001 From: GammaSQ Date: Tue, 12 Mar 2019 22:03:55 +0100 Subject: [PATCH 19/25] fixed headlines --- common-tasks/device-handling.md | 24 ++++++++++++------------ common-tasks/pci-devices.md | 18 +++++++++--------- common-tasks/usb-devices.md | 32 ++++++++++++++++---------------- 3 files changed, 37 insertions(+), 37 deletions(-) diff --git a/common-tasks/device-handling.md b/common-tasks/device-handling.md index abdcfe5c..9036d365 100644 --- a/common-tasks/device-handling.md +++ b/common-tasks/device-handling.md @@ -25,26 +25,26 @@ 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 +# 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. 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 +52,7 @@ 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,7 +60,7 @@ 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 @@ -73,10 +73,10 @@ A full command consists of one DEVICE_CLASS and one action. If no action is give **SYNOPSIS**: `qvm-device DEVICE_CLASS {action} [action-specific arguments] [options]` -##Actions +## Actions Actions are applicable to every DEVICE_CLASS and expose some additional options. -###Listing Devices +### Listing Devices The `list` action lists known devices in the system. `list` accepts VM-names to narrow down listed devices. Devices available in, as well as attached to the named VMs will be listed. `list` accepts two options: @@ -87,7 +87,7 @@ 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 +### 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 +98,7 @@ 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 +### 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.* diff --git a/common-tasks/pci-devices.md b/common-tasks/pci-devices.md index 88886233..547c23ee 100644 --- a/common-tasks/pci-devices.md +++ b/common-tasks/pci-devices.md @@ -28,7 +28,7 @@ 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 +42,7 @@ 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 +62,9 @@ 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 +77,7 @@ 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 +87,19 @@ 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: @@ -108,7 +108,7 @@ usage example: -#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. diff --git a/common-tasks/usb-devices.md b/common-tasks/usb-devices.md index 2d4cc11e..9e529c42 100644 --- a/common-tasks/usb-devices.md +++ b/common-tasks/usb-devices.md @@ -20,7 +20,7 @@ Examples for valid cases for attaching full USB-devices: (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].) -##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.) @@ -40,7 +40,7 @@ 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. -##Using The GUI to Attach a USB-Device +## Using The GUI to Attach a USB-Device 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] @@ -54,7 +54,7 @@ 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. -#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 ~ @@ -70,7 +70,7 @@ If several different block-devices are attached to a single VM, the last letter To specify this device node name, you need to use the command line tool and its [`frontend-dev`-option][frontend-dev]. -##Attaching a Drive Using The Command-Line +## Attaching a Drive Using The Command-Line 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. @@ -117,7 +117,7 @@ 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. -##Attaching a Full USB-Device Using The Command-Line +## Attaching a Full USB-Device Using The Command-Line In dom0, you can use `qvm-usb` from the commandline to attach and detach devices. Listing available USB devices: @@ -149,12 +149,12 @@ 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 -#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).) Note: `qvm-usb` does currently *not* support any additional options. -##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: @@ -163,7 +163,7 @@ 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. @@ -178,7 +178,7 @@ 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: @@ -187,8 +187,8 @@ usage example: This option accepts `cdrom` and `disk`, default is `disk`. -#Miscellaneous/Customisation -##Recovering From Premature Block-Device Destruction +# Miscellaneous/Customisation +## Recovering From Premature Block-Device Destruction If the you fail to detach the drive 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 @@ -199,7 +199,7 @@ 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 @@ -226,10 +226,10 @@ To attach a file as block device to another qube, first turn it into a loopback sudo losetup -d /dev/loop0 -##Creating And Using a USB qube +## Creating And Using a USB qube If you've selected to install a usb-qube during system installation, everything is already set up for you in `sys-usb`. If you've later decided to create a usb-qube, please follow [this guide][USB-qube howto]. -##Installation Of `qubes-usb-proxy` +## Installation Of `qubes-usb-proxy` To use this feature, the[`qubes-usb-proxy`][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. @@ -241,13 +241,13 @@ 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. From 6fd0a665a982905b9d1b8b65e7a03d0883758e0e Mon Sep 17 00:00:00 2001 From: GammaSQ Date: Wed, 13 Mar 2019 16:52:42 +0100 Subject: [PATCH 20/25] fixing redirected link to actual path --- common-tasks/pci-devices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/common-tasks/pci-devices.md b/common-tasks/pci-devices.md index 547c23ee..029eb3a0 100644 --- a/common-tasks/pci-devices.md +++ b/common-tasks/pci-devices.md @@ -138,7 +138,7 @@ or [USB]:/doc/usb-devices-in-qubes-R4.0/ [appmenu]: /attachment/wiki/Devices/qubes-appmenu-select.png [domain manager icon]: /attachment/wiki/Devices/qubes-logo-icon.png -[qvm-device]: /doc/device-handling-in-qubes-R4.0/#general-qubes-device-widget-behavior-and-handling +[qvm-device]: /doc/device-handling/#general-qubes-device-widget-behavior-and-handling [side channel attacks]: https://en.wikipedia.org/wiki/Side-channel_attack [ml1]: https://groups.google.com/group/qubes-devel/browse_thread/thread/631c4a3a9d1186e3 [ml2]: https://groups.google.com/forum/#!topic/qubes-users/Fs94QAc3vQI From 6d6f32f7889a032f4b0e0c0b29ae8d69ce00bb52 Mon Sep 17 00:00:00 2001 From: GammaSQ Date: Thu, 14 Mar 2019 23:39:20 +0100 Subject: [PATCH 21/25] reworking for split block and usb pages --- common-tasks/block-devices.md | 182 ++++++++++++++++++ common-tasks/device-handling.md | 26 +-- common-tasks/pci-devices.md | 20 +- common-tasks/usb-devices.md | 196 ++------------------ customization/disposablevm-customization.md | 2 +- doc.md | 3 +- 6 files changed, 226 insertions(+), 203 deletions(-) create mode 100644 common-tasks/block-devices.md diff --git a/common-tasks/block-devices.md b/common-tasks/block-devices.md new file mode 100644 index 00000000..9ce12f6f --- /dev/null +++ b/common-tasks/block-devices.md @@ -0,0 +1,182 @@ +--- +layout: doc +title: Block or Storage Devices in Qubes R4.0 +permalink: /doc/block-devices/ +redirect_from: +- /doc/block-devices-in-qubes-R4.0/ +--- + +Block or Storage Devices in Qubes R4.0 +====================================== +*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 +(**Note:** In the present context, the term "USB drive" denotes any [USB mass storage device][mass-storage]. +In addition to smaller flash memory sticks, this includes things like USB external hard drives.) + +Qubes OS supports the ability to attach a USB drive (or just its partitions) to any qube easily, no matter which qube handles the USB controller. + +Attaching USB drives is integrated into the Devices Widget: ![device manager icon] +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`). + +The simplest option is to attach the entire block drive. +In our example, this is `sys-usb:sda`, so hover over it. +This will pop up a submenu showing running VMs to which the USB drive can be connected. +Click on one and your USB drive will be attached! + +**Note:** attaching individual partitions (e.g. `sys-usb:sda1`) 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. + +#Block Devices in VMs +If not specified otherwise, block devices will show up as `/dev/xvdi*` in a linux VM, where `*` may be the partition-number. If a block device isn't automatically mounted after attaching, open a terminal in the VM and execute: + + cd ~ + mkdir mnt + sudo mount /dev/xvdi2 mnt + +where `xvdi2` needs to be replaced with the partition you want to mount. +This will make your drive content accessible under `~/mnt`. + +Beware that when you attach a whole block device, partitions can be identified by their trailing integer (i.e. `/dev/xvdi2` for the second partition, `/dev/xvdi` for the whole device), whereas if you attach a single partition, the partition has *no trailing integer*. + +If several different block-devices are attached to a single VM, the last letter of the device node name is advanced through the alphabet, so after `xvdi` the next device will be named `xvdj`, the next `xvdk`, and so on. + +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 +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. + +In case of a USB-drive, make sure it's attached to your computer. If you don't see anything that looks like your drive, run `sudo udevadm trigger --action=change` in your USB-qube (typically `sys-usb`) + + 1. In a dom0 console (running as a normal user), list all available block devices: + + qvm-block + + This will list all available block devices in your system across all VMs. + The name of the qube hosting the block device is displayed before the colon in the device ID. + The string after the colon is the ID of the device used within the qube, like so: + + sourceVM:sdb Cruzer () 4GiB + sourceVM:sdb1 Disk () 2GiB + + 2. Assuming your block device is attached to `sys-usb` and its device node is `sdb`, we attach the device to a qube with the name `work` like so: + + qvm-block attach work sys-usb:sdb + + This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc. + + You may also mount one partition at a time by using the same command with the partition number, e.g. `sdb1`. + + 3. The block device is now attached to the qube. + If using a default qube, you may open the Nautilus file manager in the qube, and your drive should be visible in the **Devices** panel on the left. + If you've attached a single partition (e.g. `sdb2` instead of `sdb` in our example), you may need to manually mount before it becomes visible: + + cd ~ + mkdir mnt + sudo mount /dev/xvdi mnt + + + 4. When you finish using the block device, click the eject button or right-click and select **Unmount**. + + If you've manually mounted a single partition in the above step, use: + + sudo umount mnt + + 5. In a dom0 console, detach the device + + qvm-block detach work sys-usb:sdb + + 6. You may now remove the device or attach it to another qube. + +#Recovering From Premature Device Destruction +If the you fail to detach the device before it's destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), [there will be problems][premature removal]. + +To recover from this error state, in dom0 run + + virsh detach-disk targetVM xvdi + +(where `targetVM` is to be replaced with the VM name you attached the device to and `xvdi` is to be replaced with the used [frontend device node][frontend-dev].) + +However, if the block device originated in dom0, you will have to refer to the [old way][detach dom0 device]. + +#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 + + sudo losetup -f --show /path/to/file + + [This command][losetup] will create the device node `/dev/loop0` or, if that is already in use, increase the trailing integer until that name is still available. Afterwards it prints the device-node-name it found. + + 2. If you want to use the GUI, you're done. 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: + + ~]$ qvm-block + BACKEND:DEVID DESCRIPTION USED BY + sourceVM:loop0 /path/to/file + + 3. Attach the `loop0`-device using qvm-block as usual: + + qvm-block a targetVM sourceVM:loop0 + + 4. After detaching, destroy the loop-device inside the sourceVM as follows: + + sudo losetup -d /dev/loop0 + +#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 +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: + + qvm-block a work sys-usb:sda1 -o frontend-dev=xvdz + +This command will attach the partition `sda1` to `work` as `/dev/xvdz`. + +##read-only +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. + +usage example: + + qvm-block a work sys-usb:sda1 -o read-only=true + +There exists a shortcut to set read-only `true`, `--ro`: + + qvm-block a work sys-usb:sda1 --ro + +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. + +usage example: + + qvm-block a work sys-usb:sda1 -o devtype=cdrom + +This option accepts `cdrom` and `disk`, default is `disk`. + + + +[device handling in qubes]: /doc/device-handling/ +[mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class +[device manager icon]:https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/devices/media-removable.png +[frontend-dev]: #frontend-dev +[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/ diff --git a/common-tasks/device-handling.md b/common-tasks/device-handling.md index 9036d365..366e3a4a 100644 --- a/common-tasks/device-handling.md +++ b/common-tasks/device-handling.md @@ -25,26 +25,26 @@ 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 +# 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. 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 +52,7 @@ 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,7 +60,7 @@ 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 @@ -73,10 +73,10 @@ A full command consists of one DEVICE_CLASS and one action. If no action is give **SYNOPSIS**: `qvm-device DEVICE_CLASS {action} [action-specific arguments] [options]` -## Actions +## Actions ## Actions are applicable to every DEVICE_CLASS and expose some additional options. -### Listing Devices +### Listing Devices ### The `list` action lists known devices in the system. `list` accepts VM-names to narrow down listed devices. Devices available in, as well as attached to the named VMs will be listed. `list` accepts two options: @@ -87,7 +87,7 @@ 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 +### 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 +98,7 @@ 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 +### 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,7 +109,7 @@ 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/usb-devices-in-qubes-R4.0/ +[block]:/doc/block-devices-in-qubes-R4.0/ [USB]:/doc/usb-devices-in-qubes-R4.0/ [PCI]:/doc/pci-devices-in-qubes-R4.0/ diff --git a/common-tasks/pci-devices.md b/common-tasks/pci-devices.md index 029eb3a0..f1491e81 100644 --- a/common-tasks/pci-devices.md +++ b/common-tasks/pci-devices.md @@ -28,7 +28,7 @@ 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 +42,7 @@ 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 +62,9 @@ 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 +77,7 @@ 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 +87,19 @@ 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: @@ -108,7 +108,7 @@ usage example: -# 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. @@ -134,7 +134,7 @@ or [device handling in qubes]: /doc/device-handling/ [security considerations]: /doc/device-considerations/#pci-security -[block]:/doc/usb-devices-in-qubes-R4.0/ +[block]:/doc/block-devices-in-qubes-R4.0/ [USB]:/doc/usb-devices-in-qubes-R4.0/ [appmenu]: /attachment/wiki/Devices/qubes-appmenu-select.png [domain manager icon]: /attachment/wiki/Devices/qubes-logo-icon.png diff --git a/common-tasks/usb-devices.md b/common-tasks/usb-devices.md index 9e529c42..59fdf5bd 100644 --- a/common-tasks/usb-devices.md +++ b/common-tasks/usb-devices.md @@ -6,13 +6,16 @@ redirect_from: - /doc/usb-devices-in-qubes-R4.0/ --- -USB and Storage Devices in Qubes R4.0 -===================================== +USB Devices in Qubes R4.0 +========================== *This page is part of [device handling in qubes]* (In case you were looking for the [R3.2 documentation](/doc/usb/).) -**Important security warning:** Attaching devices comes with many security implications! Please make sure you carefully read and understood the **[security considerations]**! Especially, whenever possible, attach a [block device] before attaching a [USB-device][USB]! -Examples for valid cases for attaching full USB-devices: +If you are looking to handle USB-*storage*-devices (thumbdrives or USB-drives), please have a look at [storage device handling][block-device]. + +**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! + +Examples for valid cases for USB-passthrough: - [microcontroller programming] - using [external audio devices] @@ -20,27 +23,8 @@ Examples for valid cases for attaching full USB-devices: (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].) -## Using The GUI to Attach a Drive -(**Note:** In the present context, the term "USB drive" denotes any [USB mass storage device][mass-storage]. -In addition to smaller flash memory sticks, this includes things like USB external hard drives.) - -Qubes OS supports the ability to attach a USB drive (or just its partitions) to any qube easily, no matter which qube handles the USB controller. - -Attaching USB drives is integrated into the Devices Widget: ![device manager icon] -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`). - -The simplest option is to attach the entire block drive. -In our example, this is `sys-usb:sda`, so hover over it. -This will pop up a submenu showing running VMs to which the USB drive can be connected. -Click on one and your USB drive will be attached! - -**Note:** attaching individual partitions (e.g. `sys-usb:sda1`) 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. - -## Using The GUI to Attach a USB-Device +# 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] @@ -54,70 +38,7 @@ 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. -# Block Devices in VMs -If not specified otherwise, block devices will show up as `/dev/xvdi*` in a linux VM, where `*` may be the partition-number. If a block device isn't automatically mounted after attaching, open a terminal in the VM and execute: - - cd ~ - mkdir mnt - sudo mount /dev/xvdi2 mnt - -where `xvdi2` needs to be replaced with the partition you want to mount. -This will make your drive content accessible under `~/mnt`. - -Beware that when you attach a whole block device, partitions can be identified by their trailing integer (i.e. `/dev/xvdi2` for the second partition, `/dev/xvdi` for the whole device), whereas if you attach a single partition, the partition has *no trailing integer*. - -If several different block-devices are attached to a single VM, the last letter of the device node name is advanced through the alphabet, so after `xvdi` the next device will be named `xvdj`, the next `xvdk`, and so on. - -To specify this device node name, you need to use the command line tool and its [`frontend-dev`-option][frontend-dev]. - -## Attaching a Drive Using The Command-Line -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. - -In case of a USB-drive, make sure it's attached to your computer. If you don't see anything that looks like your drive, run `sudo udevadm trigger --action=change` in your USB-qube (typically `sys-usb`) - - 1. In a dom0 console (running as a normal user), list all available block devices: - - qvm-block - - This will list all available block devices in your system across all VMs. - The name of the qube hosting the block device is displayed before the colon in the device ID. - The string after the colon is the ID of the device used within the qube, like so: - - sourceVM:sdb Cruzer () 4GiB - sourceVM:sdb1 Disk () 2GiB - - 2. Assuming your block device is attached to `sys-usb` and its device node is `sdb`, we attach the device to a qube with the name `work` like so: - - qvm-block attach work sys-usb:sdb - - This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc. - - You may also mount one partition at a time by using the same command with the partition number, e.g. `sdb1`. - - 3. The block device is now attached to the qube. - If using a default qube, you may open the Nautilus file manager in the qube, and your drive should be visible in the **Devices** panel on the left. - If you've attached a single partition (e.g. `sdb2` instead of `sdb` in our example), you may need to manually mount before it becomes visible: - - cd ~ - mkdir mnt - sudo mount /dev/xvdi mnt - - - 4. When you finish using the block device, click the eject button or right-click and select **Unmount**. - - If you've manually mounted a single partition in the above step, use: - - sudo umount mnt - - 5. In a dom0 console, detach the device - - qvm-block detach work sys-usb:sdb - - 6. You may now remove the device or attach it to another qube. - -## Attaching a Full USB-Device Using The Command-Line +## With The Command Line Tool ## In dom0, you can use `qvm-usb` from the commandline to attach and detach devices. Listing available USB devices: @@ -149,87 +70,12 @@ 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 -# 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).) +# Maintenance And Customisation # -Note: `qvm-usb` does currently *not* support any additional options. - -## 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: - - qvm-block a work sys-usb:sda1 -o frontend-dev=xvdz - -This command will attach the partition `sda1` to `work` as `/dev/xvdz`. - -## read-only -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. - -usage example: - - qvm-block a work sys-usb:sda1 -o read-only=true - -There exists a shortcut to set read-only `true`, `--ro`: - - qvm-block a work sys-usb:sda1 --ro - -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. - -usage example: - - qvm-block a work sys-usb:sda1 -o devtype=cdrom - -This option accepts `cdrom` and `disk`, default is `disk`. - -# Miscellaneous/Customisation -## Recovering From Premature Block-Device Destruction -If the you fail to detach the drive before it's destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), [there will be problems][premature removal]. - -To recover from this error state, in dom0 run - - virsh detach-disk targetVM xvdi - -(where `targetVM` is to be replaced with the VM name you attached the device to and `xvdi` is to be replaced with the used [frontend device node][frontend-dev].) - -However, if the block device originated in dom0, you will have to refer to the [old way][detach dom0 device]. - -## 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 - - sudo losetup -f --show /path/to/file - - [This command][losetup] will create the device node `/dev/loop0` or, if that is already in use, increase the trailing integer until that name is still available. Afterwards it prints the device-node-name it found. - - 2. If you want to use the GUI, you're done. 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: - - ~]$ qvm-block - BACKEND:DEVID DESCRIPTION USED BY - sourceVM:loop0 /path/to/file - - 3. Attach the `loop0`-device using qvm-block as usual: - - qvm-block a targetVM sourceVM:loop0 - - 4. After detaching, destroy the loop-device inside the sourceVM as follows: - - sudo losetup -d /dev/loop0 - -## Creating And Using a USB qube +## Creating And Using a USB qube ## If you've selected to install a usb-qube during system installation, everything is already set up for you in `sys-usb`. If you've later decided to create a usb-qube, please follow [this guide][USB-qube howto]. -## Installation Of `qubes-usb-proxy` +## Installation Of `qubes-usb-proxy` ## To use this feature, the[`qubes-usb-proxy`][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. @@ -241,13 +87,13 @@ 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. @@ -282,9 +128,10 @@ This should output something like: Now you see the BDF address in the path (right before final `usb3`). Strip the leading `0000:` and pass the rest to the [`qvm-pci` tool][qvm-pci] to attach the controller to the targetVM. -[USB]: #using-the-gui-to-attach-a-drive -[block device]: #using-the-gui-to-attach-a-usb-device + + [device handling in qubes]: /doc/device-handling/ +[block device]: /doc/block-devices-in-qubes-R4.0/ [security considerations]: /doc/device-considerations/#usb-security [usb-challenges]: https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html [usb icon]: /attachment/wiki/Devices/generic-usb.png @@ -299,10 +146,3 @@ Strip the leading `0000:` and pass the rest to the [`qvm-pci` tool][qvm-pci] to [USB-qube howto]: /doc/usb-qube-howto/ [keyboard setup]: /doc/usb-qube-howto/#enable-a-usb-keyboard-for-login [qvm-pci]: /doc/pci-devices-in-qubes-R4.0/ - -[device handling in qubes]: /doc/device-handling/ -[mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class -[frontend-dev]: #frontend-dev -[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 \ No newline at end of file diff --git a/customization/disposablevm-customization.md b/customization/disposablevm-customization.md index 21cfcb62..9c2ba81b 100644 --- a/customization/disposablevm-customization.md +++ b/customization/disposablevm-customization.md @@ -182,7 +182,7 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe [user@dom0 ~]$ qvm-pci -6. Attach the network PCI device(s) to `disp-sys-net`: Finding and assigning PCI devices can be found [here](/doc/assigning-devices/) +6. Attach the network PCI device(s) to `disp-sys-net`: Finding and assigning PCI devices can be found [here](/doc/pci-devices/) [user@dom0 ~]$ qvm-pci attach --persistent disp-sys-net : diff --git a/doc.md b/doc.md index 440a4dcd..fd7078ab 100644 --- a/doc.md +++ b/doc.md @@ -67,7 +67,8 @@ redirect_from: * [Backup, Restoration, and Migration](/doc/backup-restore/) * [Using DisposableVMs](/doc/disposablevm/) * [Using and Managing USB Devices in R3.2](/doc/usb/) - * [Using USB and Storage Devices in Qubes R4.0](/doc/usb-devices) + * [Using Block or Storage Devices in Qubes R4.0](/doc/block-devices/) + * [Using USB Devices in Qubes R4.0](/doc/usb-devices) * [Optical Discs](/doc/optical-discs/) * [Managing Application Shortcuts](/doc/managing-appvm-shortcuts/) * [Enabling Fullscreen Mode](/doc/full-screen-mode/) From 440b319fb0df0d05426df8242fa038152f46dd98 Mon Sep 17 00:00:00 2001 From: GammaSQ Date: Thu, 14 Mar 2019 23:57:26 +0100 Subject: [PATCH 22/25] typos, fixes in block-devices.md --- common-tasks/block-devices.md | 20 ++++++++++---------- common-tasks/pci-devices.md | 2 +- security/device-considerations.md | 2 +- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/common-tasks/block-devices.md b/common-tasks/block-devices.md index 9ce12f6f..836e54f5 100644 --- a/common-tasks/block-devices.md +++ b/common-tasks/block-devices.md @@ -13,7 +13,7 @@ Block or Storage Devices in Qubes R4.0 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 +33,7 @@ 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 +49,7 @@ If several different block-devices are attached to a single VM, the last letter To specify this device node name, you need to use the command line tool and its [`frontend-dev`-option][frontend-dev]. -#Command Line Tool Guide +# Command Line Tool Guide # The command-line tool you may use to mount whole USB drives or their partitions is `qvm-block`, a shortcut for `qvm-device block`. `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 +96,7 @@ 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 +107,7 @@ 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 +134,10 @@ 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 +146,7 @@ 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 +161,7 @@ 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: @@ -174,7 +174,7 @@ This option accepts `cdrom` and `disk`, default is `disk`. [device handling in qubes]: /doc/device-handling/ [mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class -[device manager icon]:https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/devices/media-removable.png +[device manager icon]:/attachment/wiki/Devices/media-removable.png [frontend-dev]: #frontend-dev [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 diff --git a/common-tasks/pci-devices.md b/common-tasks/pci-devices.md index f1491e81..ca4b3dfa 100644 --- a/common-tasks/pci-devices.md +++ b/common-tasks/pci-devices.md @@ -21,7 +21,7 @@ Unlike other devices ([USB], [block], mic), PCI devices need to be attached on V 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 aformentioned [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. diff --git a/security/device-considerations.md b/security/device-considerations.md index 69b3547a..4e116f3b 100644 --- a/security/device-considerations.md +++ b/security/device-considerations.md @@ -18,7 +18,7 @@ Attaching a full block device (e.g. `sda`) again offers more attack surface than 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 controll 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.) +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.) By default, Qubes requires any PCI device to be resettable from the outside (i.e. via the hypervisor), which completely reinitialises the device. This ensures that any device that was attached to a compromised VM, even if that VM was able to use bugs in the PCI device to inject malicious code, can be trusted again. (Or at least as trusted as it was when Qubes booted.) From 328ce89659f41a377abb293ec968f6e9059e4001 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Fri, 29 Mar 2019 19:12:44 -0500 Subject: [PATCH 23/25] 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 | 53 +++-- common-tasks/device-handling.md | 71 ++++-- common-tasks/pci-devices.md | 56 +++-- common-tasks/usb-devices.md | 57 +++-- common-tasks/usb.md | 203 ------------------ configuration/assigning-devices.md | 112 ---------- .../{usb-qube-howto.md => usb-qubes.md} | 44 ++-- customization/disposablevm-customization.md | 2 +- doc.md | 13 +- installing/install-security.md | 2 +- ...rations.md => device-handling-security.md} | 38 ++-- security/yubi-key.md | 2 +- 12 files changed, 208 insertions(+), 445 deletions(-) delete mode 100644 common-tasks/usb.md delete mode 100644 configuration/assigning-devices.md rename configuration/{usb-qube-howto.md => usb-qubes.md} (93%) rename security/{device-considerations.md => device-handling-security.md} (89%) diff --git a/common-tasks/block-devices.md b/common-tasks/block-devices.md index 836e54f5..daf85c36 100644 --- a/common-tasks/block-devices.md +++ b/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 -====================================== -*This page is part of [device handling in qubes]* -(In case you were looking for the [R3.2 documentation](/doc/usb/).) +# Block (Storage) Devices # + +*This page is part of [device handling in qubes].* If you don't know what a "block device" is, just think of it as a fancy way to say "something that stores data". -# Using The GUI to Attach a Drive # + +## Using The GUI to Attach a Drive ## + (**Note:** In the present context, the term "USB drive" denotes any [USB mass storage device][mass-storage]. In addition to smaller flash memory sticks, this includes things like USB external hard drives.) @@ -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/ + diff --git a/common-tasks/device-handling.md b/common-tasks/device-handling.md index 366e3a4a..a85922cf 100644 --- a/common-tasks/device-handling.md +++ b/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/ -[USB]:/doc/usb-devices-in-qubes-R4.0/ -[PCI]:/doc/pci-devices-in-qubes-R4.0/ - -[security considerations]: /doc/device-considerations/ +[block]:/doc/block-devices/ +[USB]:/doc/usb-devices/ +[PCI]:/doc/pci-devices/ +[security considerations]: /doc/device-handling-security/ [device manager icon]: /attachment/wiki/Devices/media-removable.png [eject icon]: /attachment/wiki/Devices/media-eject.png [i4692]: https://github.com/QubesOS/qubes-issues/issues/4692 + diff --git a/common-tasks/pci-devices.md b/common-tasks/pci-devices.md index ca4b3dfa..db1332cb 100644 --- a/common-tasks/pci-devices.md +++ b/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 -========================= -*This page is part of [device handling in qubes]* -(In case you were looking for the [R3.2 documentation](/doc/assigning-devices/).) +# PCI 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 -[block]:/doc/block-devices-in-qubes-R4.0/ -[USB]:/doc/usb-devices-in-qubes-R4.0/ +[security considerations]: /doc/device-handling-security/#pci-security +[block]:/doc/block-devices/ +[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 + diff --git a/common-tasks/usb-devices.md b/common-tasks/usb-devices.md index 59fdf5bd..60ca90d8 100644 --- a/common-tasks/usb-devices.md +++ b/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 -========================== -*This page is part of [device handling in qubes]* -(In case you were looking for the [R3.2 documentation](/doc/usb/).) +# USB Devices # -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/ -[security considerations]: /doc/device-considerations/#usb-security +[block device]: /doc/block-devices/ +[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/ -[keyboard setup]: /doc/usb-qube-howto/#enable-a-usb-keyboard-for-login -[qvm-pci]: /doc/pci-devices-in-qubes-R4.0/ +[USB-qube howto]: /doc/usb-qubes/ +[keyboard setup]: /doc/usb-qubes/#enable-a-usb-keyboard-for-login +[qvm-pci]: /doc/pci-devices/ diff --git a/common-tasks/usb.md b/common-tasks/usb.md deleted file mode 100644 index 02eba04a..00000000 --- a/common-tasks/usb.md +++ /dev/null @@ -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 - - or - - qvm-block -d - - 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 diff --git a/configuration/assigning-devices.md b/configuration/assigning-devices.md deleted file mode 100644 index a1394860..00000000 --- a/configuration/assigning-devices.md +++ /dev/null @@ -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 -~~~ - -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 \ No newline at end of file diff --git a/configuration/usb-qube-howto.md b/configuration/usb-qubes.md similarity index 93% rename from configuration/usb-qube-howto.md rename to configuration/usb-qubes.md index c48eb822..204a46a4 100644 --- a/configuration/usb-qube-howto.md +++ b/configuration/usb-qubes.md @@ -1,17 +1,23 @@ --- layout: doc -title: USB Qube HowTo -permalink: /doc/usb-qube-howto/ +title: USB Qubes +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 \ No newline at end of file +[create a USB qube]: #creating-and-using-a-usb-qube + diff --git a/customization/disposablevm-customization.md b/customization/disposablevm-customization.md index 9c2ba81b..eba8ae9d 100644 --- a/customization/disposablevm-customization.md +++ b/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: diff --git a/doc.md b/doc.md index fd7078ab..e6312a44 100644 --- a/doc.md +++ b/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/) - * [Using Block or Storage Devices in Qubes R4.0](/doc/block-devices/) - * [Using USB Devices in Qubes R4.0](/doc/usb-devices) + * [Block (or Storage) Devices](/doc/block-devices/) + * [USB Devices](/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/) - * [Creating a USB qube](/doc/usb-qube-howto/) + * [USB Qubes](/doc/usb-qubes/) * [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/) diff --git a/installing/install-security.md b/installing/install-security.md index bb7ba215..377d4081 100644 --- a/installing/install-security.md +++ b/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/ diff --git a/security/device-considerations.md b/security/device-handling-security.md similarity index 89% rename from security/device-considerations.md rename to security/device-handling-security.md index 4e116f3b..8759e26b 100644 --- a/security/device-considerations.md +++ b/security/device-handling-security.md @@ -1,22 +1,20 @@ --- layout: doc -title: Security Considerations When Handling Devices -permalink: /doc/device-considerations/ +title: Device Handling Security +permalink: /doc/device-handling-security/ --- -Security Considerations When Handling Devices -============================================= -General Words of Caution ------------------------- +# Device Handling Security # + 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]. -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. - +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 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. 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 \ No newline at end of file +[Software Attacks on Intel VT-d]: https://invisiblethingslab.com/resources/2011/Software%20Attacks%20on%20Intel%20VT-d.pdf + diff --git a/security/yubi-key.md b/security/yubi-key.md index f49ae067..b9995c94 100644 --- a/security/yubi-key.md +++ b/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. From bb449dac7cf8ca221114ba6a18e261a5b3c8a773 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Fri, 29 Mar 2019 19:40:14 -0500 Subject: [PATCH 24/25] Copy content from deprecated USB page --- common-tasks/block-devices.md | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/common-tasks/block-devices.md b/common-tasks/block-devices.md index daf85c36..1c58db63 100644 --- a/common-tasks/block-devices.md +++ b/common-tasks/block-devices.md @@ -115,7 +115,35 @@ To recover from this error state, in dom0 run (where `targetVM` is to be replaced with the VM name you attached the device to and `xvdi` is to be replaced with the used [frontend device node][frontend-dev].) -However, if the block device originated in dom0, you will have to refer to the [old way][detach dom0 device]. +However, if the block device originated in dom0, you will have to refer to the next section. + + +### What if I removed the device before detaching it from the VM?### + +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 File ## @@ -200,4 +228,5 @@ This option accepts `cdrom` and `disk`, default is `disk`. [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/ +[1082]: https://github.com/QubesOS/qubes-issues/issues/1082 From 566dce3793495b81d119ebfc302a581e4df6ea64 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Fri, 29 Mar 2019 19:40:36 -0500 Subject: [PATCH 25/25] Update link from deprecated USB page to new block device page --- about/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/about/faq.md b/about/faq.md index 691d98d1..ddcee6ea 100644 --- a/about/faq.md +++ b/about/faq.md @@ -436,7 +436,7 @@ In Qubes 4.0, this is accomplished with the Devices Widget located in the tool t In Qubes 3.2, you can use the Qubes VM Manager. 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. -Although external media such as external hard drives or flash drives plugged in via USB are available in the USB qube, it is not recommended to access them directly from inside the USB qube. See ["How to attach USB drives"](/doc/usb/#how-to-attach-usb-drives) for more information. +Although external media such as external hard drives or flash drives plugged in via USB are available in the USB qube, it is not recommended to access them directly from inside the USB qube. See [Block (Storage) Devices](/doc/block-devices/) for more information. ### My encrypted drive doesn't appear in Debian qube.