suzanne.soy/qubes-doc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

reworking for split block and usb pages

Browse Source
This commit is contained in:
GammaSQ 2019-03-14 23:39:20 +01:00
parent 600dc5db6f
commit 6d6f32f788
No known key found for this signature in database
GPG Key ID: D552FD2F98647C64
6 changed files with 226 additions and 203 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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 <!--TODO: find actual icon used in qubes!-->
[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/

26
common-tasks/device-handling.md
View File

@ -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. 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. 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. 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! 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] 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. Only `mic` should be attached to more than one running VM. You may *assign* a device to more than one VM (using the [`--persistent`][#attaching-devices] option), however, only one of them can be started at the same time.
But be careful: There is a [bug in `qvm-device block` or `qvm-block`][i4692] which will allow you to *attach* a block device to two running VMs. Don't do that! But be careful: There is a [bug in `qvm-device block` or `qvm-block`][i4692] which will allow you to *attach* a block device to two running VMs. Don't do that!
# General `qvm-device` Command Line Tool Behavior # General `qvm-device` Command Line Tool Behavior #
All devices, including PCI-devices, may be attached from the commandline using the `qvm-device`-tools. 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 `qvm-device` expects DEVICE_CLASS as first argument. DEVICE_CLASS can be one of
- `pci` - `pci`
@ -52,7 +52,7 @@ All devices, including PCI-devices, may be attached from the commandline using t
- `block` - `block`
- `mic` - `mic`
## Actions ## Actions ##
`qvm-device` supports three actions: `qvm-device` supports three actions:
- `list` (ls, l) - list all devices of DEVICE_CLASS - `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 - `detach` (dt, d) - detach a specific device of DEVICE_CLASS
## Global Options ## Global Options ##
These three options are always available: These three options are always available:
- `--help`, `-h` - show help message and exit - `--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**: **SYNOPSIS**:
`qvm-device DEVICE_CLASS {action} [action-specific arguments] [options]` `qvm-device DEVICE_CLASS {action} [action-specific arguments] [options]`
## Actions ## Actions ##
Actions are applicable to every DEVICE_CLASS and expose some additional options. 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. 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: `list` accepts two options:
@ -87,7 +87,7 @@ The `list` action lists known devices in the system. `list` accepts VM-names to
**SYNOPSIS** **SYNOPSIS**
`qvm-device DEVICE_CLASS {list|ls|l} [--all [--exclude VM [VM [...]]] | VM [VM [...]]]` `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) 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: `attach` accepts two options:
@ -98,7 +98,7 @@ The `attach` action assigns an exposed device to a VM. This makes the device ava
**SYNOPSIS** **SYNOPSIS**
`qvm-device DEVICE_CLASS {attach|at|a} targetVM sourceVM:deviceID [options]` `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! 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.* 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]` `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/ [USB]:/doc/usb-devices-in-qubes-R4.0/
[PCI]:/doc/pci-devices-in-qubes-R4.0/ [PCI]:/doc/pci-devices-in-qubes-R4.0/

20
common-tasks/pci-devices.md
View File

@ -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 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. 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. The qube settings for a VM offers the "Devices"-tab. There you can attach PCI-devices to a qube.
1. To reach the settings of any qube either 1. To reach the settings of any qube either
@ -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. 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! 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]. 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: 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 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). 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. 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. 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. Sometimes the PCI arbitrator is too strict.
There is a way to enable permissive mode for it. 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. 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).) Attaching a PCI device through the commandline offers additional options, specifiable via the `--option`/`-o` option. (Yes, confusing wording, there's an [issue for that](https://github.com/QubesOS/qubes-issues/issues/4530).)
`qvm-pci` exposes two additional options. Both are intended to fix device or driver specific issues, but both come with [heavy security implications][security considerations]! **Make sure you understand them before continuing!** `qvm-pci` exposes two additional options. Both are intended to fix device or driver specific issues, but both come with [heavy security implications][security considerations]! **Make sure you understand them before continuing!**
## no-strict-reset ## no-strict-reset ##
Do not require PCI device to be reset before attaching it to another VM. This may leak usage data even without malicious intent! Do not require PCI device to be reset before attaching it to another VM. This may leak usage data even without malicious intent!
usage example: usage example:
qvm-pci a work dom0:00_1a.0 --persistent -o no-strict-reset=true qvm-pci a work dom0:00_1a.0 --persistent -o no-strict-reset=true
## permissive ## permissive ##
Allow write access to full PCI config space instead of whitelisted registers. This increases attack surface and possibility of [side channel attacks]. Allow write access to full PCI config space instead of whitelisted registers. This increases attack surface and possibility of [side channel attacks].
usage example: 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. 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. This is an intended feature.
@ -134,7 +134,7 @@ or
[device handling in qubes]: /doc/device-handling/ [device handling in qubes]: /doc/device-handling/
[security considerations]: /doc/device-considerations/#pci-security [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/ [USB]:/doc/usb-devices-in-qubes-R4.0/
[appmenu]: /attachment/wiki/Devices/qubes-appmenu-select.png [appmenu]: /attachment/wiki/Devices/qubes-appmenu-select.png
[domain manager icon]: /attachment/wiki/Devices/qubes-logo-icon.png [domain manager icon]: /attachment/wiki/Devices/qubes-logo-icon.png

196
common-tasks/usb-devices.md
View File

@ -6,13 +6,16 @@ redirect_from:
- /doc/usb-devices-in-qubes-R4.0/ - /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]* *This page is part of [device handling in qubes]*
(In case you were looking for the [R3.2 documentation](/doc/usb/).) (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] - [microcontroller programming]
- using [external audio devices] - 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].) (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 # Attaching And Detaching a USB Device #
(**Note:** In the present context, the term "USB drive" denotes any [USB mass storage device][mass-storage]. ## With Qubes Device Manager ##
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
Click the device-manager-icon: ![device manager icon] Click the device-manager-icon: ![device manager icon]
A list of available devices appears. USB-devices have a USB-icon to their right: ![usb icon] A list of available devices appears. USB-devices have a USB-icon to their right: ![usb icon]
@ -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. 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. Click that and your device will be detached.
# Block Devices in VMs ## With The Command Line Tool ##
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
In dom0, you can use `qvm-usb` from the commandline to attach and detach devices. In dom0, you can use `qvm-usb` from the commandline to attach and detach devices.
Listing available USB 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-5 058f:3822 058f_USB_2.0_Camera
sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse
# Additional Attach Options # Maintenance And Customisation #
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. ## Creating And Using a USB qube ##
## 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
If you've selected to install a usb-qube during system installation, everything is already set up for you in `sys-usb`. If you've later decided to create a usb-qube, please follow [this guide][USB-qube howto]. If you've selected to install a usb-qube during system installation, everything is already set up for you in `sys-usb`. If you've later decided to create a usb-qube, please follow [this guide][USB-qube howto].
## Installation Of `qubes-usb-proxy` ## 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. To use this feature, the[`qubes-usb-proxy`][qubes-usb-proxy] package needs to be installed in the templates used for the USB qube and qubes you want to connect USB devices to.
This section exists for reference or in case something broke and you need to reinstall `qubes-usb-proxy`. Under normal conditions, `qubes-usb-proxy` should already be installed and good to go. This section exists for reference or in case something broke and you need to reinstall `qubes-usb-proxy`. Under normal conditions, `qubes-usb-proxy` should already be installed and good to go.
@ -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` - 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! **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]. 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. 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. 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`). 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. 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/ [device handling in qubes]: /doc/device-handling/
[block device]: /doc/block-devices-in-qubes-R4.0/
[security considerations]: /doc/device-considerations/#usb-security [security considerations]: /doc/device-considerations/#usb-security
[usb-challenges]: https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html [usb-challenges]: https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html
[usb icon]: /attachment/wiki/Devices/generic-usb.png [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/ [USB-qube howto]: /doc/usb-qube-howto/
[keyboard setup]: /doc/usb-qube-howto/#enable-a-usb-keyboard-for-login [keyboard setup]: /doc/usb-qube-howto/#enable-a-usb-keyboard-for-login
[qvm-pci]: /doc/pci-devices-in-qubes-R4.0/ [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

2
customization/disposablevm-customization.md
View File

@ -182,7 +182,7 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe
[user@dom0 ~]$ qvm-pci [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 <backend>:<bdf> [user@dom0 ~]$ qvm-pci attach --persistent disp-sys-net <backend>:<bdf>

3
doc.md
View File

@ -67,7 +67,8 @@ redirect_from:
* [Backup, Restoration, and Migration](/doc/backup-restore/) * [Backup, Restoration, and Migration](/doc/backup-restore/)
* [Using DisposableVMs](/doc/disposablevm/) * [Using DisposableVMs](/doc/disposablevm/)
* [Using and Managing USB Devices in R3.2](/doc/usb/) * [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/) * [Optical Discs](/doc/optical-discs/)
* [Managing Application Shortcuts](/doc/managing-appvm-shortcuts/) * [Managing Application Shortcuts](/doc/managing-appvm-shortcuts/)
* [Enabling Fullscreen Mode](/doc/full-screen-mode/) * [Enabling Fullscreen Mode](/doc/full-screen-mode/)