mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-12-09 21:16:20 -05:00
Improve device handling rework content
- Remove deprecated 3.2 pages - Normalize names, text, formatting, and URLs - Fix Markdown syntax - Miscellanous cleanups and improvements
This commit is contained in:
Andrew David Wong
parent
08d83f6e22
commit
328ce89659
12 changed files with 208 additions and 445 deletions
|
|
@ -1,112 +0,0 @@
|
|||
---
|
||||
layout: doc
|
||||
title: Assigning Devices in R3.2
|
||||
permalink: /doc/assigning-devices/
|
||||
redirect_from:
|
||||
- /en/doc/assigning-devices/
|
||||
- /doc/AssigningDevices/
|
||||
- /wiki/AssigningDevices/
|
||||
---
|
||||
|
||||
Assigning Devices to VMs in R3.2
|
||||
================================
|
||||
(In case you were looking for the [R4.0 documentation](/doc/pci-devices/).)
|
||||
|
||||
Sometimes you may need to assign an entire PCI or PCI Express device directly to a qube.
|
||||
This is also known as PCI passthrough.
|
||||
The Qubes installer does this by default for `sys-net` (assigning all network class controllers), as well as `sys-usb` (assigning all USB controllers) if you chose to create the USB qube during install.
|
||||
While this covers most use cases, there are some occasions when you may want to manually assign one NIC to `sys-net` and another to a custom NetVM, or have some other type of PCI controller you want to manually assign.
|
||||
|
||||
Note that one can only assign full PCI or PCI Express devices by default.
|
||||
This limit is imposed by the PC and VT-d architectures.
|
||||
This means if a PCI device has multiple functions, all instances of it need to be assigned to the same qube unless you have disabled the strict requirement for FLR with the `no-strict-reset` (R4.0) or `pci_strictreset` (R3.2) option.
|
||||
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 also assigned), 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.
|
||||
|
||||
Using the Command Line
|
||||
------------------------
|
||||
|
||||
In order to assign a whole PCI(e) device to a VM, one should use the `qvm-pci` tool.
|
||||
First, list the available PCI devices:
|
||||
|
||||
~~~
|
||||
lspci
|
||||
~~~
|
||||
|
||||
This will show you the BDF address of each PCI device.
|
||||
It will look something like `00:1a.0`.
|
||||
Once you've found the BDF address of the device you want to assign, then attach it like so:
|
||||
|
||||
~~~
|
||||
qvm-pci -a <vmname> <bdf>
|
||||
~~~
|
||||
|
||||
For example, if `00:1a.0` is the BDF of the device you want to assign to the "personal" domain, you would do this:
|
||||
|
||||
~~~
|
||||
qvm-pci -a personal 00:1a.0
|
||||
~~~
|
||||
|
||||
Using Qubes Manager
|
||||
-------------------
|
||||
|
||||
The above steps can also be done in Qubes Manager.
|
||||
Simply go into the VM settings of your desired VM, then go to the "Devices" tab.
|
||||
This will show you a list of available devices, which you can select to be assigned to that VM.
|
||||
|
||||
|
||||
Finding the right USB controller
|
||||
--------------------------------
|
||||
This was moved to the [current documentation][finding controller].
|
||||
|
||||
Possible issues
|
||||
---------------
|
||||
Please refer to the [current documentation][possible issues] for an issue description and carefully read the [security implications]!
|
||||
Return here for a guide on how to enable permissive mode and disable strict reset!
|
||||
|
||||
Enabling permissive mode
|
||||
------------------------
|
||||
|
||||
Permissive mode is enabled system wide per device.
|
||||
|
||||
Create `/etc/systemd/system/qubes-pre-netvm.service`:
|
||||
|
||||
~~~
|
||||
[Unit]
|
||||
Description=Netvm fixup
|
||||
Before=qubes-netvm.service
|
||||
|
||||
[Service]
|
||||
ExecStart=/bin/sh -c 'echo 0000:04:00.0 > /sys/bus/pci/drivers/pciback/permissive'
|
||||
Type=oneshot
|
||||
RemainAfterExit=yes
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
~~~
|
||||
|
||||
Then enable it with `systemctl enable qubes-pre-netvm.service`
|
||||
|
||||
The strict reset option is set for all devices attached to a VM with:
|
||||
|
||||
```
|
||||
qvm-prefs usbVM -s pci_strictreset false
|
||||
```
|
||||
|
||||
**Note** again that in most cases you should not need either of these options set.
|
||||
Only set one or more of them as required to get your device to function, or replace the device with one that functions properly with Qubes.
|
||||
|
||||
Bringing PCI device back to dom0
|
||||
--------------------------------
|
||||
This was moved to the [current documentation][bring back devices].
|
||||
|
||||
|
||||
|
||||
[usb]: /doc/usb/
|
||||
[finding controller]: /doc/usb-devices/#finding-the-right-usb-controller
|
||||
[possible issues]: /doc/pci-devices/#possible-issues
|
||||
[security implications]: /doc/device-considerations/#pci-security
|
||||
[bring back devices]: /doc/pci-devices/#bringing-pci-devices-back-to-dom0
|
||||
|
|
@ -1,17 +1,23 @@
|
|||
---
|
||||
layout: doc
|
||||
title: USB Qube HowTo
|
||||
permalink: /doc/usb-qube-howto/
|
||||
title: USB Qubes
|
||||
permalink: /doc/usb-qubes/
|
||||
redirect_from:
|
||||
- /doc/usbvm/
|
||||
- /en/doc/usbvm/
|
||||
- /doc/USBVM/
|
||||
- /wiki/USBVM/
|
||||
- /doc/sys-usb/
|
||||
---
|
||||
|
||||
USB Qube HowTo
|
||||
==============
|
||||
# USB Qubes #
|
||||
|
||||
If during installation you enabled the creation of a USB-qube, your system should be setup already and none of the mentioned steps here should be necessary. (Unless you want to [remove your USB-qube].) If for any reason no USB-qube was created during installation, this guide will show you how to do so.
|
||||
|
||||
**Caution:** If you want to use a USB-keyboard, please beware of the possibility to lock yourself out! To avoid this problem [enable your keyboard for login]!
|
||||
|
||||
Creating and Using a USB qube
|
||||
-----------------------------
|
||||
|
||||
## Creating and Using a USB qube ##
|
||||
|
||||
**Warning:** This has the potential to prevent you from connecting a keyboard to Qubes via USB.
|
||||
There are problems with doing this in an encrypted install (LUKS).
|
||||
|
|
@ -48,8 +54,7 @@ Alternatively, you can create a USB qube manually as follows:
|
|||
If the USB qube will not start, please have a look at the [faq].
|
||||
|
||||
|
||||
Enable a USB keyboard for login
|
||||
-------------------------------
|
||||
## Enable a USB keyboard for login ##
|
||||
|
||||
**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding!
|
||||
|
||||
|
|
@ -57,6 +62,7 @@ If you use USB keyboard, automatic USB qube creation during installation is disa
|
|||
Additional steps are required to avoid locking you out from the system.
|
||||
Those steps are not performed by default, because of risk explained in [Security Warning about USB Input Devices].
|
||||
|
||||
|
||||
### Automatic setup ###
|
||||
R4.0 only! R3.2 users please read the [manual setup] below!
|
||||
|
||||
|
|
@ -72,6 +78,7 @@ To undo these changes, please follow the section on [**Removing a USB qube**][re
|
|||
|
||||
If you wish to perform only a subset of this configuration (for example do not enable USB keyboard during boot), see manual instructions below.
|
||||
|
||||
|
||||
### Manual setup ###
|
||||
|
||||
In order to use a USB keyboard, you must first attach it to a USB qube, then give that qube permission to pass keyboard input to dom0.
|
||||
|
|
@ -96,8 +103,8 @@ For a confirmation dialog each time the USB keyboard is connected, *which will e
|
|||
Additionally, if you want to use USB keyboard to enter LUKS passphrase, it is incompatible with [hiding USB controllers from dom0].
|
||||
You need to revert that procedure (remove `rd.qubes.hide_all_usb` option from files mentioned there) and employ alternative protection during system boot - disconnect other devices during startup.
|
||||
|
||||
Auto Enabling A USB Mouse
|
||||
----------------------
|
||||
|
||||
## Auto Enabling A USB Mouse ##
|
||||
|
||||
**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding.
|
||||
|
||||
|
|
@ -120,8 +127,7 @@ In case you are absolutely sure you do not want to confirm mouse access from `sy
|
|||
(Change `sys-usb` to your desired USB qube.)
|
||||
|
||||
|
||||
How to hide all USB controllers from dom0
|
||||
-----------------------------------------
|
||||
## How to hide all USB controllers from dom0 ##
|
||||
|
||||
(Note: Beginning with R3.2, `rd.qubes.hide_all_usb` is set automatically if you opt to create a USB qube during installation.
|
||||
This also occurs automatically if you choose to [create a USB qube] using the `qubesctl` method, which is the
|
||||
|
|
@ -162,8 +168,7 @@ The procedure to hide all USB controllers from dom0 is as follows:
|
|||
5. Reboot.
|
||||
|
||||
|
||||
Removing a USB qube
|
||||
-------------------
|
||||
## Removing a USB qube ##
|
||||
|
||||
**Warning:** This procedure will result in your USB controller(s) being attached directly to dom0.
|
||||
|
||||
|
|
@ -189,18 +194,17 @@ Removing a USB qube
|
|||
7. Reboot.
|
||||
|
||||
|
||||
|
||||
|
||||
[remove your USB-qube]: #removing-a-usb-qube
|
||||
[security implications]: /doc/device-considerations/#usb-security
|
||||
[security implications]: /doc/device-handling-security/#usb-security
|
||||
[enable your keyboard for login]: #enable-a-usb-keyboard-for-login
|
||||
[2270-comm23]: https://github.com/QubesOS/qubes-issues/issues/2270#issuecomment-242900312
|
||||
[PCI Devices]: /doc/pci-devices-in-qubes-R4.0/
|
||||
[PCI Devices]: /doc/pci-devices/
|
||||
[usb-controller]: /doc/usb-devices/#finding-the-right-usb-controller
|
||||
[faq]: /faq/#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot
|
||||
[Security Warning about USB Input Devices]: /doc/device-considerations/#security-warning-on-usb-input-devices
|
||||
[Security Warning about USB Input Devices]: /doc/device-handling-security/#security-warning-on-usb-input-devices
|
||||
[manual setup]: #manual-setup
|
||||
[install dom0 updates]: /doc/software-update-dom0/#how-to-update-dom0
|
||||
[hiding USB controllers from dom0]: #how-to-hide-all-usb-controllers-from-dom0
|
||||
[AEM]: /doc/anti-evil-maid/
|
||||
[create a USB qube]: #creating-and-using-a-usb-qube
|
||||
[create a USB qube]: #creating-and-using-a-usb-qube
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue