Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-12-11 06:01:51 -05:00
Code Issues Projects Releases Packages Wiki Activity

Update device widget icon and remove issue link

Browse source 
* The Device Widget icon is updated, taken from
  [qubes-desktop-linux-manager](QubesOS/qubes-desktop-linux-manager/tree/release4.2/)
* As the original PNG was deleted, all the ``how-to-use-*-devices`` have
  been updated too (with a better markup)
* QubesOS/qubes-issues#4692 is closed so the corresponding paragraph has
  been removed.

Note: cherry-picked from #1492
This commit is contained in:
parulin 2025-09-19 16:13:40 -04:00
parent a595faa4e6
commit 69852d017a
No known key found for this signature in database
GPG key ID: 65099A5B0E31336C
5 changed files with 22 additions and 127 deletions
Download patch file Download diff file Expand all files Collapse all files

BIN
attachment/doc/media-removable.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 6.1 KiB

1
attachment/doc/qubes-devices.svg Normal file
View file

@ -0,0 +1 @@
<svg xmlns:xlink="http://www.w3.org/1999/xlink" width="26.136" xmlns="http://www.w3.org/2000/svg" height="27.392" id="screenshot-de3f5f2e-651c-801e-8003-497b6baebd5c" viewBox="-5.227 -1.305 26.136 27.392" style="-webkit-print-color-adjust: exact;" fill="none" version="1.1"><g id="shape-de3f5f2e-651c-801e-8003-497b6baebd5c" rx="0" ry="0"><g id="shape-de3f5f2e-651c-801e-8003-497abeb7e6e4"><g class="fills" id="fills-de3f5f2e-651c-801e-8003-497abeb7e6e4"><path d="M10.235777410044818,2.5312758605410863 h6.5 a1,1 0 0 1 1,1 v6 a0,0 0 0 1 0,0 h-8.5 a0,0 0 0 1 0,0 v-6 a1,1 0 0 1 1,-1 z" x="9.235777410044818" y="2.5312758605410863" transform="matrix(0.767072, 0.641561, -0.641561, 0.767072, 7.010645, -7.247096)" width="8.5" height="7" style="fill: rgb(155, 155, 155); fill-opacity: 1;"/></g></g><g id="shape-de3f5f2e-651c-801e-8003-497ad39f5ab2"><g class="fills" id="fills-de3f5f2e-651c-801e-8003-497ad39f5ab2"><rect rx="0" ry="0" x="14.469714467628762" y="5.386935461206235" transform="matrix(0.767072, 0.641561, -0.641561, 0.767072, 7.700937, -8.437069)" width="2" height="2" style="fill: rgb(235, 235, 235); fill-opacity: 1;"/></g></g><g id="shape-de3f5f2e-651c-801e-8003-497ad9b00fdb"><g class="fills" id="fills-de3f5f2e-651c-801e-8003-497ad9b00fdb"><rect rx="0" ry="0" x="11.78496225215207" y="3.141472136746529" transform="matrix(0.767072, 0.641561, -0.641561, 0.767072, 5.634982, -7.237668)" width="2.000000000000057" height="2.0000000000001137" style="fill: rgb(235, 235, 235); fill-opacity: 1;"/></g></g><g id="shape-de3f5f2e-651c-801e-8003-497aedbb68e1"><g class="fills" id="fills-de3f5f2e-651c-801e-8003-497aedbb68e1"><path d="M-1.725502478416331,7.459286392639228 h13.999999999999886 a0,0 0 0 1 0,0 v10 a6,6 0 0 1 -6,6 h-1.9999999999998863 a6,6 0 0 1 -6,-6 v-10 a0,0 0 0 1 0,0 z" x="-1.725502478416331" y="7.459286392639228" transform="matrix(0.767072, 0.641561, -0.641561, 0.767072, 11.146652, 0.216988)" width="13.999999999999886" height="16" style="fill: rgb(155, 155, 155); fill-opacity: 1;"/></g></g></g></svg>
Side by side

After

Width:  |  Height:  |  Size: 2 KiB

66
user/how-to-guides/how-to-use-block-storage-devices.rst
View file

@ -2,7 +2,6 @@
How to use block storage devices
================================
*This page is part of* :doc:`device handling in qubes </user/how-to-guides/how-to-use-devices>` *.*
If you don’t know what a “block device” is, just think of it as a fancy way to say “something that stores data”.
@ -10,12 +9,17 @@ If you don’t know what a “block device” is, just think of it as a fancy wa
Using the Devices Widget to Attach a Drive
------------------------------------------
(**Note:** In the present context, the term “USB drive” denotes any `USB mass storage device <https://en.wikipedia.org/wiki/USB_mass_storage_device_class>`__. 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 :doc:`whole usb-device </user/how-to-guides/how-to-use-usb-devices>`. 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``).
.. figure:: /attachment/doc/qubes-devices.svg
:alt:
:align: center
Qubes Devices Widget tray icon
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 :doc:`whole usb-device </user/how-to-guides/how-to-use-usb-devices>`. 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!
@ -24,7 +28,6 @@ The simplest option is to attach the entire block drive. In our example, this is
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:
.. code:: console
@ -33,8 +36,6 @@ If not specified otherwise, block devices will show up as ``/dev/xvdi*`` in a li
$ 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*.
@ -46,7 +47,6 @@ To specify this device node name, you need to use the command line tool and its
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.
@ -59,7 +59,6 @@ In case of a USB-drive, make sure it’s attached to your computer. If you don
$ 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:
.. code:: output
@ -67,22 +66,16 @@ In case of a USB-drive, make sure it’s attached to your computer. If you don
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:
.. code:: console
$ 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:
.. code:: console
@ -91,36 +84,25 @@ In case of a USB-drive, make sure it’s attached to your computer. If you don
$ 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:
.. code:: console
$ sudo umount mnt
5. In a dom0 console, detach the device
.. code:: console
$ 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 you fail to detach the device before it’s destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), `there will be problems <https://github.com/QubesOS/qubes-issues/issues/1082>`__.
To recover from this error state, in dom0 run
@ -129,8 +111,6 @@ 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 next section.
@ -138,7 +118,6 @@ However, if the block device originated in dom0, you will have to refer to the n
What if I removed the device before detaching it from the VM?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Currently (until issue `1082 <https://github.com/QubesOS/qubes-issues/issues/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. 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``).
@ -161,16 +140,11 @@ Currently (until issue `1082 <https://github.com/QubesOS/qubes-issues/issues/108
- ``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 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
@ -179,52 +153,40 @@ To attach a file as block device to another qube, first turn it into a loopback
$ sudo losetup -f --show /path/to/file
`This command <https://linux.die.net/man/8/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.
2. If you want to use the GUI, you’re done. Click the Device Widget 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:
.. code:: console
~]$ qvm-block
BACKEND:DEVID DESCRIPTION USED BY
sourceVM:loop0 /path/to/file
3. Attach the ``loop0``-device using qvm-block as usual:
.. code:: console
$ qvm-block a targetVM sourceVM:loop0
4. After detaching, destroy the loop-device inside the sourceVM as follows:
.. code:: console
$ 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:
@ -233,14 +195,11 @@ 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.
@ -251,22 +210,17 @@ usage example:
$ qvm-block a work sys-usb:sda1 -o read-only=true
There exists a shortcut to set read-only ``true``, ``--ro``:
.. code:: console
$ 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:
@ -275,8 +229,4 @@ usage example:
$ qvm-block a work sys-usb:sda1 -o devtype=cdrom
This option accepts ``cdrom`` and ``disk``, default is ``disk``.
.. |device manager icon| image:: /attachment/doc/media-removable.png

39
user/how-to-guides/how-to-use-devices.rst
View file

@ -2,7 +2,6 @@
How to use devices
==================
This is an overview of device handling in Qubes OS. For specific devices (:doc:`block </user/how-to-guides/how-to-use-block-storage-devices>`, :doc:`USB </user/how-to-guides/how-to-use-usb-devices>` and :doc:`PCI </user/how-to-guides/how-to-use-pci-devices>` devices), please visit their respective pages.
**Important security warning:** Device handling comes with many security implications. Please make sure you carefully read and understand the :doc:`security considerations </user/security-in-qubes/device-handling-security>`.
@ -10,7 +9,6 @@ This is an overview of device handling in Qubes OS. For specific devices (:doc:`
Introduction
------------
The interface to deal with devices of all sorts was unified in Qubes 4.0 with the ``qvm-device`` command and the Qubes Devices Widget. In Qubes 3.X, the Qubes VM Manager dealt with attachment as well. This functionality was moved to the Qubes Device Widget, the tool tray icon with a yellow square located in the top right of your screen by default.
There are currently four categories of devices Qubes understands:
@ -23,48 +21,44 @@ There are currently four categories of devices Qubes understands:
- PCI devices
Microphones, block devices and USB devices can be attached with the GUI-tool. PCI devices can be attached using the Qube Settings, but require a VM reboot.
General Qubes Device Widget Behavior And Handling
-------------------------------------------------
.. figure:: /attachment/doc/qubes-devices.svg
:alt:
:align: center
When clicking on the tray icon (which looks similar to this): |SD card and thumbdrive| several device-classes separated by lines are displayed as tooltip. Block devices are displayed on top, microphones one below and USB-devices at the bottom.
Qubes Devices Widget tray icon
When clicking on the tray icon, several device-classes separated by lines are displayed as tooltip. Block devices are displayed on top, microphones one below and USB-devices at the bottom.
On most laptops, integrated hardware such as cameras and fingerprint-readers are implemented as USB-devices and can be found here.
Attaching Using The Widget
^^^^^^^^^^^^^^^^^^^^^^^^^^
Click the tray icon. Hover on a device you want to attach to a VM. A list of running VMs (except dom0) appears. Click on one and your device will be attached!
Detaching Using The Widget
^^^^^^^^^^^^^^^^^^^^^^^^^^
To detach a device, click the Qubes Devices Widget icon again. Attached devices are displayed in bold. Hover the one you want to detach. A list of VMs appears, one showing the eject symbol: |eject icon|
Attaching a Device to Several VMs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Only ``mic`` should be attached to more than one running VM. You may *assign* a device to more than one VM (using the ``--persistent`` option), however, only one of them can be started at the same time.
But be careful: There is a `bug in <https://github.com/QubesOS/qubes-issues/issues/4692>`__ ``qvm-device block`` or ``qvm-block`` which will allow you to *attach* a block device to two running VMs. Don’t do that!
General ``qvm-device`` Command Line Tool Behavior
-------------------------------------------------
All devices, including PCI-devices, may be attached from the commandline using the ``qvm-device``-tools.
Device Classes
^^^^^^^^^^^^^^
``qvm-device`` expects DEVICE_CLASS as first argument. DEVICE_CLASS can be one of
- ``pci``
@ -75,12 +69,9 @@ Device Classes
- ``mic``
``qvm-device`` Actions
^^^^^^^^^^^^^^^^^^^^^^
``qvm-device`` supports three actions:
- ``list`` (ls, l) - list all devices of DEVICE_CLASS
@ -89,12 +80,9 @@ Device Classes
- ``detach`` (dt, d) - detach a specific device of DEVICE_CLASS
Global Options
^^^^^^^^^^^^^^
These three options are always available:
- ``--help``, ``-h`` - show help message and exit
@ -103,27 +91,20 @@ These three options are always available:
- ``--quiet``, ``-q`` - decrease verbosity
A full command consists of one DEVICE_CLASS and one action. If no action is given, list is implied. DEVICE_CLASS however is required.
**SYNOPSIS**: ``qvm-device DEVICE_CLASS {action} [action-specific arguments] [options]``
.. _actions-1:
Actions
-------
Actions are applicable to every DEVICE_CLASS and expose some additional options.
Listing Devices
^^^^^^^^^^^^^^^
The ``list`` action lists known devices in the system. ``list`` accepts VM-names to narrow down listed devices. Devices available in, as well as attached to the named VMs will be listed.
``list`` accepts two options:
@ -132,14 +113,11 @@ The ``list`` action lists known devices in the system. ``list`` accepts VM-names
- ``--exclude`` - exclude VMs from ``--all``. Requires ``--all``.
**SYNOPSIS** ``qvm-device DEVICE_CLASS {list|ls|l} [--all [--exclude VM [VM [...]]] | VM [VM [...]]]``
Attaching Devices
^^^^^^^^^^^^^^^^^
The ``attach`` action assigns an exposed device to a VM. This makes the device available in the VM it’s attached to. Required argument are targetVM and sourceVM:deviceID. (sourceVM:deviceID can be determined from ``list`` output)
``attach`` accepts two options:
@ -148,14 +126,11 @@ The ``attach`` action assigns an exposed device to a VM. This makes the device a
- ``--option``, ``-o`` - set additional options specific to DEVICE_CLASS.
**SYNOPSIS** ``qvm-device DEVICE_CLASS {attach|at|a} targetVM sourceVM:deviceID [options]``
Detaching Devices
^^^^^^^^^^^^^^^^^
The ``detach`` action removes an assigned device from a targetVM. It won’t be available afterwards anymore. Though it tries to do so gracefully, beware that data-connections might be broken unexpectedly, so close any transaction before detaching a device!
If no specific ``sourceVM:deviceID`` combination is given, *all devices of that DEVICE_CLASS will be detached.*
@ -164,6 +139,4 @@ If no specific ``sourceVM:deviceID`` combination is given, *all devices of that
**SYNOPSIS** ``qvm-device DEVICE_CLASS {detach|dt|d} targetVM [sourceVM:deviceID]``
.. |SD card and thumbdrive| image:: /attachment/doc/media-removable.png
.. |eject icon| image:: /attachment/doc/media-eject.png

43
user/how-to-guides/how-to-use-usb-devices.rst
View file

@ -2,7 +2,6 @@
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.
@ -19,19 +18,21 @@ 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
------------------------------------
With Qubes Device Widget
^^^^^^^^^^^^^^^^^^^^^^^^
With Qubes device manager
^^^^^^^^^^^^^^^^^^^^^^^^^
.. figure:: /attachment/doc/qubes-devices.svg
:alt:
:align: center
Qubes Devices Widget tray icon
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|
Click the Device Widget: 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 qubes you may attach it to.
@ -42,7 +43,6 @@ 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:
@ -55,7 +55,6 @@ 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:: console
@ -67,7 +66,6 @@ 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.
@ -81,21 +79,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.
@ -106,22 +100,15 @@ If you receive this error: ``ERROR: qubes-usb-proxy not installed in the qube``,
$ sudo dnf install qubes-usb-proxy
- Debian/Ubuntu:
.. code:: console
$ 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!
Mouse and keyboard setup are part of :doc:`setting up a USB qube </user/advanced-topics/usb-qubes>`.
@ -129,7 +116,6 @@ Mouse and keyboard setup are part of :doc:`setting up a USB qube </user/advanced
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.
@ -140,16 +126,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:: output
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.
@ -160,32 +142,24 @@ To find the right controller, follow the usb bus:
$ readlink /sys/bus/usb/devices/usb3
This should output something like:
.. code:: output
../../../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:: console
$ 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:: output
../../../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.
@ -193,7 +167,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``
@ -204,8 +177,6 @@ If, for example, you have 2 USB controllers in your system because you added one
Now you should be able to tell which is the BDF address of the mainboard USB controller or the added USB controller.
.. |device manager icon| image:: /attachment/doc/media-removable.png
.. |usb icon| image:: /attachment/doc/generic-usb.png
.. |eject icon| image:: /attachment/doc/media-eject.png