mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-02-04 17:05:22 -05:00
Merge remote-tracking branch 'origin/pr/546'
* origin/pr/546: Update usb.md Add EFI, misc cleanup Add 4.0 content to usage of qubes-usb-proxy Incorporate Marmarek's comments Cleanup How to attach USB drives section update usb:How to attach USB drives with 4.0 move rarely used content down
This commit is contained in:
commit
1c844b47b1
@ -21,6 +21,322 @@ redirect_from:
|
||||
Using and Managing USB Devices
|
||||
==============================
|
||||
|
||||
How to attach USB drives
|
||||
------------------------
|
||||
|
||||
(**Note:** In the present context, the term "USB drive" denotes any
|
||||
[USB mass storage device][mass-storage]. In addition to smaller flash memory
|
||||
sticks, this includes things like USB external hard drives.)
|
||||
|
||||
Qubes OS supports the ability to attach a USB drive (or just one or more of its
|
||||
partitions) to any qube easily, no matter which qube actually handles the USB
|
||||
controller.
|
||||
|
||||
**R4.0**
|
||||
|
||||
USB drive mounting is integrated into the Devices Widget. This is the tool tray
|
||||
icon with a yellow square located in the top right of your screen by default.
|
||||
Simply insert
|
||||
your USB drive and click on the widget. You will see multiple entries for your
|
||||
USB drive; typically, `sys-usb:sda`, `sys-usb:sda1`, and `sys-usb:2-1` for example.
|
||||
The simplest (but slightly less secure, see note below about attaching individual
|
||||
partitions) option is to attach the entire block drive. In our example, this is `sda`,
|
||||
so hover over it.
|
||||
This will pop up a submenu showing running VMs to which the USB drive can be connected.
|
||||
Click on one and your USB drive will be attached!
|
||||
|
||||
Note that attaching individual partitions can be slightly more secure because it doesn't
|
||||
force the target AppVM to parse the partition table. However, it often means the
|
||||
AppVM won't detect the new partition and you will need to manually mount it inside
|
||||
the AppVM. See below for more detailed steps.
|
||||
|
||||
The command-line tool you may use to mount whole USB drives or their partitions
|
||||
is `qvm-block`. This tool can be used to assign a USB drive to a qube as
|
||||
follows:
|
||||
|
||||
1. Insert your USB drive.
|
||||
|
||||
2. In a dom0 console (running as a normal user), list all available block
|
||||
devices:
|
||||
|
||||
qvm-block
|
||||
|
||||
This will list all available block devices connected to any USB controller
|
||||
in your system, no matter which qube hosts the controller. The name of the
|
||||
qube hosting the USB controller is displayed before the colon in the device
|
||||
name. The string after the colon is the name of the device used within the
|
||||
qube, like so:
|
||||
|
||||
dom0:sdb1 Cruzer () 4GiB
|
||||
|
||||
usbVM:sdb1 Disk () 2GiB
|
||||
|
||||
**Note:** If your device is not listed here, you may refresh the list by
|
||||
calling from the qube to which the device is connected (typically `sys-usb`):
|
||||
|
||||
sudo udevadm trigger --action=change
|
||||
|
||||
3. Assuming your USB drive is attached to `sys-usb` and is `sdb`, we attach the
|
||||
device to a qube with the name `personal` like so:
|
||||
|
||||
qvm-block attach personal sys-usb:sdb
|
||||
|
||||
This will attach the device to the qube as `/dev/xvdi` if that name is not
|
||||
already taken by another attached device, or `/dev/xvdj`, etc.
|
||||
|
||||
You may also mount one partition at a time by using the same command with
|
||||
the partition number after `sdb`.
|
||||
|
||||
4. The USB drive is now attached to the qube. If using a default qube, you may
|
||||
open the Nautilus file manager in the qube, and your drive should be
|
||||
visible in the **Devices** panel on the left. If you've attached a single
|
||||
partition, you may need to manually mount before it becomes visible:
|
||||
```
|
||||
cd ~
|
||||
mkdir mnt
|
||||
sudo mount /dev/xvdi mnt
|
||||
```
|
||||
|
||||
5. When you finish using your USB drive, click the eject button or right-click
|
||||
and select **Unmount**. If you've manually mounted a single partition
|
||||
in the above step, use:
|
||||
`sudo umount mnt`
|
||||
|
||||
6. In a dom0 console, detach the stick
|
||||
|
||||
qvm-block detach <vmname> <device>
|
||||
|
||||
7. You may now remove the device.
|
||||
|
||||
**R3.2**
|
||||
|
||||
USB drive mounting is integrated into the Qubes VM Manager GUI. Simply insert
|
||||
your USB drive, right-click on the desired qube in the Qubes VM Manager list,
|
||||
click **Attach/detach block devices**, and select your desired action and
|
||||
device. This, however, only works for the whole device. If you would like to
|
||||
attach individual partitions, you must use the command-line tool.
|
||||
|
||||
Note that attaching individual partitions can be slightly more secure because it doesn't
|
||||
force the target AppVM to parse the partition table. However, it often means the
|
||||
AppVM won't detect the new partition and you will need to manually mount it inside
|
||||
the AppVM. See below for more detailed steps.
|
||||
|
||||
The command-line tool you may use to mount whole USB drives or their partitions
|
||||
is `qvm-block`. This tool can be used to assign a USB drive to a qube as
|
||||
follows:
|
||||
|
||||
1. Insert your USB drive.
|
||||
|
||||
2. In a dom0 console (running as a normal user), list all available block
|
||||
devices:
|
||||
|
||||
qvm-block
|
||||
|
||||
This will list all available block devices connected to any USB controller
|
||||
in your system, no matter which qube hosts the controller. The name of the
|
||||
qube hosting the USB controller is displayed before the colon in the device
|
||||
name. The string after the colon is the name of the device used within the
|
||||
qube, like so:
|
||||
|
||||
dom0:sdb1 Cruzer () 4GiB
|
||||
|
||||
usbVM:sdb1 Disk () 2GiB
|
||||
|
||||
**Note:** If your device is not listed here, you may refresh the list by
|
||||
calling from the qube to which the device is connected (typically `sys-usb`):
|
||||
|
||||
sudo udevadm trigger --action=change
|
||||
|
||||
3. Assuming your USB drive is attached to `sys-usb` and is `sdb`, we attach the
|
||||
device to a qube with the name `personal` like so:
|
||||
|
||||
qvm-block -a personal sys-usb:sdb
|
||||
|
||||
This will attach the device to the qube as `/dev/xvdi` if that name is not
|
||||
already taken by another attached device, or `/dev/xvdj`, etc.
|
||||
|
||||
You may also mount one partition at a time by using the same command with
|
||||
the partition number after `sdb`. This is slightly more secure because it
|
||||
does not force the target AppVM to parse the partition table.
|
||||
|
||||
**Warning:** when working with single partitions, it is possible to assign
|
||||
the same partition to multiple qubes. For example, you could attach `sdb1`
|
||||
to qube1 and then `sdb` to qube2. It is up to the user not to make this
|
||||
mistake. The Xen block device framework currently does not provide an easy
|
||||
way around this. Point 2 of [this comment on issue 1072][1072-comm2] gives
|
||||
details about this.
|
||||
|
||||
4. The USB drive is now attached to the qube. If using a default qube, you may
|
||||
open the Nautilus file manager in the qube, and your drive should be
|
||||
visible in the **Devices** panel on the left. If you've attached a single
|
||||
partition, you may need to manually mount before it becomes visible:
|
||||
```
|
||||
cd ~
|
||||
mkdir mnt
|
||||
sudo mount /dev/xvdi mnt
|
||||
```
|
||||
|
||||
5. When you finish using your USB drive, click the eject button or right-click
|
||||
and select **Unmount**. If you've manually mounted a single partition
|
||||
in the above step, use:
|
||||
`sudo umount mnt`
|
||||
|
||||
6. In a dom0 console, detach the stick
|
||||
|
||||
qvm-block -d <device>
|
||||
|
||||
or
|
||||
|
||||
qvm-block -d <vmname>
|
||||
|
||||
7. You may now remove the device.
|
||||
|
||||
**Warning:** Do not remove the device before detaching it from the VM!
|
||||
Otherwise, you will not be able to attach it anywhere later. See issue [1082]
|
||||
for details.
|
||||
|
||||
If the device does not appear in Nautilus, you will need to mount it
|
||||
manually. The device will show up as `/dev/xvdi` (or `/dev/xvdj` if there is
|
||||
already one device attached -- if two, `/dev/xvdk`, and so on).
|
||||
|
||||
|
||||
### What if I removed the device before detaching it from the VM? (R3.2) ###
|
||||
|
||||
Currently (until issue [1082] gets implemented), if you remove the device
|
||||
before detaching it from the qube, Qubes OS (more precisely, `libvirtd`) will
|
||||
think that the device is still attached to the qube and will not allow attaching
|
||||
further devices under the same name. The easiest way to recover from such a
|
||||
situation is to reboot the qube to which the device was attached, but if this
|
||||
isn't an option, you can manually recover from the situation by following these
|
||||
steps:
|
||||
|
||||
1. Physically connect the device back. You can use any device as long as it
|
||||
will be detected under the same name (for example, `sdb`).
|
||||
|
||||
2. Attach the device manually to the same VM using the `xl block-attach`
|
||||
command. It is important to use the same "frontend" device name (by default,
|
||||
`xvdi`). You can get it from the `qvm-block` listing:
|
||||
|
||||
[user@dom0 ~]$ qvm-block
|
||||
sys-usb:sda DataTraveler_2.0 () 246 MiB (attached to 'testvm' as 'xvdi')
|
||||
[user@dom0 ~]$ sudo xl block-attach testvm phy:/dev/sda backend=sys-usb xvdi
|
||||
|
||||
In above example, all `xl block-attach` parameters can be deduced from the
|
||||
output of `qvm-block`. In order:
|
||||
|
||||
* `testvm` - name of target qube to which device was attached - listed in
|
||||
brackets by `qvm-block` command
|
||||
* `phy:/dev/sda` - physical path at which device appears in source qube
|
||||
(just after source qube name in `qvm-block` output)
|
||||
* `backend=sys-usb` - name of source qube, can be omitted in case of dom0
|
||||
* `xvdi` - "frontend" device name (listed at the end of line in `qvm-block`
|
||||
output)
|
||||
|
||||
3. Now properly detach the device, either using Qubes VM Manager or the
|
||||
`qvm-block -d` command.
|
||||
|
||||
|
||||
Attaching a single USB device to a qube (USB passthrough)
|
||||
---------------------------------------------------------
|
||||
|
||||
Starting with Qubes 3.2, it is possible to attach a single USB device to any
|
||||
Qube. While this is useful feature, it should be used with care, because there
|
||||
are [many security implications][usb-challenges] from using USB devices and USB
|
||||
passthrough will **expose your target qube** for most of them. If possible, use
|
||||
method specific for particular device type (for example block devices described
|
||||
above), instead of this generic one.
|
||||
|
||||
### Installation of qubes-usb-proxy ###
|
||||
[installation]: #installation-of-qubes-usb-proxy
|
||||
|
||||
To use this feature, you need to install [`qubes-usb-proxy`][qubes-usb-proxy] package in the
|
||||
templates used for the USB qube and qubes you want to connect USB devices to. Note
|
||||
you cannot pass through devices from dom0 (in other words: USB VM is required).
|
||||
`qubes-usb-proxy` should be installed by default in the template VM.
|
||||
However, 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.
|
||||
|
||||
- Fedora: `sudo dnf install qubes-usb-proxy`
|
||||
- Debian/Ubuntu: `sudo apt-get install qubes-usb-proxy`
|
||||
|
||||
### Usage of qubes-usb-proxy (R4.0) ###
|
||||
|
||||
This feature is also available from the Devices Widget. This is the tool tray
|
||||
icon with a yellow square located in the top right of your screen by default.
|
||||
Simply insert
|
||||
your USB device and click on the widget. You will see an entry for your device
|
||||
such as `sys-usb:2-5 - 058f_USB_2.0_Camera` for example.
|
||||
Hover over it.
|
||||
This will pop up a submenu showing running VMs to which the USB device can be connected.
|
||||
Click on one and your device will be attached! You may also use the command line:
|
||||
|
||||
Listing available USB devices:
|
||||
|
||||
[user@dom0 ~]$ qvm-usb
|
||||
sys-usb:2-4 04ca:300d 04ca_300d
|
||||
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
|
||||
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
|
||||
|
||||
Attaching selected USB device:
|
||||
|
||||
[user@dom0 ~]$ qvm-usb attach conferences sys-usb:2-5
|
||||
[user@dom0 ~]$ qvm-usb
|
||||
conferences:2-1 058f:3822 058f_USB_2.0_Camera
|
||||
sys-usb:2-4 04ca:300d 04ca_300d
|
||||
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera (attached to conferences)
|
||||
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
|
||||
|
||||
Now, you can use your USB device (camera in this case) in the `conferences` qube.
|
||||
If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead,
|
||||
please refer to the [Installation Section][installation].
|
||||
|
||||
When you finish, detach the device. This can be done in the GUI by
|
||||
clicking on the Devices Widget. You will see an entry in bold for your device
|
||||
such as **`sys-usb:2-5 - 058f_USB_2.0_Camera`**.
|
||||
Hover over it.
|
||||
This will pop up a submenu showing running VMs. The one which your device is
|
||||
connected to will have an Eject button next to it. Click that and your device
|
||||
will be detached. You may also use the command line:
|
||||
|
||||
[user@dom0 ~]$ qvm-usb detach conferences sys-usb:2-5
|
||||
[user@dom0 ~]$ qvm-usb
|
||||
sys-usb:2-4 04ca:300d 04ca_300d
|
||||
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
|
||||
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
|
||||
|
||||
### Usage of qubes-usb-proxy (R3.2) ###
|
||||
|
||||
Listing available USB devices:
|
||||
|
||||
[user@dom0 ~]$ qvm-usb
|
||||
sys-usb:2-4 04ca:300d 04ca_300d
|
||||
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
|
||||
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
|
||||
|
||||
Attaching selected USB device:
|
||||
|
||||
[user@dom0 ~]$ qvm-usb -a conferences sys-usb:2-5
|
||||
[user@dom0 ~]$ qvm-usb
|
||||
conferences:2-1 058f:3822 058f_USB_2.0_Camera
|
||||
sys-usb:2-4 04ca:300d 04ca_300d
|
||||
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera (attached to conferences)
|
||||
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
|
||||
|
||||
Now, you can use your USB device (camera in this case) in the `conferences` qube.
|
||||
If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead,
|
||||
please refer to the [Installation Section][installation].
|
||||
|
||||
When you finish, detach the device:
|
||||
|
||||
[user@dom0 ~]$ qvm-usb -d sys-usb:2-5
|
||||
[user@dom0 ~]$ qvm-usb
|
||||
sys-usb:2-4 04ca:300d 04ca_300d
|
||||
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
|
||||
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
|
||||
|
||||
This feature is not available in Qubes Manager.
|
||||
|
||||
Creating and Using a USB qube
|
||||
-----------------------------
|
||||
|
||||
@ -40,17 +356,14 @@ 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).
|
||||
(see instructions above). The USB controller may be assigned on the **Devices** tab of a
|
||||
qube's settings page in Qubes VM Manager or by using the
|
||||
[qvm-pci][Assigning Devices] command. For guidance on finding the correct USB
|
||||
controller, see [here][usb-controller].
|
||||
You can create a USB qube using the management stack by performing the following
|
||||
steps as root in dom0:
|
||||
as root in dom0:
|
||||
|
||||
1. Enable `sys-usb`:
|
||||
|
||||
sudo qubesctl top.enable qvm.sys-usb
|
||||
|
||||
2. Apply the configuration:
|
||||
|
||||
sudo qubesctl state.highstate
|
||||
sudo qubesctl state.sls qvm.sys-usb
|
||||
|
||||
Alternatively, you can create a USB qube manually as follows:
|
||||
|
||||
@ -100,12 +413,22 @@ will hang.
|
||||
|
||||
The procedure to hide all USB controllers from dom0 is as follows:
|
||||
|
||||
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.
|
||||
* GRUB2
|
||||
|
||||
1. Open the file `/etc/default/grub` in dom0.
|
||||
2. Find the line that begins with `GRUB_CMDLINE_LINUX`.
|
||||
3. Add `rd.qubes.hide_all_usb` to that line.
|
||||
4. Save and close the file.
|
||||
5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
|
||||
6. Reboot.
|
||||
|
||||
* EFI
|
||||
|
||||
1. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0.
|
||||
2. Find the lines that begin with `kernel=`. There may be more than one.
|
||||
3. Add `rd.qubes.hide_all_usb` to those lines.
|
||||
4. Save and close the file.
|
||||
5. Reboot.
|
||||
|
||||
(Note: Beginning with R3.2, `rd.qubes.hide_all_usb` is set automatically if you
|
||||
opt to create a USB qube during installation. This also occurs automatically if
|
||||
@ -125,15 +448,26 @@ Removing a USB qube
|
||||
**Warning:** This procedure will result in your USB controller(s) being attached
|
||||
directly to dom0.
|
||||
|
||||
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.
|
||||
* GRUB2
|
||||
|
||||
1. Shut down the USB qube.
|
||||
2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
|
||||
3. Open the file `/etc/default/grub` in dom0.
|
||||
4. Find the line(s) that begins with `GRUB_CMDLINE_LINUX`.
|
||||
5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it.
|
||||
6. Save and close the file.
|
||||
7. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
|
||||
8. Reboot.
|
||||
|
||||
* EFI
|
||||
|
||||
1. Shut down the USB qube.
|
||||
2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
|
||||
3. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0.
|
||||
4. Find the line(s) that begins with `kernel=`.
|
||||
5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it.
|
||||
6. Save and close the file.
|
||||
7. Reboot.
|
||||
|
||||
Security Warning about USB Input Devices
|
||||
----------------------------------------
|
||||
@ -183,7 +517,12 @@ How to use a USB mouse
|
||||
|
||||
**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding.
|
||||
|
||||
In order to use a USB mouse, you must first attach it to a USB qube, then give that qube permission to pass mouse input to dom0.
|
||||
In order to use a USB mouse, you must first attach it to a USB qube, then give that
|
||||
qube permission to pass mouse input to dom0.
|
||||
The following steps are already done by default if you created the sys-usb qube with
|
||||
`qubesctl state.sls qvm.sys-usb` above, or let Qubes create it for you on first boot. However,
|
||||
if you've created the USB qube manually:
|
||||
|
||||
Edit the `qubes.InputMouse` policy file in dom0, which is located here:
|
||||
|
||||
/etc/qubes-rpc/policy/qubes.InputMouse
|
||||
@ -201,189 +540,6 @@ For a confirmation dialog each time the USB mouse is connected, change this line
|
||||
sys-usb dom0 ask,default_target=dom0
|
||||
```
|
||||
|
||||
How to attach USB drives
|
||||
------------------------
|
||||
|
||||
(**Note:** In the present context, the term "USB drive" denotes any
|
||||
[USB mass storage device][mass-storage]. In addition to smaller flash memory
|
||||
sticks, this includes things like USB external hard drives.)
|
||||
|
||||
Qubes OS supports the ability to attach a USB drive (or just one or more of its
|
||||
partitions) to any qube easily, no matter which qube actually handles the USB
|
||||
controller. (The USB controller may be assigned on the **Devices** tab of a
|
||||
qube's settings page in Qubes VM Manager or by using the
|
||||
[qvm-pci][Assigning Devices] command. For guidance on finding the correct USB
|
||||
controller, see [here][usb-controller].)
|
||||
|
||||
USB drive mounting is integrated into the Qubes VM Manager GUI. Simply insert
|
||||
your USB drive, right-click on the desired qube in the Qubes VM Manager list,
|
||||
click **Attach/detach block devices**, and select your desired action and
|
||||
device. This, however, only works for the whole device. If you would like to
|
||||
attach individual partitions, you must use the command-line tool.
|
||||
|
||||
The command-line tool you may use to mount whole USB drives or their partitions
|
||||
is `qvm-block`. This tool can be used to assign a USB drive to a qube as
|
||||
follows:
|
||||
|
||||
1. Insert your USB drive.
|
||||
|
||||
2. In a dom0 console (running as a normal user), list all available block
|
||||
devices:
|
||||
|
||||
qvm-block -l
|
||||
|
||||
This will list all available block devices connected to any USB controller
|
||||
in your system, no matter which qube hosts the controller. The name of the
|
||||
qube hosting the USB controller is displayed before the colon in the device
|
||||
name. The string after the colon is the name of the device used within the
|
||||
qube, like so:
|
||||
|
||||
dom0:sdb1 Cruzer () 4GiB
|
||||
|
||||
usbVM:sdb1 Disk () 2GiB
|
||||
|
||||
**Note:** If your device is not listed here, you may refresh the list by
|
||||
calling (from the qube to which the device is connected):
|
||||
|
||||
sudo udevadm trigger --action=change
|
||||
|
||||
3. Assuming your USB drive is attached to dom0 and is `sdb`, we attach the
|
||||
device to a qube with the name `personal` like so:
|
||||
|
||||
qvm-block -a personal dom0:sdb
|
||||
|
||||
This will attach the device to the qube as `/dev/xvdi` if that name is not
|
||||
already taken by another attached device, or `/dev/xvdj`, etc.
|
||||
|
||||
You may also mount one partition at a time by using the same command with
|
||||
the partition number after `sdb`.
|
||||
|
||||
**Warning:** when working with single partitions, it is possible to assign
|
||||
the same partition to multiple qubes. For example, you could attach `sdb1`
|
||||
to qube1 and then `sdb` to qube2. It is up to the user not to make this
|
||||
mistake. The Xen block device framework currently does not provide an easy
|
||||
way around this. Point 2 of [this comment on issue 1072][1072-comm2] gives
|
||||
details about this.
|
||||
|
||||
4. The USB drive is now attached to the qube. If using a default qube, you may
|
||||
open the Nautilus file manager in the qube, and your drive should be
|
||||
visible in the **Devices** panel on the left.
|
||||
|
||||
5. When you finish using your USB drive, click the eject button or right-click
|
||||
and select **Unmount**.
|
||||
|
||||
6. In a dom0 console, detach the stick
|
||||
|
||||
qvm-block -d <device>
|
||||
|
||||
or
|
||||
|
||||
qvm-block -d <vmname>
|
||||
|
||||
7. You may now remove the device.
|
||||
|
||||
**Warning:** Do not remove the device before detaching it from the VM!
|
||||
Otherwise, you will not be able to attach it anywhere later. See issue [1082]
|
||||
for details.
|
||||
|
||||
If the device does not appear in Nautilus, you will need to mount it
|
||||
manually. The device will show up as `/dev/xvdi` (or `/dev/xvdj` if there is
|
||||
already one device attached -- if two, `/dev/xvdk`, and so on).
|
||||
|
||||
|
||||
### What if I removed the device before detaching it from the VM? ###
|
||||
|
||||
Currently (until issue [1082] gets implemented), if you remove the device
|
||||
before detaching it from the qube, Qubes OS (more precisely, `libvirtd`) will
|
||||
think that the device is still attached to the qube and will not allow attaching
|
||||
further devices under the same name. The easiest way to recover from such a
|
||||
situation is to reboot the qube to which the device was attached, but if this
|
||||
isn't an option, you can manually recover from the situation by following these
|
||||
steps:
|
||||
|
||||
1. Physically connect the device back. You can use any device as long as it
|
||||
will be detected under the same name (for example, `sdb`).
|
||||
|
||||
2. Attach the device manually to the same VM using the `xl block-attach`
|
||||
command. It is important to use the same "frontend" device name (by default,
|
||||
`xvdi`). You can get it from the `qvm-block` listing:
|
||||
|
||||
[user@dom0 ~]$ qvm-block
|
||||
sys-usb:sda DataTraveler_2.0 () 246 MiB (attached to 'testvm' as 'xvdi')
|
||||
[user@dom0 ~]$ xl block-attach testvm phy:/dev/sda backend=sys-usb xvdi
|
||||
|
||||
In above example, all `xl block-attach` parameters can be deduced from the
|
||||
output of `qvm-block`. In order:
|
||||
|
||||
* `testvm` - name of target qube to which device was attached - listed in
|
||||
brackets by `qvm-block` command
|
||||
* `phy:/dev/sda` - physical path at which device appears in source qube
|
||||
(just after source qube name in `qvm-block` output)
|
||||
* `backend=sys-usb` - name of source qube, can be omitted in case of dom0
|
||||
* `xvdi` - "frontend" device name (listed at the end of line in `qvm-block`
|
||||
output)
|
||||
|
||||
3. Now properly detach the device, either using Qubes VM Manager or the
|
||||
`qvm-block -d` command.
|
||||
|
||||
|
||||
Attaching a single USB device to a qube (USB passthrough)
|
||||
---------------------------------------------------------
|
||||
|
||||
Starting with Qubes 3.2, it is possible to attach a single USB device to any
|
||||
Qube. While this is useful feature, it should be used with care, because there
|
||||
are [many security implications][usb-challenges] from using USB devices and USB
|
||||
passthrough will **expose your target qube** for most of them. If possible, use
|
||||
method specific for particular device type (for example block devices described
|
||||
above), instead of this generic one.
|
||||
|
||||
### Installation of qubes-usb-proxy ###
|
||||
[installation]: #installation-of-qubes-usb-proxy
|
||||
|
||||
To use this feature, you need to install [`qubes-usb-proxy`][qubes-usb-proxy] package in the
|
||||
templates used for the USB qube and qubes you want to connect USB devices to. Note
|
||||
you cannot pass through devices from dom0 (in other words: USB VM is required).
|
||||
`qubes-usb-proxy` should be installed by default in the template VM.
|
||||
However, 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.
|
||||
|
||||
- Fedora: `sudo dnf install qubes-usb-proxy`
|
||||
- Debian/Ubuntu: `sudo apt-get install qubes-usb-proxy`
|
||||
|
||||
### Usage of qubes-usb-proxy ###
|
||||
|
||||
Listing available USB devices:
|
||||
|
||||
[user@dom0 ~]$ qvm-usb
|
||||
sys-usb:2-4 04ca:300d 04ca_300d
|
||||
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
|
||||
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
|
||||
|
||||
Attaching selected USB device:
|
||||
|
||||
[user@dom0 ~]$ qvm-usb -a conferences sys-usb:2-5
|
||||
[user@dom0 ~]$ qvm-usb
|
||||
conferences:2-1 058f:3822 058f_USB_2.0_Camera
|
||||
sys-usb:2-4 04ca:300d 04ca_300d
|
||||
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera (attached to conferences)
|
||||
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
|
||||
|
||||
Now, you can use your USB device (camera in this case) in the `conferences` qube.
|
||||
If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead,
|
||||
please refer to the [Installation Section][installation].
|
||||
|
||||
When you finish, detach the device:
|
||||
|
||||
[user@dom0 ~]$ qvm-usb -d sys-usb:2-5
|
||||
[user@dom0 ~]$ qvm-usb
|
||||
sys-usb:2-4 04ca:300d 04ca_300d
|
||||
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
|
||||
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
|
||||
|
||||
This feature is not yet available in Qubes Manager however, if you would like to contribute to Qubes OS project by implementing it and are a student please consider applying for the [Google Summer of Code][gsoc-page] scholarship and choosing QubesOS Project as a mentor organization. You can find list of our our Project Ideas [here][project-page].
|
||||
|
||||
|
||||
[mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class
|
||||
[Assigning Devices]: /doc/assigning-devices/
|
||||
[usb-controller]: /doc/assigning-devices/#finding-the-right-usb-controller
|
||||
@ -398,8 +554,6 @@ This feature is not yet available in Qubes Manager however, if you would like to
|
||||
[1618]: https://github.com/QubesOS/qubes-issues/issues/1618
|
||||
[create a USB qube]: #creating-and-using-a-usb-qube
|
||||
[usb-challenges]: https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html
|
||||
[project-page]: /gsoc/
|
||||
[gsoc-page]: https://summerofcode.withgoogle.com/organizations/6239659689508864/
|
||||
[YubiKey]: /doc/YubiKey/
|
||||
[Security Warning about USB Input Devices]: #security-warning-about-usb-input-devices
|
||||
[qubes-usb-proxy]: https://github.com/QubesOS/qubes-app-linux-usb-proxy
|
||||
|
Loading…
x
Reference in New Issue
Block a user