How to use devices: better cross-referencing

A lot of options of ``qvm-device`` command have been converted to Sphinx
options directives and references.

The `action-1` role doesn't seem to be used and the duplicate title was
producing a warning.

The Qubes Device Widget tray icon is presented as a figure, to get a
more consitent paragraph.

SYNOPSIS have been changed to code blocks.

The Device Widget icon is updated (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.
QubesOS/qubes-issues#4692 is closed so the corresponding paragraph has
been removed.
This commit is contained in:
parulin 2025-07-25 16:18:16 -04:00
parent b7ef85eae4
commit 598cc7c9a6
No known key found for this signature in database
GPG key ID: BC3830B42F4BF1F5
7 changed files with 90 additions and 70 deletions

View file

@ -15,7 +15,13 @@ Using the Devices Widget to Attach a Drive
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!
@ -47,7 +53,7 @@ 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``.
The command-line tool you may use to mount whole USB drives or their partitions is ``qvm-block``, a shortcut for :option:`qvm-device block`.
``qvm-block`` wont 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.
@ -182,7 +188,7 @@ To attach a file as block device to another qube, first turn it into a loopback
`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, youre 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, youre done. Click the Device Widget and select the ``loop0``-device to attach it to another qube.
- If you rather use the command line, continue:
@ -278,5 +284,3 @@ usage example:
This option accepts ``cdrom`` and ``disk``, default is ``disk``.
.. |device manager icon| image:: /attachment/doc/media-removable.png