Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-10-01 01:25:40 -04:00
Code Issues Packages Projects Releases Wiki Activity

Added rearranged documentation on devices in R4.0

Browse Source
This commit is contained in:
GammaSQ 2019-01-05 10:30:04 +01:00
parent c551a862aa
commit e2258ac74c
No known key found for this signature in database
GPG Key ID: D552FD2F98647C64
6 changed files with 841 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

164
common-tasks/block-devices.md Normal file
View File

@ -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*. <!--TODO: really? Didn't have a drive to test this quickly.-->
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.
<!--TODO: what happens if USB-device removed before detaching? How about attaching a blockdevice to two qubes?-->
#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 <!--TODO: find actual icon used in qubes!-->
[USB]:/dock/usb-devices-in-qubes-R4.0/

118
common-tasks/device-handling.md Normal file
View File

@ -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
<!--TODO: This seems like a very bad idea, but it's possible? When would I want to do that? What are the security-implications?-->
#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. <!--TODO: are specified VMs searched for AVAILABLE or also attached devices? Would after `qvm-usb a work sys-usb:1-1` the command `qvm-usb l work` yield any result?-->
`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`
<!--TODO: Is sourceVM:deviceID still required? -->
[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 <!--TODO: find actual icon used in qubes!-->
[eject icon]: https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/actions/media-eject.png

146
common-tasks/pci-devices.md Normal file
View File

@ -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 `<BDF>` with your full device, for example `0000:00:1c.2`:
echo <BDF> > /sys/bus/pci/drivers/pciback/unbind
MODALIAS=`cat /sys/bus/pci/devices/<BDF>/modalias`
MOD=`modprobe -R $MODALIAS | head -n 1`
echo <BDF> > /sys/bus/pci/drivers/$MOD/bind
It is **strongly discouraged to reattach PCI devices to dom0**, especially if they don't support resetting!
<!--TODO: Is this still needed?-->
[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

142
common-tasks/usb-devices.md Normal file
View File

@ -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. <!--TODO: Where is that 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.
##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
<!--TODO: This looks super old. Somebody please have a look! -->
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 <!--TODO: find actual icon used in qubes!-->
[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/

210
configuration/usb-qube-howto.md Normal file
View File

@ -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.
<!--TODO: How to undo?-->
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 ###
<!--TODO: What about LUKS-passphrase? At the very least I can't open a conformation-dialogue during boot?-->
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.) <!--TODO: Why user=root?-->
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]: <!--TODO: link specific section of qvm-device on identifying correct pci device!
[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
[manual setup]: #manual-setup
[install dom0 updates]: /doc/software-update-dom0/#how-to-update-software-in-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

61
security/device-considerations.md Normal file
View File

@ -0,0 +1,61 @@
---
layout: doc
title: Security Considerations When Handling Devices
permalink: /doc/device-considerations/
---
Security Considerations When Handling Devices
=============================================
General Words of Caution
------------------------
Any additional ability a VM gains is additional attack surface. It's a good idea to always attach the minimum entity required in a VM.
Attaching a full USB-device offers [more attack surface than attaching a single block device][USB security].
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
------------
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.)
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.
Additionally, Qubes restricts the config-space a VM may use to communicate with a PCI device. Only whitelisted registers are accessible. However, some devices or applications require full PCI access. In these cases, the whole config-space may be allowed. you're potentially weakening the device isolation, especially if your system is not equipped with a VT-d Interrupt Remapping unit. This increases the VM's ability to run a [side channel attack] and vulnerability to the same. <!--TODO: really? It seems obvious, but I'm missing citation.-->
See [Software Attacks on Intel VT-d] (page 7) for more details.
USB Security
------------
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.<!--TODO: what's the difference? What is meant by "USB qube" vs. "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