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

Merging usb & block by paragraphs

Browse Source
This commit is contained in:
GammaSQ 2019-03-04 23:06:28 +01:00
parent 1789ff6ddb
commit afa8308c46
No known key found for this signature in database
GPG Key ID: D552FD2F98647C64
3 changed files with 79 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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]` `qvm-device DEVICE_CLASS {detach|dt|d} targetVM [sourceVM:deviceID]`
[block]:/doc/usb-devices-in-qubes-R4.0/#drives-and-block-devices [block]:/doc/usb-devices-in-qubes-R4.0/
[USB]:/dock/usb-devices-in-qubes-R4.0/#handling-other-usb-devices [USB]:/dock/usb-devices-in-qubes-R4.0/
[PCI]:/doc/pci-devices-in-qubes-R4.0/ [PCI]:/doc/pci-devices-in-qubes-R4.0/
[security considerations]: /doc/device-considerations/ [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/ [device handling in qubes]: /doc/device-handling/
[security considerations]: /doc/device-considerations/#pci-security [security considerations]: /doc/device-considerations/#pci-security
[block]:/dock/usb-devices-in-qubes-R4.0/#drives-and-block-devices [block]:/dock/usb-devices-in-qubes-R4.0/
[USB]:/dock/usb-devices-in-qubes-R4.0/#handling-other-usb-devices [USB]:/dock/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
[qvm-device]: /doc/device-handling-in-qubes-R4.0/#general-qubes-device-widget-behavior-and-handling [qvm-device]: /doc/device-handling-in-qubes-R4.0/#general-qubes-device-widget-behavior-and-handling

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

@ -10,12 +10,17 @@ USB and Storage 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]!
Drives And Block Devices Examples for valid cases for attaching full USB-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 - [microcontroller programming]
- using [external audio devices]
- [optical drives] for recording
(If you are thinking to use a two-factor-authentication device, [there is an app for that][qubes u2f proxy]. But it has some [issues][4661].)
##Using The GUI to Attach a Drive
(**Note:** In the present context, the term "USB drive" denotes any [USB mass storage device][mass-storage]. (**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.) In addition to smaller flash memory sticks, this includes things like USB external hard drives.)
@ -35,6 +40,20 @@ Click on one and your USB drive will be attached!
However, it often means the AppVM won't detect the new partition and you will need to manually mount it inside the AppVM. 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. See below for more detailed steps.
##Using The GUI to Attach a USB-Device
Click the device-manager-icon: ![device manager icon]
A list of available devices appears. USB-devices have a USB-icon to their right: ![usb icon]
Hover on one device to display a list of VMs you may attach it to.
Click one of those. The USB device will be attached to it. You're done.
After you finished using the USB-device, you can detach it the same way by clicking on the Devices Widget.
You will see an entry in bold for your device such as **`sys-usb:2-5 - 058f_USB_2.0_Camera`**.
Hover on the attached device to display a list of running VMs.
The one to which your device is connected will have an eject button ![eject icon] next to it.
Click that and your device will be detached.
#Block Devices in VMs #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: If not specified otherwise, block devices will show up as `/dev/xvdi*` in a linux VM, where `*` may be the partition-number. If a block device isn't automatically mounted after attaching, open a terminal in the VM and execute:
@ -51,7 +70,7 @@ If several different block-devices are attached to a single VM, the last letter
To specify this device node name, you need to use the command line tool and its [`frontend-dev`-option][frontend-dev]. To specify this device node name, you need to use the command line tool and its [`frontend-dev`-option][frontend-dev].
#Command Line Tool Guide ##Attaching a Drive Using The Command-Line
The command-line tool you may use to mount whole USB drives or their partitions is `qvm-block`, a shortcut for `qvm-device block`. 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. `qvm-block` won't recognise your device by any given name, but rather the device-node the sourceVM assigns. So make sure you have the drive available in the sourceVM, then list the available block devices (step 1.) to find the corresponding device-node.
@ -98,47 +117,43 @@ In case of a USB-drive, make sure it's attached to your computer. If you don't s
6. You may now remove the device or attach it to another qube. 6. You may now remove the device or attach it to another qube.
#Recovering From Premature Device Destruction ##Attaching a Full USB-Device Using The Command-Line
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]. In dom0, you can use `qvm-usb` from the commandline to attach and detach devices.
To recover from this error state, in dom0 run Listing available USB devices:
virsh detach-disk targetVM xvdi [user@dom0 ~]$ qvm-usb
BACKEND:DEVID DESCRIPTION USED BY
sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
(where `targetVM` is to be replaced with the VM name you attached the device to and `xvdi` is to be replaced with the used [frontend device node][frontend-dev].) Attaching selected USB device:
However, if the block device originated in dom0, you will have to refer to the [old way][detach dom0 device]. [user@dom0 ~]$ qvm-usb attach work sys-usb:2-5
[user@dom0 ~]$ qvm-usb
BACKEND:DEVID DESCRIPTION USED BY
sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera work
sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse
#Attaching a File Now, you can use your USB device (camera in this case) in the `work` qube.
To attach a file as block device to another qube, first turn it into a loopback device inside the sourceVM. If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section].
1. In the linux sourceVM run When you finish, detach the device.
sudo losetup -f --show /path/to/file [user@dom0 ~]$ qvm-usb detach work sys-usb:2-5
[user@dom0 ~]$ qvm-usb
[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. BACKEND:DEVID DESCRIPTION USED BY
sys-usb:2-4 04ca:300d 04ca_300d
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. sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse
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 #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).) Attaching a block device through the command line offers additional customisation options, specifiable via the `--option`/`-o` option. (Yes, confusing wording, there's an [issue for that](https://github.com/QubesOS/qubes-issues/issues/4530).)
Note: `qvm-usb` does currently *not* support any additional options.
##frontend-dev ##frontend-dev
This option allows you to specify the name of the device node made available in the targetVM. This defaults to `xvdi` or, if already occupied, the first available device node name in alphabetical order. (The next one tried will be `xvdj`, then `xvdk`, and so on ...) This option allows you to specify the name of the device node made available in the targetVM. This defaults to `xvdi` or, if already occupied, the first available device node name in alphabetical order. (The next one tried will be `xvdj`, then `xvdk`, and so on ...)
@ -172,66 +187,44 @@ usage example:
This option accepts `cdrom` and `disk`, default is `disk`. This option accepts `cdrom` and `disk`, default is `disk`.
Handling other USB Devices #Miscellaneous/Customisation
========================== ##Recovering From Premature Block-Device Destruction
**Important security warning:** USB passthrough comes with many security implications! Please make sure you carefully read and understood the **[security considerations]**! Especially, whenever possible, attach a [block device] instead! If the you fail to detach the drive before it's destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), [there will be problems][premature removal].
Examples for valid cases for USB-passthrough: To recover from this error state, in dom0 run
- [microcontroller programming] virsh detach-disk targetVM xvdi
- using [external audio devices]
- [optical drives] for recording
(If you are thinking to use a two-factor-authentication device, [there is an app for that][qubes u2f proxy]. But it has some [issues][4661].) (where `targetVM` is to be replaced with the VM name you attached the device to and `xvdi` is to be replaced with the used [frontend device node][frontend-dev].)
#Attaching And Detaching a USB Device However, if the block device originated in dom0, you will have to refer to the [old way][detach dom0 device].
##With Qubes Device Manager
Click the device-manager-icon: ![device manager icon]
A list of available devices appears. USB-devices have a USB-icon to their right: ![usb icon]
Hover on one device to display a list of VMs you may attach it to. ##Attaching a File
To attach a file as block device to another qube, first turn it into a loopback device inside the sourceVM.
Click one of those. The USB device will be attached to it. You're done. 1. In the linux sourceVM run
After you finished using the USB-device, you can detach it the same way by clicking on the Devices Widget. sudo losetup -f --show /path/to/file
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 [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.
In dom0, you can use `qvm-usb` from the commandline to attach and detach devices.
Listing available USB devices: 2. If you want to use the GUI, you're done. Click the Device Manager ![device manager icon] and select the `loop0`-device to attach it to another qube.
[user@dom0 ~]$ qvm-usb If you rather use the command line, continue:
BACKEND:DEVID DESCRIPTION USED BY
sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
Attaching selected USB device: In dom0, run `qvm-block` to display known block devices. The newly created loop device should show up:
[user@dom0 ~]$ qvm-usb attach work sys-usb:2-5 ~]$ qvm-block
[user@dom0 ~]$ qvm-usb BACKEND:DEVID DESCRIPTION USED BY
BACKEND:DEVID DESCRIPTION USED BY sourceVM:loop0 /path/to/file
sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera work
sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse
Now, you can use your USB device (camera in this case) in the `work` qube. 3. Attach the `loop0`-device using qvm-block as usual:
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. qvm-block a targetVM sourceVM:loop0
[user@dom0 ~]$ qvm-usb detach work sys-usb:2-5 4. After detaching, destroy the loop-device inside the sourceVM as follows:
[user@dom0 ~]$ qvm-usb
BACKEND:DEVID DESCRIPTION USED BY
sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse
#Maintenance And Customisation sudo losetup -d /dev/loop0
##Creating And Using a USB qube ##Creating And Using a USB qube
If you've selected to install a usb-qube during system installation, everything is already set up for you in `sys-usb`. If you've later decided to create a usb-qube, please follow [this guide][USB-qube howto]. If you've selected to install a usb-qube during system installation, everything is already set up for you in `sys-usb`. If you've later decided to create a usb-qube, please follow [this guide][USB-qube howto].
@ -289,10 +282,9 @@ This should output something like:
Now you see the BDF address in the path (right before final `usb3`). 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]: #drives-and-block-devices
[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
@ -313,5 +305,4 @@ Strip the leading `0000:` and pass the rest to the [`qvm-pci` tool][qvm-pci] to
[frontend-dev]: #frontend-dev [frontend-dev]: #frontend-dev
[premature removal]: https://github.com/QubesOS/qubes-issues/issues/1082 [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 [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 [losetup]: https://linux.die.net/man/8/losetup
[USB]:/dock/usb-devices-in-qubes-R4.0/