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

Naivly merging block-devices and usb-devices

Browse Source
This commit is contained in:
GammaSQ 2019-03-04 21:43:13 +01:00
parent af4c726b28
commit 1789ff6ddb
No known key found for this signature in database
GPG Key ID: D552FD2F98647C64
4 changed files with 177 additions and 190 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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 <!--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]:/dock/usb-devices-in-qubes-R4.0/

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

@ -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/

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

@ -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

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

@ -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/