Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-08-06 13:44:22 -04:00
Code Issues Projects Releases Packages Wiki Activity

Merge ccf5ec3e7f into ba609d123e

Browse source
This commit is contained in:
parulin 2025-07-27 09:59:54 +00:00 • committed by GitHub
commit 93b9a42495
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
13 changed files with 193 additions and 357 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

2
developer/system/audio.rst
View file

@ -67,4 +67,4 @@ In Qubes R4.1 and later, ``pacat-simple-vchan`` is controlled over a UNIX socket
These commands can be sent using the ``qubes.AudioInputEnable+VMNAME`` and ``qubes.AudioInputDisable+VMNAME`` qrexec services, respectively. The current status is written into QubesDB at ``/audio-input/VMNAME`` (where ``VMNAME`` is the VM’s name) with either ``1`` or ``0`` values. The lack of a key means that the ``pacat-simple-vchan`` for a given VM is not running.
In either version, it is exposed to the user as device of class ``mic``, which can be attached to a VM (for example, using the ``qvm-device mic`` command).
In either version, it is exposed to the user as device of class ``mic``, which can be attached to a VM (for example, using the :option:`qvm-device mic` command).

55
introduction/intro.rst
View file

@ -8,7 +8,6 @@ What is Qubes OS?
Qubes OS is a free and open-source, security-oriented operating system for
single-user desktop computing. Qubes OS `leverages Xen-based virtualization <https://wiki.xen.org/wiki/Xen_Project_Software_Overview>`__ to allow for the creation and management of isolated compartments called :ref:`qubes <user/reference/glossary:qube>`.
These qubes, which are implemented as :ref:`virtual machines (VMs)<user/reference/glossary:vm>`, have specific:
- **Purposes:** with a predefined set of one or many isolated
@ -24,15 +23,13 @@ These qubes, which are implemented as :ref:`virtual machines (VMs)<user/referenc
- **Levels of trust:** from complete to non-existent. All windows are displayed in a unified desktop environment with
:doc:`unforgeable colored window borders </introduction/getting-started>` so that different security levels are easily identifiable.
.. figure:: /attachment/site/qubes-trust-level-architecture.png
:alt: Qubes system diagram
.. image:: /attachment/site/qubes-trust-level-architecture.png
:alt:
.. note::
**Note:** See our :doc:`glossary </user/reference/glossary>` and :doc:`FAQ </introduction/faq>` for more information.
Features
--------
@ -43,7 +40,6 @@ Features
share a root file system without sacrificing security using the innovative
:doc:`Template system </user/templates/templates>`.
- **Multiple operating systems** Use multiple operating systems at the same time, including
:doc:`Fedora </user/templates/fedora/fedora>`, :doc:`Debian </user/templates/debian/debian/>`, and
`Windows <https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows.md>`__
@ -60,16 +56,13 @@ Features
- **Open-source** Users are free to use, copy, and modify Qubes OS and :doc:`are encouraged to do so! </introduction/contributing>`
.. note::
**Note:** Given the technical nature of Qubes OS, prior experience with Linux can be helpful.
Why Qubes OS?
-------------
Physical isolation is a given safeguard that the digital world lacks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -90,18 +83,12 @@ Better yet, it allows us to create new compartments whenever we need them,
and it gives us sophisticated tools for securely managing our activities
and data across these compartments.
.. figure:: /attachment/doc/r4.0-qubes-manager.png
:alt: Qubes manager
.. image:: /attachment/doc/r4.0-qubes-manager.png
:alt:
Qubes allows you to compartmentalize your digital life
------------------------------------------------------
.. figure:: /attachment/site/qubes-partition-data-flows.jpg
:alt: Compartmentalization example
Many of us are initially surprised to learn that our devices do not
support the kind of secure compartmentalization that our lives demand, and
we're disappointed that software vendors rely on generic defenses that
@ -125,11 +112,12 @@ physical computer without having to worry about a single successful
cyberattack taking down your entire digital life in one fell swoop. In
fact, Qubes has `distinct advantages over physical air gaps <https://invisiblethingslab.com/resources/2014/Software_compartmentalization_vs_physical_separation.pdf>`__.
.. image:: /attachment/site/qubes-partition-data-flows.jpg
:alt:
Made to support vulnerable users and power users alike
------------------------------------------------------
Qubes provides practical, usable security to vulnerable and
actively-targeted individuals, such as journalists, activists,
whistleblowers, and researchers. Qubes is designed with the understanding
@ -154,31 +142,15 @@ software, because the fundamental operating system that constitutes the
core infrastructure of our digital lives **must** be free and
open-source in order to be trustworthy.
.. image:: /attachment/doc/r4.0-snapshot12.png
:alt:
.. figure:: /attachment/doc/r4.0-snapshot12.png
:alt: Qubes desktop screenshot
Video Tours
~~~~~~~~~~~
Want to see Qubes OS in action? Sit back and watch a guided :doc:`tour! </introduction/video-tours/>`
Screenshots
~~~~~~~~~~~
See what using Qubes actually looks like with these :doc:`screenshots </introduction/screenshots/>` of various
applications running in Qubes.
Getting Started
~~~~~~~~~~~~~~~
Ready to get started with Qubes? :doc:`Here's </introduction/getting-started>` what you need to know after installing.
Qubes OS at a glance
--------------------
- :doc:`Video tours</introduction/video-tours/>`: want to see Qubes OS in action? Sit back and watch one of the guided tour!
- :doc:`Screenshots </introduction/screenshots/>`: see what using Qubes actually looks like with various applications running in Qubes.
- :doc:`Getting started </introduction/getting-started>`: ready to get started with Qubes? Find all you need to know after installing.
More information
----------------
@ -187,7 +159,6 @@ This page is just a brief introduction to what Qubes is all about, and
many technical details have been omitted here for the sake of
presentation.
- If you’re a current or potential Qubes user, you may want to check out the :doc:`documentation </index>` and the :ref:`user FAQ <introduction/faq:users>`.
- If you’re a developer, there’s dedicated :ref:`developer documentation <index:developer documentation>` and a :ref:`developer FAQ <introduction/faq:developers>` just for you.
- Ready to give Qubes a try? Head on over to the `downloads page <https://www.qubes-os.org/downloads/>`__, and read the :doc:`installation guide </user/downloading-installing-upgrading/installation-guide>`.

2
user/advanced-topics/disposable-customization.rst
View file

@ -107,7 +107,7 @@ Next, set the old ``sys-firewall`` autostart to false, and update any references
To create one with a PCI device attached such as for ``sys-net`` or ``sys-usb``, use the additional commands as follows.
**Note:** You can use ``qvm-pci`` to :ref:`determine <user/how-to-guides/how-to-use-pci-devices:\`\`qvm-pci\`\` usage>` the ``<BDF>``. Also, you will often need to include the ``-o no-strict-reset=True`` :ref:`option <user/how-to-guides/how-to-use-pci-devices:no-strict-reset>` with USB controllers.
**Note:** You can use ``qvm-pci`` to :ref:`determine <user/how-to-guides/how-to-use-pci-devices:\`\`qvm-pci\`\` usage>` the ``<BDF>``. Also, you will often need to include the ``-o no-strict-reset=True`` :option:`no-strict-reset` option with USB controllers.
.. code:: bash

12
user/how-to-guides/how-to-reinstall-a-template.rst
View file

@ -11,7 +11,7 @@ Automatic Method
First, copy any files that you wish to keep from the template’s ``/home`` and ``/rw`` folders to a safe storage location. Then, in a dom0 terminal, run:
.. code:: bash
.. code:: console
$ sudo qubes-dom0-update --action=reinstall qubes-template-package-name
@ -23,7 +23,7 @@ Note that Qubes may initially refuse to perform the reinstall if the exact revis
**Reminder:** If you’re trying to reinstall a template that is not in an enabled repo, you must enable that repo. For example:
.. code:: bash
.. code:: console
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinstall qubes-template-whonix-ws
@ -51,14 +51,14 @@ In what follows, the term “target template” refers to whichever template you
3. Uninstall the target template from dom0:
.. code:: bash
.. code:: console
$ sudo dnf remove <template-package-name>
For example, to uninstall the ``whonix-gw`` template:
.. code:: bash
.. code:: console
$ sudo dnf remove qubes-template-whonix-gw
@ -66,14 +66,14 @@ In what follows, the term “target template” refers to whichever template you
4. Reinstall the target template in dom0:
.. code:: bash
.. code:: console
$ sudo qubes-dom0-update --enablerepo=<optional-additional-repo> \
<template-package-name>
For example, to install the ``whonix-gw`` template:
.. code:: bash
.. code:: console
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community \
qubes-template-whonix-gw

91
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,21 +9,25 @@ 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.)
.. 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!
**Note:** attaching individual partitions (e.g. ``sys-usb:sda1``) can be slightly more secure because it doesn’t force the target app qube to parse the partition table. However, it often means the app qube won’t detect the new partition and you will need to manually mount it inside the app qube. See below for more detailed steps.
.. note:: attaching individual partitions (e.g. ``sys-usb:sda1``) can be slightly more secure because it doesn’t force the target app qube to parse the partition table. However, it often means the app qube won’t detect the new partition and you will need to manually mount it inside the app qube. See below for more detailed steps.
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:: bash
@ -33,21 +36,18 @@ 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*.
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 <#frontend-dev>`__.
To specify this device node name, you need to use the command line tool and its :option:`frontend-dev` option.
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`` 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,30 +59,23 @@ 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:: bash
.. code:: console
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:: bash
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:: bash
@ -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:: bash
sudo umount mnt
5. In a dom0 console, detach the device
.. code:: bash
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,14 +118,13 @@ 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``).
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:
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-block
sys-usb:sda DataTraveler_2.0 () 246 MiB (attached to 'testvm' as 'xvdi')
@ -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,51 +153,38 @@ 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
.. code:: bash
~]$ qvm-block
[user@dom0 ~]$ qvm-block
BACKEND:DEVID DESCRIPTION USED BY
sourceVM:loop0 /path/to/file
3. Attach the ``loop0``-device using qvm-block as usual:
.. code:: bash
qvm-block a targetVM sourceVM:loop0
4. After detaching, destroy the loop-device inside the sourceVM as follows:
.. code:: bash
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
^^^^^^^^^^^^
.. option:: 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 …)
@ -233,13 +194,9 @@ 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
^^^^^^^^^
.. option:: read-only
Attach device in read-only mode. Protects the block device in case you don’t trust the targetVM.
@ -251,21 +208,15 @@ usage example:
qvm-block a work sys-usb:sda1 -o read-only=true
There exists a shortcut to set read-only ``true``, ``--ro``:
.. code:: bash
qvm-block a work sys-usb:sda1 --ro
The two commands are equivalent.
devtype
^^^^^^^
.. option:: devtype
Usually, a block device is attached as disk. In case you need to attach a block device as cdrom, this option allows that.
@ -275,8 +226,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

128
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,160 +9,173 @@ 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:
- Microphones
- Block devices
- USB devices
- 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!
Only ``mic`` should be attached to more than one running VM. You may *assign* a device to more than one VM (using the :option:`--persistent <qvm-device attach --persistent>` option), however, only one of them can be started at the same time.
General ``qvm-device`` Command Line Tool Behavior
-------------------------------------------------
All devices, including PCI-devices, may be attached from the commandline using the ``qvm-device``-tools.
All devices, including PCI-devices, may be attached from the commandline using the ``qvm-device`` tools.
Device Classes
^^^^^^^^^^^^^^
.. program:: qvm-device
``qvm-device`` expects DEVICE_CLASS as first argument. DEVICE_CLASS can be one of
``qvm-device`` expects :option:`DEVICE_CLASS` as first argument.
- ``pci``
.. option:: DEVICE_CLASS
- ``usb``
can be one of the following
- ``block``
- ``mic``
Actions
^^^^^^^
.. option:: pci
.. option:: usb
.. option:: block
.. option:: mic
Actions overview
^^^^^^^^^^^^^^^^
``qvm-device`` supports three actions:
- ``list`` (ls, l) - list all devices of DEVICE_CLASS
.. option:: list, ls, l
- ``attach`` (at, a) - attach a specific device of DEVICE_CLASS
list all devices of :option:`DEVICE_CLASS`
- ``detach`` (dt, d) - detach a specific device of DEVICE_CLASS
.. option:: attach, at, a
attach a specific device of :option:`DEVICE_CLASS`
.. option:: detach, dt, d
detach a specific device of :option:`DEVICE_CLASS`
Global Options
^^^^^^^^^^^^^^
These three options are always available:
- ``--help``, ``-h`` - show help message and exit
.. option:: --help, -h
- ``--verbose``, ``-v`` - increase verbosity
show help message and exit
- ``--quiet``, ``-q`` - decrease verbosity
.. option:: --verbose, -v
increase verbosity
.. option:: --quiet, -q
decrease verbosity
A full command consists of one :option:`DEVICE_CLASS` and one action. If no action is given, list is implied. :option:`DEVICE_CLASS` however is required.
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**::
**SYNOPSIS**: ``qvm-device DEVICE_CLASS {action} [action-specific arguments] [options]``
.. _actions-1:
qvm-device DEVICE_CLASS {action} [action-specific arguments] [options]
Actions
-------
Actions are applicable to every DEVICE_CLASS and expose some additional options.
Actions are applicable to every :option:`DEVICE_CLASS` and expose some additional options.
Listing Devices
^^^^^^^^^^^^^^^
The :option:`list` action lists known devices in the system. :option:`list` accepts VM-names to narrow down listed devices. Devices available in, as well as attached to the named VMs will be listed.
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.
:option:`qvm-device list` takes two options:
``list`` accepts two options:
.. program:: qvm-device list
- ``--all`` - equivalent to specifying every VM name after ``list``. No VM-name implies ``--all``.
.. option:: --all
- ``--exclude`` - exclude VMs from ``--all``. Requires ``--all``.
equivalent to specifying every VM name after :option:`qvm-device list`. No VM-name implies :option:`--all`.
.. option:: --exclude
exclude VMs from :option:`--all`. Requires :option:`--all`.
**SYNOPSIS** ``qvm-device DEVICE_CLASS {list|ls|l} [--all [--exclude VM [VM [...]]] | VM [VM [...]]]``
**SYNOPSIS**::
qvm-device DEVICE_CLASS {list|ls|l} [--all [--exclude VM [VM [...]]] | VM [VM [...]]]
Attaching Devices
^^^^^^^^^^^^^^^^^
The :option:`qvm-device attach` action assigns an exposed device to a VM. This makes the device available in the VM it’s attached to. **Required argument are**:
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)
.. program:: qvm-device attach
``attach`` accepts two options:
.. option:: targetVM
- ``--persistent`` - attach device on targetVM-boot. If the device is unavailable (physically missing or sourceVM not started), booting the targetVM fails.
.. option:: sourceVM:deviceID
- ``--option``, ``-o`` - set additional options specific to DEVICE_CLASS.
:option:`sourceVM:deviceID` can be determined from :option:`qvm-device list` output
:option:`qvm-device attach` accepts two options:
.. option:: --persistent
attach device on :option:`targetVM`-boot. If the device is unavailable (physically missing or ``sourceVM`` not started), booting the :option:`targetVM` fails.
.. option:: --option, -o
set additional options specific to :option:`DEVICE_CLASS <qvm-device DEVICE_CLASS>`.
**SYNOPSIS**::
**SYNOPSIS** ``qvm-device DEVICE_CLASS {attach|at|a} targetVM sourceVM:deviceID [options]``
qvm-device DEVICE_CLASS {attach|at|a} targetVM sourceVM:deviceID [options]
Detaching Devices
^^^^^^^^^^^^^^^^^
The :option:`qvm-device detach` action removes an assigned device from a :option:`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!
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 :option:`sourceVM:deviceID` combination is given, *all devices of that* `DEVICE_CLASS <qvm-device DEVICE_CLASS>` will be detached.
If no specific ``sourceVM:deviceID`` combination is given, *all devices of that DEVICE_CLASS will be detached.*
:option:`qvm-device detach` accepts no options.
``detach`` accepts no options.
**SYNOPSIS**::
**SYNOPSIS** ``qvm-device DEVICE_CLASS {detach|dt|d} targetVM [sourceVM:deviceID]``
.. |SD card and thumbdrive| image:: /attachment/doc/media-removable.png
qvm-device DEVICE_CLASS {detach|dt|d} targetVM [sourceVM:deviceID]
.. |eject icon| image:: /attachment/doc/media-eject.png

80
user/how-to-guides/how-to-use-disposables.rst
View file

@ -2,29 +2,32 @@
How to use disposables
======================
A :ref:`disposable <user/reference/glossary:disposable>` is a lightweight :ref:`qube <user/reference/glossary:qube>` that can be created quickly and will self-destruct when closed. Disposables are usually created in order to host a single application, like a viewer, editor, or web browser.
From inside an app qube, choosing the ``Open in disposable`` option on a file will launch a disposable for just that file. Changes made to a file opened in a disposable are passed back to the originating qube. This means that you can safely work with untrusted files without risk of compromising your other qubes. Disposables can be launched either directly from dom0’s app menu or terminal window, or from within app qubes. Disposables are generated with names like ``disp####``, where ``####`` is random number.
|disposablevm-example.png|
.. figure:: /attachment/doc/disposablevm-example.png
This diagram provides a general example of how disposables can be used to safely open untrusted links and attachments in disposables. See `this article <https://blog.invisiblethings.org/2010/06/01/disposable-vms.html>`__ for more on why one would want to use a disposable.
Example of how disposables can be used to safely open untrusted links and attachments in disposables
In a *work-email* qube, the user clicks on a link. This link is opened in a new disposable through qrexec protocol (``qubes.OpenURL``). The link appears to be some kind of malware that infects the disposable qube but it is harmless as this qube is then destroyed.
In that same *work-email* qube, the user now opens a PDF attachment. Using the qrexec protocol (``qubes.OpenInVM``), the PDF is opened as a legitimate file in a new disposable qube. The disposable is destroyed at the end of the process.
See `this article <https://blog.invisiblethings.org/2010/06/01/disposable-vms.html>`__ for more on why one would want to use a disposable.
Named disposables and disposable templates
------------------------------------------
There is a difference between :ref:`named disposable qubes <user/reference/glossary:named disposable>` and :ref:`disposable templates <user/reference/glossary:disposable template>`.
In a default QubesOS Installation, you would probably use the ‘whonix-ws-16-dvm’ disposable template to, for example, browse the Tor network with an disposable qube. Every time you start an application using this disposable template, a new disposable qube - named ``dispX`` (where X is a random number) starts. If you close the application window, the ``dispX`` qube shuts down and vanishes from your system. That is how disposable templates are used.
In a default QubesOS Installation, you would probably use the ``whonix-ws-16-dvm`` disposable template to, for example, browse the Tor network with an disposable qube. Every time you start an application using this disposable template, a new disposable qube - named ``dispX`` (where ``X`` is a random number) starts. If you close the application window, the ``dispX`` qube shuts down and vanishes from your system. That is how disposable templates are used.
Named disposables are also built upon disposable templates, but they have a fixed name. The named disposable seems to behave like an ordinary app qube - every application you open will start in the same qube, and you need to manually shutdown the qube. But when you shutdown *any changes you made in the named disposable will be lost*. Except for this non-persistance, they feel like usual app qubes.
How to create disposable templates
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
First, you need to create an app qube. You can run it normally, set up any necessary settings (like browser settings) you wish to be applied to every disposable qube ran from this template. Next, go to ‘Qube Settings’ of the app qube, set it as a *Disposable template* in the *Advanced* section and apply the change.
In Qubes 4.1, the entry in the Application menu is split into ‘Disposable’ and ‘Template (disp)’. The settings for the disposable can be changed under **’Application Menu -> Template (disp) -> Template: Qubes Settings**
@ -34,7 +37,6 @@ In Qubes 4.2, the qube will now appear in the menu as a disposable template (in
How to create named disposables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In Qubes 4.1: named disposables can be created under **Application Menu -> Create Qubes VM**, set the qube type to be *DisposableVM*.
In Qubes 4.2: named disposables can be created by **Application Menu -> Settings -> Qubes Settings -> Create New Qube**. Set the qube type to **Named disposable**.
@ -42,13 +44,11 @@ In Qubes 4.2: named disposables can be created by **Application Menu -> Settings
Security
--------
If a :ref:`disposable template <user/reference/glossary:disposable template>` becomes compromised, then any disposable based on that disposable template could be compromised. In particular, the *default* disposable template is important because it is used by the “Open in disposable” feature. This means that it will have access to everything that you open with this feature. For this reason, it is strongly recommended that you base the default disposable template on a trusted template.
Disposables and Local Forensics
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
At this time, disposables should not be relied upon to circumvent local forensics, as they do not run entirely in RAM. For details, see `this thread <https://groups.google.com/d/topic/qubes-devel/QwL5PjqPs-4/discussion>`__.
When it is essential to avoid leaving any trace, consider using `Tails <https://tails.boum.org/>`__.
@ -56,7 +56,6 @@ When it is essential to avoid leaving any trace, consider using `Tails <https://
Disposables and Networking
--------------------------
Similarly to how app qubes are based on their underlying :ref:`template <user/reference/glossary:template>`, disposables are based on their underlying :ref:`disposable template <user/reference/glossary:disposable template>`. R4.0 introduces the concept of multiple disposable templates, whereas R3.2 was limited to only one.
On a fresh installation of Qubes, the default disposable template is called ``fedora-X-dvm`` or ``debian-X-dvm`` (where ``X`` is a release number). If you have included the Whonix option in your install, there will also be a ``whonix-ws-dvm`` disposable template available for your use.
@ -67,8 +66,6 @@ You can set any app qube to have the ability to act as a disposable template wit
qvm-prefs <APP_QUBE> template_for_dispvms True
The default system wide disposable template can be changed with ``qubes-prefs default_dispvm``. By combining the two, choosing ``Open in disposable`` from inside an app qube will open the document in a disposable based on the default disposable template you specified.
You can change this behavior for individual qubes: in the Application Menu, open Qube Settings for the qube in question and go to the “Advanced” tab. Here you can edit the “Default disposable” setting to specify which disposable template will be used to launch disposables from that qube. This can also be changed from the command line with:
@ -77,77 +74,59 @@ You can change this behavior for individual qubes: in the Application Menu, open
qvm-prefs <QUBE> default_dispvm <DISPOSABLE_TEMPLATE>
For example, ``anon-whonix`` has been set to use ``whonix-ws-dvm`` as its ``default_dispvm``, instead of the system default. You can even set an app qube that has also been configured as a disposable template to use itself, so disposables launched from within the app qube/disposable template would inherit the same settings.
Network and firewall settings for disposable templates can be set as they can for a normal qube. By default a disposable will inherit the network and firewall settings of the disposable template on which it is based. This is a change in behavior from R3.2, where disposables would inherit the settings of the app qube from which they were launched. Therefore, launching a disposable from an app qube will result in it using the network/firewall settings of the disposable template on which it is based. For example, if an app qube uses sys-net as its net qube, but the default system disposable uses sys-whonix, any disposable launched from this app qube will have sys-whonix as its net qube.
**Warning:** The opposite is also true. This means if you have changed ``anon-whonix``’s ``default_dispvm`` to use the system default, and the system default disposable uses sys-net, launching a disposable from inside ``anon-whonix`` will result in the disposable using ``sys-net``.
.. warning:: The opposite is also true. This means if you have changed ``anon-whonix``’s ``default_dispvm`` to use the system default, and the system default disposable uses sys-net, launching a disposable from inside ``anon-whonix`` will result in the disposable using ``sys-net``.
A disposable launched from the app menu inherits the net qube and firewall settings of the disposable template on which it is based. Note that changing the net qube setting for the system default disposable template *does* affect the net qube of disposables launched from the app menu. Different disposable templates with individual net qube settings can be added to the app menu.
**Important Notes:** Some disposable templates will automatically create a menu item to launch a disposable. If you do not see an entry and want to add one, please use the command:
.. important:: Some disposable templates will automatically create a menu item to launch a disposable. If you do not see an entry and want to add one, please use the command:
.. code:: bash
qvm-features <DISPOSABLE_TEMPLATE> appmenus-dispvm 1
To launch a disposable template from the command line, execute the following command in dom0:
.. code:: bash
qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --service qubes.StartApp+<APPLICATION>
Opening a file in a disposable via GUI
--------------------------------------
In an app qube’s file manager, right click on the file you wish to open in a disposable, then choose “View in disposable” or “Edit in disposable”. Wait a few seconds and the default application for this file type should appear displaying the file content. This app is running in its own dedicated qube – a disposable created for the purpose of viewing or editing this very file. Once you close the viewing application the whole disposable will be destroyed. If you have edited the file and saved the changes, the changed file will be saved back to the original app qube, overwriting the original.
.. figure:: /attachment/doc/r4.0-open-in-dispvm-1.png
:alt: r4.0-open-in-dispvm-1.png
.. figure:: /attachment/doc/r4.0-open-in-dispvm-2.png
:alt: r4.0-open-in-dispvm-2.png
Opening a fresh web browser instance in a new disposable
--------------------------------------------------------
Sometimes it is desirable to open an instance of Firefox within a new fresh disposable. This can be done easily using the app menu: just go to **Application Menu -> Disposable -> Disposable: Firefox web browser**. Wait a few seconds until a web browser starts. Once you close the viewing application the whole disposable will be destroyed.
.. figure:: /attachment/doc/r4.0-open-in-dispvm-3.png
:alt: r4.0-open-in-dispvm-3.png
Opening a file in a disposable via command line (from app qube)
---------------------------------------------------------------
Use the ``qvm-open-in-dvm`` command from a terminal in your app qube:
.. code:: bash
.. code:: console
[user@work-pub ~]$ qvm-open-in-dvm Downloads/apple-sandbox.pdf
Note that the ``qvm-open-in-dvm`` process will not exit until you close the application in the disposable.
Making a particular application open everything in a disposable
---------------------------------------------------------------
You can use the ``qvm-service`` command or the services GUI to cause an application in a qube to open files and URLs in a disposable. To do this, enable a service named ``app-dispvm.X`` in that qube, where ``X`` is the application ID. For instance, to have Thunderbird open all attachments in a disposable, enable the ``app-dispvm.thunderbird`` service.
This feature is currently somewhat experimental, and only works for Linux qubes. It is known to work with Thunderbird and Wire, but it may fail to work with some applications that do not honor all XDG environment variables. If the feature does not work for you, please file a bug report.
@ -155,7 +134,6 @@ This feature is currently somewhat experimental, and only works for Linux qubes.
Opening particular types of files in a disposable
-------------------------------------------------
You can set ``qvm-open-in-dvm.desktop`` as the handler for a given MIME type. This will cause all files of that type to open in a disposable. This works in disposable templates too, but be careful: if your disposable template is set to use ``qvm-open-in-dvm.desktop`` to open a certain kind of file, every disposable based on it will be as well. If the disposable template is its own default disposable template (as is often the case), this will result in a loop: ``qvm-open-in-dvm`` will execute ``qubes.OpenURL`` in a new disposable, but that will in turn execute ``qvm-open-in-dvm``. The cycle will repeat until no new disposables can be created, most likely because your system has run out of memory.
This will *not* override the internal handling of PDF documents in Web browsers. This is typically okay, though: in-browser PDF viewers have a fairly good security record, especially when compared to non-browser PDF viewers. In particular, the attack surface of PDF viewing in Firefox is usually less than that of viewing an ordinary Web page.
@ -163,57 +141,45 @@ This will *not* override the internal handling of PDF documents in Web browsers.
Starting an arbitrary program in a disposable from an app qube
--------------------------------------------------------------
Sometimes it can be useful to start an arbitrary program in a disposable. The disposable will stay running so long as the process which started the disposable has not exited. Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details in `Github issue #2581 <https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009>`__). Starting an arbitrary program can be done from an app qube by running
Sometimes it can be useful to start an arbitrary program in a disposable. The disposable will stay running so long as the process which started the disposable has not exited. Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details `here <https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009>`__). Starting an arbitrary program can be done from an app qube by running
.. code:: bash
.. code:: console
[user@vault ~]$ qvm-run '@dispvm' xterm
The created disposable can be accessed via other tools (such as ``qvm-copy-to-vm``) using its ``disp####`` name as shown in the Qubes Manager or ``qvm-ls``.
Starting an arbitrary application in a disposable via command line from dom0
----------------------------------------------------------------------------
The Application Launcher has shortcuts for opening a terminal and a web browser in dedicated disposables, since these are very common tasks. The disposable will stay running so long as the process which started the disposable has not exited. Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details `here <https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009>`__). It is possible to start an arbitrary application in a disposable directly from dom0 by running:
.. code:: bash
$ qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --service qubes.StartApp+xterm
.. code:: console
[user@dom0 ~]$ qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --service qubes.StartApp+xterm
The label color will be inherited from ``<DISPOSABLE_TEMPLATE>``. (The disposable Application Launcher shortcut used for starting programs runs a very similar command to the one above.)
Opening a link in a disposable based on a non-default disposable template from a qube
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Suppose that the default disposable template for your ``email`` qube has no networking (e.g., so that untrusted attachments can’t phone home). However, sometimes you want to open email links in disposables. Obviously, you can’t use the default disposable template, since it has no networking, so you need to be able to specify a different disposable template. You can do that with this command from the ``email`` qube (as long as your RPC policies allow it):
.. code:: bash
$ qvm-open-in-vm @dispvm:<ONLINE_DISPOSABLE_TEMPLATE> https://www.qubes-os.org
.. code:: console
[user@email ~]$ qvm-open-in-vm @dispvm:<ONLINE_DISPOSABLE_TEMPLATE> https://www.qubes-os.org
This will create a new disposable based on ``<ONLINE_DISPOSABLE_TEMPLATE>``, open the default web browser in that disposable, and navigate to ``https://www.qubes-os.org``.
Example of RPC policies to allow this behavior
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In dom0, add the following line at the beginning of the file ``/etc/qubes-rpc/policy/qubes.OpenURL``
.. code:: bash
.. code::
@anyvm @dispvm:<ONLINE_DISPOSABLE_TEMPLATE> allow
This line means:
- FROM: Any qube
@ -222,17 +188,13 @@ This line means:
- WHAT: Allow sending an “Open URL” request
In other words, any qube will be allowed to create a new disposable based on ``<ONLINE_DISPOSABLE_TEMPLATE>`` and open a URL inside of that disposable.
More information about RPC policies for disposables can be found :ref:`here <developer/services/qrexec:qubes rpc administration>`.
More information about RPC policies for disposables can be found in :ref:`developer/services/qrexec:qubes rpc administration`.
Customizing disposables
-----------------------
You can change the template used to generate the disposables, and change settings used in the disposable savefile. These changes will be reflected in every new disposable based on that template. Full instructions can be found in :doc:`/user/advanced-topics/disposable-customization`.
You can change the template used to generate the disposables, and change settings used in the disposable savefile. These changes will be reflected in every new disposable based on that template. Full instructions can be found :doc:`here </user/advanced-topics/disposable-customization>`.
.. |disposablevm-example.png| image:: /attachment/doc/disposablevm-example.png

7
user/how-to-guides/how-to-use-optical-discs.rst
View file

@ -2,7 +2,6 @@
How to use optical discs
========================
Passthrough reading and recording (a.k.a., “burning”) are not supported by Qubes OS. This is not a limitation of Xen, which provides scsiback and scsifront drivers, but of Qubes OS. It will be fixed in the future.
Currently, the only options for reading and recording optical discs (e.g., CDs, DVDs, BRDs) in Qubes are:
@ -11,8 +10,8 @@ Currently, the only options for reading and recording optical discs (e.g., CDs,
2. Attach a SATA optical drive to a secondary SATA controller, then assign this secondary SATA controller to a VM.
3. Use a SATA optical drive attached to dom0. (**Caution:** This option is `potentially dangerous <https://forum.qubes-os.org/t/19075#dom0-precautions>`__.)
3. Use a SATA optical drive attached to dom0.
.. warning:: This option is `potentially dangerous <https://forum.qubes-os.org/t/19075#dom0-precautions>`__.
To access an optical disc via USB follow the :ref:`typical procedure for attaching a USB device <user/how-to-guides/how-to-use-usb-devices:with the command line tool>`, then check with the **Qubes Devices** widget to see what device in the target qube the USB optical drive was attached to. Typically this would be ``sr0``. For example, if ``sys-usb`` has device ``3-2`` attached to the ``work`` qube’s ``sr0``, you would mount it with ``mount /dev/sr0 /mnt/removable``. You could also write to a disc with ``wodim -v dev=/dev/sr0 -eject /home/user/Qubes.iso``.
To access an optical disc via USB follow the :ref:`typical procedure for attaching a USB device <attaching-and-detaching-a-usb-device>`, then check with the **Qubes Devices** widget to see what device in the target qube the USB optical drive was attached to. Typically this would be ``sr0``. For example, if ``sys-usb`` has device ``3-2`` attached to the ``work`` qube’s ``sr0``, you would mount it with ``mount /dev/sr0 /mnt/removable``. You could also write to a disc with ``wodim -v dev=/dev/sr0 -eject /home/user/Qubes.iso``.

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

@ -2,39 +2,34 @@
How to use PCI devices
======================
*This page is part of* :doc:`device handling in qubes </user/how-to-guides/how-to-use-devices>` *.*
**Warning:** Only dom0 exposes PCI devices. Some of them are strictly required in dom0 (e.g., the host bridge). You may end up with an unusable system by attaching the wrong PCI device to a VM. PCI passthrough should be safe by default, but non-default options may be required. Please make sure you carefully read and understand the :ref:`security considerations <user/security-in-qubes/device-handling-security:pci security>` before deviating from default behavior.
.. warning:: Only dom0 exposes PCI devices. Some of them are strictly required in dom0 (e.g., the host bridge). You may end up with an unusable system by attaching the wrong PCI device to a VM. PCI passthrough should be safe by default, but non-default options may be required. Please make sure you carefully read and understand the :ref:`security considerations <user/security-in-qubes/device-handling-security:pci security>` before deviating from default behavior.
Introduction
------------
Unlike other devices (:doc:`USB </user/how-to-guides/how-to-use-usb-devices>`, :doc:`block </user/how-to-guides/how-to-use-block-storage-devices>`, mic), PCI devices need to be attached on VM-bootup. Similar to how you can’t attach a new sound-card after your computer booted (and expect it to work properly), attaching PCI devices to already booted VMs isn’t supported. Moreover, PCI devices can be attached only to VMs running in certain virtualization modes. See :ref:`FAQ: Which virtualization modes do VMs use? <introduction/faq:which virtualization modes do vms use?>`
The Qubes installer attaches all network class controllers to ``sys-net`` and all USB controllers to ``sys-usb`` by default, if you chose to create the network and USB qube during install. While this covers most use cases, there are some occasions when you may want to manually attach one NIC to ``sys-net`` and another to a custom NetVM, or have some other type of PCI controller you want to manually attach.
Some devices expose multiple functions with distinct BDF-numbers. Limits imposed by the PC and VT-d architectures may require all functions belonging to the same device to be attached to the same VM. This requirement can be dropped with the ``no-strict-reset`` option during attachment, bearing in mind the aforementioned :ref:`security considerations <user/security-in-qubes/device-handling-security:pci security>`. In the steps below, you can tell if this is needed if you see the BDF for the same device listed multiple times with only the number after the “.” changing.
Some devices expose multiple functions with distinct BDF-numbers. Limits imposed by the PC and VT-d architectures may require all functions belonging to the same device to be attached to the same VM. This requirement can be dropped with the :option:`no-strict-reset` option during attachment, bearing in mind the aforementioned :ref:`security considerations <user/security-in-qubes/device-handling-security:pci security>`. In the steps below, you can tell if this is needed if you see the BDF for the same device listed multiple times with only the number after the “.” changing.
While PCI device can only be used by one powered on VM at a time, it *is* possible to *assign* the same device to more than one VM at a time. This means that you can use the device in one VM, shut that VM down, start up a different VM (to which the same device is now attached), then use the device in that VM. This can be useful if, for example, you have only one USB controller, but you have multiple security domains which all require the use of different USB devices.
Attaching Devices Using the GUI
-------------------------------
The qube settings for a VM offers the “Devices”-tab. There you can attach PCI-devices to a qube.
1. To reach the settings of any qube either
- Press Alt+F3 to open the application finder, type in the VM name, select the |appmenu| ``[VM-name]: Qube Settings`` menu entry and press enter or click ``Launch``!
- Press :kbd:`Alt+F3` to open the application finder, type in the VM name, select the |appmenu| ``[VM-name]: Qube Settings`` menu entry and press enter or click ``Launch``!
- Select the VM in Qube Manager and click the settings-button or right-click the VM and select ``Qube settings``.
- Click the Domain Manager, hover the VM you want to attach a device to and select “settings” in the additional menu. (only running VMs!)
2. Select the “Devices” tab on the top bar.
3. Select a device you want to attach to the qube and click the single arrow right! (``>``)
@ -43,13 +38,10 @@ The qube settings for a VM offers the “Devices”-tab. There you can attach PC
5. In case it doesn’t work out, first try disabling memory-balancing in the settings (“Advanced” tab). If that doesn’t help, read on to learn how to disable the strict reset requirement!
``qvm-pci`` Usage
-----------------
The ``qvm-pci`` tool allows PCI attachment and detachment. It’s a shortcut for :ref:`qvm-device pci <user/how-to-guides/how-to-use-devices:general qubes device widget behavior and handling>`
The ``qvm-pci`` tool allows PCI attachment and detachment. It’s a shortcut for :option:`qvm-device pci`.
To figure out what device to attach, first list the available PCI devices by running (as user) in dom0:
@ -57,17 +49,13 @@ To figure out what device to attach, first list the available PCI devices by run
qvm-pci
This will show you the ``backend:BDF`` (Bus_Device.Function) address of each PCI device. It will look something like ``dom0:00_1a.0``. Once you’ve found the address of the device you want to attach, then attach it like this:
.. code:: bash
qvm-pci attach targetVM sourceVM:[BDF] --persistent
Since PCI devices have to be attached on bootup, attaching has to happen with the ``--persistant`` option.
Since PCI devices have to be attached on bootup, attaching has to happen with the :option:`--persistent <qvm-device attach --persistent>` option.
For example, if ``00_1a.0`` is the BDF of the device you want to attach to the “work” domain, you would do this:
@ -75,25 +63,19 @@ For example, if ``00_1a.0`` is the BDF of the device you want to attach to the
qvm-pci attach work dom0:00_1a.0 --persistent
Possible Issues
---------------
Visit the :doc:`PCI Troubleshooting guide </user/troubleshooting/pci-troubleshooting>` to see issues that may arise due to PCI devices and how to troubleshoot them.
Additional Attach Options
-------------------------
Attaching a PCI device through the commandline offers additional options, specifiable via the ``--option``/``-o`` option. (Yes, confusing wording, there’s an `issue for that <https://github.com/QubesOS/qubes-issues/issues/4530>`__.)
``qvm-pci`` exposes two additional options. Both are intended to fix device or driver specific issues, but both come with :ref:`heavy security implications <user/security-in-qubes/device-handling-security:pci security>`! **Make sure you understand them before continuing!**
no-strict-reset
^^^^^^^^^^^^^^^
.. option:: no-strict-reset
Do not require PCI device to be reset before attaching it to another VM. This may leak usage data even without malicious intent!
@ -103,11 +85,7 @@ usage example:
qvm-pci a work dom0:00_1a.0 --persistent -o no-strict-reset=true
permissive
^^^^^^^^^^
.. option:: permissive
Allow write access to full PCI config space instead of whitelisted registers. This increases attack surface and possibility of `side channel attacks <https://en.wikipedia.org/wiki/Side-channel_attack>`__.
@ -117,12 +95,9 @@ usage example:
qvm-pci a work dom0:00_1a.0 --persistent -o permissive=true
Bringing PCI Devices Back to dom0
---------------------------------
By default, when a device is detached from a VM (or when a VM with an attached PCI device is shut down), the device is *not* automatically attached back to dom0.
This is an intended feature.
@ -133,8 +108,6 @@ In order to re-enable the device in dom0, either:
- Reboot the physical machine. (Best practice)
or
- Go to the sysfs (``/sys/bus/pci``), find the right device, detach it from the pciback driver, and attach it back to the original driver. Replace ``<BDF>`` with your full device, for example ``0000:00:1c.2``:
@ -146,10 +119,6 @@ or
MOD=`modprobe -R $MODALIAS | head -n 1`
echo <BDF> > /sys/bus/pci/drivers/$MOD/bind
It is **strongly discouraged to reattach PCI devices to dom0**, especially if they don’t support resetting!
.. |appmenu| image:: /attachment/doc/qubes-appmenu-select.png

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

@ -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,19 +20,23 @@ 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
^^^^^^^^^^^^^^^^^^^^^^^^
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,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
@ -55,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
@ -67,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
@ -81,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.
@ -106,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.
@ -140,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.
@ -160,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.
@ -193,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``
@ -204,8 +181,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

2
user/templates/templates.rst
View file

@ -71,7 +71,7 @@ By installing these templates, you are trusting not only the Qubes developers an
- :doc:`Gentoo Minimal </user/templates/minimal-templates>`
- :doc:`CentOS* <https://forum.qubes-os.org/t/19006>`
- `CentOS* <https://forum.qubes-os.org/t/19006>`__