mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2024-12-24 14:59:25 -05:00
219 lines
7.2 KiB
ReStructuredText
219 lines
7.2 KiB
ReStructuredText
|
======================
|
|||
|
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.
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
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”!
|
|||
|
|
|||
|
- 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! (``>``)
|
|||
|
|
|||
|
4. You’re done. If everything worked out, once the qube boots (or
|
|||
|
reboots if it’s running) it will start with the pci device attached.
|
|||
|
|
|||
|
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>`
|
|||
|
|
|||
|
To figure out what device to attach, first list the available PCI
|
|||
|
devices by running (as user) in dom0:
|
|||
|
|
|||
|
.. code:: bash
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
For example, if ``00_1a.0`` is the BDF of the device you want to attach
|
|||
|
to the “work” domain, you would do this:
|
|||
|
|
|||
|
.. code:: bash
|
|||
|
|
|||
|
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
|
|||
|
^^^^^^^^^^^^^^^
|
|||
|
|
|||
|
|
|||
|
Do not require PCI device to be reset before attaching it to another VM.
|
|||
|
This may leak usage data even without malicious intent!
|
|||
|
|
|||
|
usage example:
|
|||
|
|
|||
|
.. code:: bash
|
|||
|
|
|||
|
qvm-pci a work dom0:00_1a.0 --persistent -o no-strict-reset=true
|
|||
|
|
|||
|
|
|||
|
|
|||
|
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>`__.
|
|||
|
|
|||
|
usage example:
|
|||
|
|
|||
|
.. code:: bash
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
A device which was previously attached to a VM less trusted than dom0
|
|||
|
(which, in Qubes, is *all* of them) could attack dom0 if it were
|
|||
|
automatically reattached there.
|
|||
|
|
|||
|
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``:
|
|||
|
|
|||
|
.. code:: bash
|
|||
|
|
|||
|
echo <BDF> > /sys/bus/pci/drivers/pciback/unbind
|
|||
|
MODALIAS=`cat /sys/bus/pci/devices/<BDF>/modalias`
|
|||
|
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
|