mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-08-09 15:12:41 -04:00
Minor fixes on how-to-use-*-devices
* Use proper note or warning directives. * Use `console` instead of `bash` lexer when appropriate * Mark option as such when possible
This commit is contained in:
parulin
parent
10736c0023
commit
e8d7924dc4
3 changed files with 55 additions and 171 deletions
|
|
@ -2,14 +2,15 @@
|
|||
How to use USB devices
|
||||
======================
|
||||
|
||||
|
||||
*This page is part of* :doc:`device handling in qubes </user/how-to-guides/how-to-use-devices>` *.*
|
||||
|
||||
If you are looking to handle USB *storage* devices (thumbdrives or USB-drives), please have a look at the :doc:`block device </user/how-to-guides/how-to-use-block-storage-devices>` page.
|
||||
|
||||
**Note:** Attaching USB devices to qubes requires a :doc:`USB qube </user/advanced-topics/usb-qubes>`.
|
||||
.. note:: Attaching USB devices to qubes requires a :doc:`USB qube </user/advanced-topics/usb-qubes>`.
|
||||
|
||||
**Important security warning:** USB passthrough comes with many security implications. Please make sure you carefully read and understand the :ref:`security considerations <user/security-in-qubes/device-handling-security:usb security>`. Whenever possible, attach a :doc:`block device </user/how-to-guides/how-to-use-block-storage-devices>` instead.
|
||||
.. warning: **Important security warning**
|
||||
|
||||
USB passthrough comes with many security implications. Please make sure you carefully read and understand the :ref:`security considerations <user/security-in-qubes/device-handling-security:usb security>`. Whenever possible, attach a :doc:`block device </user/how-to-guides/how-to-use-block-storage-devices>` instead.
|
||||
|
||||
Examples of valid cases for USB-passthrough:
|
||||
|
||||
|
|
@ -19,14 +20,13 @@ Examples of valid cases for USB-passthrough:
|
|||
|
||||
- :doc:`optical drives </user/how-to-guides/how-to-use-optical-discs>` for recording
|
||||
|
||||
|
||||
|
||||
(If you are thinking to use a two-factor-authentication device, :doc:`there is an app for that </user/security-in-qubes/ctap-proxy>`. But it has some `issues <https://github.com/QubesOS/qubes-issues/issues/4661>`__.)
|
||||
|
||||
.. _attaching-and-detaching-a-usb-device:
|
||||
|
||||
Attaching and detaching a USB device
|
||||
------------------------------------
|
||||
|
||||
|
||||
With Qubes Device Widget
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
|
@ -34,7 +34,7 @@ With Qubes Device Widget
|
|||
:alt:
|
||||
:align: center
|
||||
|
||||
Qubes Devices Widget tray icon
|
||||
Qubes Devices Widget tray icon
|
||||
|
||||
Click the Device Widget: a list of available devices appears. USB-devices have a USB-icon to their right: |usb icon|
|
||||
|
||||
|
|
@ -47,12 +47,11 @@ After you finished using the USB-device, you can detach it the same way by click
|
|||
With the command line tool
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
In dom0, you can use ``qvm-usb`` from the commandline to attach and detach devices.
|
||||
|
||||
Listing available USB devices:
|
||||
|
||||
.. code:: bash
|
||||
.. code:: console
|
||||
|
||||
[user@dom0 ~]$ qvm-usb
|
||||
BACKEND:DEVID DESCRIPTION USED BY
|
||||
|
|
@ -60,10 +59,9 @@ Listing available USB devices:
|
|||
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:
|
||||
|
||||
.. code:: bash
|
||||
.. code:: console
|
||||
|
||||
[user@dom0 ~]$ qvm-usb attach work sys-usb:2-5
|
||||
[user@dom0 ~]$ qvm-usb
|
||||
|
|
@ -72,12 +70,11 @@ Attaching selected USB device:
|
|||
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 qube`` instead, please refer to the `Installation Section <#installation-of-qubes-usb-proxy>`__.
|
||||
|
||||
When you finish, detach the device.
|
||||
|
||||
.. code:: bash
|
||||
.. code:: console
|
||||
|
||||
[user@dom0 ~]$ qvm-usb detach work sys-usb:2-5
|
||||
[user@dom0 ~]$ qvm-usb
|
||||
|
|
@ -86,21 +83,17 @@ When you finish, detach the device.
|
|||
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
|
||||
sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse
|
||||
|
||||
|
||||
Maintenance and customisation
|
||||
-----------------------------
|
||||
|
||||
|
||||
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 :doc:`this guide </user/advanced-topics/usb-qubes>`.
|
||||
|
||||
Installation of ``qubes-usb-proxy``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
To use this feature, the ``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 qube``, you can install the ``qubes-usb-proxy`` with the package manager in the qube you want to attach the USB device to.
|
||||
|
|
@ -111,30 +104,22 @@ If you receive this error: ``ERROR: qubes-usb-proxy not installed in the qube``,
|
|||
|
||||
sudo dnf install qubes-usb-proxy
|
||||
|
||||
|
||||
|
||||
- Debian/Ubuntu:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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 :ref:`security considerations <user/security-in-qubes/device-handling-security:usb security>` 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 :ref:`security considerations <user/security-in-qubes/device-handling-security:usb security>` before continuing!
|
||||
|
||||
Mouse and keyboard setup are part of :doc:`setting up a USB qube </user/advanced-topics/usb-qubes>`.
|
||||
|
||||
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 you cannot attach single *USB devices* but have to attach the whole *USB controller* with whatever USB devices are connected to it.
|
||||
|
||||
You can find your controller and its BDF address using the method described below, using the command-line tools ``lsusb`` and ``readlink``. If you have multiple USB controllers, you must first figure out which PCI device is the right controller.
|
||||
|
|
@ -145,16 +130,12 @@ First, find out which USB bus the device is connected to (note that these steps
|
|||
|
||||
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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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 attached to the target qube.
|
||||
|
|
@ -165,32 +146,24 @@ To find the right controller, follow the usb bus:
|
|||
|
||||
readlink /sys/bus/usb/devices/usb3
|
||||
|
||||
|
||||
|
||||
This should output something like:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
|
||||
|
||||
|
||||
|
||||
Now you see the path: the text between ``/pci0000:00/0000:`` and ``/usb3`` i.e. ``00:1a.0`` is the BDF address. Strip the address and pass it to the :doc:`qvm-pci tool </user/how-to-guides/how-to-use-pci-devices>` to attach the controller to the target qube, like this:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
qvm-pci attach --persistent personal dom0:00_1a.0
|
||||
|
||||
|
||||
|
||||
It is possible that on some system configurations the readlink method produces output which is different from the example above, For example, you might see output like this:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
../../../devices/pci0000:00/0000:00:1c.0/0000:01:00.0/usb1
|
||||
|
||||
|
||||
|
||||
In this case, there is a PCI bridge, and the BDF address of the controller is the *last* item, 01:00.0
|
||||
|
||||
If the output format does not match this example, or you are unsure if it contains the correct BDF address, you can try finding the address using using the Qube Manager instead.
|
||||
|
|
@ -198,7 +171,6 @@ If the output format does not match this example, or you are unsure if it contai
|
|||
Identifying controllers using the Qube Manager
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
Using Qube Manager you can quickly determine the controllers on your system and their BDF addresses, but not which controller a particular device is attached to.
|
||||
|
||||
Open the Qube Manager, then right click on one of the qubes and open the settings. Go to the tab “Devices”. Here you should see your available devices along with their BDF addresses. Look for the lines containing “USB controller”. They should look something like: ``01:00.0 USB controller: Name of manufacturer``
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue