15 KiB
layout | title | permalink | redirect_from | |
---|---|---|---|---|
doc | USB Devices in Qubes R4.0 | /doc/usb-devices/ |
|
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.) 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!
Examples for valid cases for attaching full USB-devices:
- 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. But it has some issues.)
Using The GUI to Attach a Drive
(Note: In the present context, the term "USB drive" denotes any USB mass storage device. 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:
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. 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:
A list of available devices appears. USB-devices have a USB-icon to their right:
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 next to it.
Click that and your device will be detached.
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.
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
)
-
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
-
Assuming your block device is attached to
sys-usb
and its device node issdb
, we attach the device to a qube with the namework
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
. -
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 ofsdb
in our example), you may need to manually mount before it becomes visible:cd ~ mkdir mnt sudo mount /dev/xvdi mnt
-
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
-
In a dom0 console, detach the device
qvm-block detach work sys-usb:sdb
-
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.
Listing available USB devices:
[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
Attaching selected USB 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
Now, you can use your USB device (camera in this case) in the work
qube.
If you see the error ERROR: qubes-usb-proxy not installed in the VM
instead, please refer to the Installation Section.
When you finish, detach the device.
[user@dom0 ~]$ qvm-usb detach work sys-usb:2-5
[user@dom0 ~]$ qvm-usb
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
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.)
Note: qvm-usb
does currently not support any additional options.
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.
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.)
However, if the block device originated in dom0, you will have to refer to the old way.
Attaching a File
To attach a file as block device to another qube, first turn it into a loopback device inside the sourceVM.
-
In the linux sourceVM run
sudo losetup -f --show /path/to/file
This command 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. -
If you want to use the GUI, you're done. Click the Device Manager 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
-
Attach the
loop0
-device using qvm-block as usual:qvm-block a targetVM sourceVM:loop0
-
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.
Installation Of qubes-usb-proxy
To use this feature, the[qubes-usb-proxy
][qubes-usb-proxy] package needs to be installed in the templates used for the USB qube and qubes you want to connect USB devices to.
This section exists for reference or in case something broke and you need to reinstall qubes-usb-proxy
. Under normal conditions, qubes-usb-proxy
should already be installed and good to go.
If you receive this error: ERROR: qubes-usb-proxy not installed in the VM
, you can install the qubes-usb-proxy
with the package manager in the VM you want to attach the USB device to.
Note: you cannot pass through devices from dom0 (in other words: a USB qube is required).
qubes-usb-proxy
should be installed by default in the template VM.
- Fedora:
sudo dnf install qubes-usb-proxy
- Debian/Ubuntu:
sudo apt-get install qubes-usb-proxy
Using USB Keyboards And Other Input Devices
Warning: especially keyboards need to be accepted by default when using them to login! Please make sure you carefully read and understood the security considerations before continuing!
Mouse and keyboard setup are part of setting up a USB-qube.
Finding The Right USB Controller
Some USB devices are not compatible with the USB pass-through method Qubes employs. In situations like these, you can try to pass through the entire USB controller to a qube as PCI device. However, with this approach one cannot attach single USB devices but has to attach the whole USB controller with whatever USB devices are connected to it.
If you have multiple USB controllers, you must first figure out which PCI device is the right controller.
First, find out which USB bus the device is connected to (note that these steps need to be run from a terminal inside your USB qube):
lsusb
For example, I want to attach a broadband modem to the NetVM.
In the output of lsusb
it may be listed as something like:
Bus 003 Device 003: ID 413c:818d Dell Computer Corp.
(In this case, the device isn't fully identified)
The device is connected to USB bus #3. Check which other devices are connected to the same bus, since all of them will be attach to the same VM.
To find the right controller, follow the usb bus:
readlink /sys/bus/usb/devices/usb3
This should output something like:
../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
Now you see the BDF address in the path (right before final usb3
).
Strip the leading 0000:
and pass the rest to the qvm-pci
tool to attach the controller to the targetVM.