Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-02-17 21:34:17 -05:00
Code Issues Packages Projects Releases Wiki Activity

Fix line breaks

Browse Source
This commit is contained in:
awokd 2018-02-05 01:25:19 +00:00 committed by GitHub
parent d2837c4a22
commit c87072d798
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 65 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

120
configuration/assigning-devices.md
View File

@ -12,41 +12,43 @@ Assigning Devices to VMs
======================== ========================
Sometimes you may need to assign an entire PCI or PCI Express device directly Sometimes you may need to assign an entire PCI or PCI Express device directly
to a qube. This is also known as PCI pass-through. The Qubes installer does this to a qube.
by default for `sys-net` (assigning all network class controllers), as well as This is also known as PCI pass-through.
`sys-usb` (assigning all USB controllers) if you chose to create the 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. USB qube during install.
While this covers most use cases, there are some occasions when you may want to 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 manually assign one NIC to `sys-net` and another to a custom NetVM,
other type of PCI controller you want to manually assign. 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. Note that one can only assign full PCI or PCI Express devices by default.
This limit is imposed by the PC and VT-d This limit is imposed by the PC and VT-d architectures.
architectures. This means if a PCI device has multiple functions, all instances 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 FLR with the of it need to be assigned to the same qube unless you have disabled FLR with the
`no-strict-reset` (R4.0) or `pci_strictreset` (R3.2) option. `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 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. same device listed multiple times with only the number after the "." changing.
While a device can only be attached to one VM at a time, it *is* possible to While a device can only be attached to one 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 *assign* the same device to more than one VM at a time.
use the device in one VM, shut that VM down, start up a different VM (to which This means that you can use the device in one VM, shut that VM down, start up a different VM
the same device is also assigned), then use the device in that VM. This can be (to which the same device is also assigned), then use the device in that VM.
useful if, for example, you have only one USB controller, but you have multiple 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. security domains which all require the use of different USB devices.
R4.0 R4.0
------------------------ ------------------------
In order to assign a whole PCI(e) device to a VM, one should use the `qvm-pci` In order to assign a whole PCI(e) device to a VM, one should use the `qvm-pci` tool.
tool. First, list the available PCI devices: First, list the available PCI devices:
~~~ ~~~
qvm-pci qvm-pci
~~~ ~~~
This will show you the `backend:BDF` address of each PCI device. It will look something This will show you the `backend:BDF` address of each PCI device.
like `dom0:00_1a.0`. Once you've found the address of the device you want to It will look something like `dom0:00_1a.0`.
Once you've found the address of the device you want to
assign, then attach it like so: assign, then attach it like so:
~~~ ~~~
@ -70,8 +72,9 @@ tool. First, list the available PCI devices:
lspci lspci
~~~ ~~~
This will show you the BDF address of each PCI device. It will look something This will show you the BDF address of each PCI device.
like `00:1a.0`. Once you've found the BDF address of the device you want to 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: assign, then attach it like so:
~~~ ~~~
@ -88,9 +91,9 @@ qvm-pci -a personal 00:1a.0
Using Qubes Manager Using Qubes Manager
------------------- -------------------
The above steps can also be done in Qubes Manager. Simply go into the VM The above steps can also be done in Qubes Manager.
settings of your desired VM, then go to the "Devices" tab. This will show you a Simply go into the VM settings of your desired VM, then go to the "Devices" tab.
list of available devices, which you can select to be assigned to that VM. This will show you a list of available devices, which you can select to be assigned to that VM.
Finding the right USB controller Finding the right USB controller
@ -98,28 +101,31 @@ Finding the right USB controller
Some USB devices are not compatible with the USB pass-through method Qubes employs. Some USB devices are not compatible with the USB pass-through method Qubes employs.
In situations like this, you can still often get the USB device to work by In situations like this, you can still often get the USB device to work by
passing through the entire USB controller to a qube. However, with this approach passing through the entire USB controller to a qube.
one cannot assign single USB devices, only the whole USB controller with whatever However, with this approach one cannot assign single USB devices,
USB devices are connected to it. More information on using and managing USB devices with qubes is only the whole USB controller with whatever USB devices are connected to it.
available on the [USB] page. If you want assign a certain USB device to a VM (by attaching the whole More information on using and managing USB devices with qubes is
USB controller), you need to figure out which PCI device is the right available on the [USB] page.
controller. First, check to which USB bus the device is connected (note that If you want assign a certain USB device to a VM (by attaching the whole USB controller),
you need to figure out which PCI device is the right controller.
First, check to which USB bus the device is connected (note that
these steps need to be run from a terminal inside `dom0`): these steps need to be run from a terminal inside `dom0`):
~~~ ~~~
lsusb lsusb
~~~ ~~~
For example, I want assign a broadband modem to the netvm. In the output of For example, I want assign a broadband modem to the netvm.
`lsusb` it can be listed as something like this. (In this case, the device isn't In the output of `lsusb` it can be listed as something like this.
fully identified): (In this case, the device isn't fully identified):
~~~ ~~~
Bus 003 Device 003: ID 413c:818d Dell Computer Corp. Bus 003 Device 003: ID 413c:818d Dell Computer Corp.
~~~ ~~~
The device is connected to USB bus \#3. Then check which other devices are The device is connected to USB bus \#3.
connected to the same bus, since *all* of them will be assigned to the same VM. Then check which other devices are connected to the same bus,
since *all* of them will be assigned to the same VM.
Now is the time to find right USB controller: Now is the time to find right USB controller:
~~~ ~~~
@ -132,8 +138,8 @@ This should output something like:
../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3 ../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
~~~ ~~~
Now you see the BDF address in the path (right before final `usb3`). Strip the Now you see the BDF address in the path (right before final `usb3`).
leading `0000:` and pass the rest to the `qvm-pci` tool to attach the controller Strip the leading `0000:` and pass the rest to the `qvm-pci` tool to attach the controller
with the version specific steps above. with the version specific steps above.
Possible issues Possible issues
@ -142,9 +148,10 @@ Possible issues
### DMA buffer size ### DMA buffer size
VMs with assigned PCI devices in Qubes have allocated a small buffer for DMA VMs with assigned PCI devices in Qubes have allocated a small buffer for DMA
operations (called swiotlb). By default it is 2MB, but some devices need a operations (called swiotlb).
larger buffer. To change this allocation, edit VM's kernel parameters (this is By default it is 2MB, but some devices need a larger buffer.
expressed in 512B chunks): To change this allocation, edit VM's kernel parameters
(this is expressed in 512B chunks):
~~~ ~~~
# qvm-prefs netvm |grep kernelopts # qvm-prefs netvm |grep kernelopts
@ -157,12 +164,14 @@ Controller.
### PCI passthrough issues ### PCI passthrough issues
Sometimes the PCI arbitrator is too strict. There is a way to enable permissive mode Sometimes the PCI arbitrator is too strict.
for it. See also: [this thread][ml2] and the Xen wiki's [PCI passthrough] page. There is a way to enable permissive mode for it.
See also: [this thread][ml2] and the Xen wiki's [PCI passthrough] page.
**NOTE:** By setting the permissive flag for the PCI device, you're potentially **NOTE:** By setting the permissive flag for the PCI device, you're potentially
weakening the device isolation, especially if your system is not equipped with weakening the device isolation, especially if your system is not equipped with
VT-d Interrupt Remapping unit. See [Software Attacks on Intel VT-d] (page 7) VT-d Interrupt Remapping unit.
See [Software Attacks on Intel VT-d] (page 7)
for more details. for more details.
At other times, you may instead need to disable the FLR requirement on a device. At other times, you may instead need to disable the FLR requirement on a device.
@ -172,16 +181,17 @@ the [FAQ](/doc/user-faq/) for more details.
R4.0 R4.0
------------------------ ------------------------
Permissive mode and strict reset are options set as part of PCI device attachment. If you've already Permissive mode and strict reset are options set as part of PCI device attachment.
attached the PCI device to a VM, detach it first either with Qube Manager If you've already attached the PCI device to a VM, detach it first either with Qube Manager
or `qvm-pci`, then list the available PCI devices: or `qvm-pci`, then list the available PCI devices:
~~~ ~~~
qvm-pci qvm-pci
~~~ ~~~
This will show you the `backend:BDF` address of each PCI device. It will look something This will show you the `backend:BDF` address of each PCI device.
like `dom0:00_1a.0`. Once you've found the address of the device you want to It will look something like `dom0:00_1a.0`.
Once you've found the address of the device you want to
assign, then attach it like so: assign, then attach it like so:
~~~ ~~~
@ -198,9 +208,9 @@ qvm-pci attach --persistent --option permissive=true --option no-strict-reset=tr
Running `qvm-pci` again should then show your PCI device attached with both the Running `qvm-pci` again should then show your PCI device attached with both the
`permissive` and `no-strict-reset` options set. `permissive` and `no-strict-reset` options set.
**Note** again that in most cases you should **Note** again that in most cases you should not need either of these options set.
not need either of these options set. Only set one or more of them as required to get Only set one or more of them as required to get your device to function,
your device to function, or replace the device with one that functions properly with Qubes. or replace the device with one that functions properly with Qubes.
R3.2 R3.2
------------------------ ------------------------
@ -231,18 +241,18 @@ The strict reset option is set for all devices attached to a VM with:
qvm-prefs usbVM -s pci_strictreset false qvm-prefs usbVM -s pci_strictreset false
``` ```
**Note** again that in most cases you should **Note** again that in most cases you should not need either of these options set.
not need either of these options set. Only set one or more of them as required to get Only set one or more of them as required to get your device to function,
your device to function, or replace the device with one that functions properly with Qubes. or replace the device with one that functions properly with Qubes.
Bringing PCI device back to dom0 Bringing PCI device back to dom0
-------------------------------- --------------------------------
By default, when a device is detached from a VM (or when a VM with an attached 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 PCI device is shut down), the device is *not* automatically attached back to dom0.
dom0. This is an intended feature. A device which was previously assigned to a This is an intended feature.
VM less trusted than dom0 (which, in Qubes, is *all* of them) could attack dom0 A device which was previously assigned to a VM less trusted than dom0
if it were automatically reassigned there. (which, in Qubes, is *all* of them) could attack dom0 if it were automatically reassigned there.
In order to re-enable the device in dom0, either: In order to re-enable the device in dom0, either:
@ -251,8 +261,8 @@ In order to re-enable the device in dom0, either:
or or
* Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the * 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>` pciback driver, and attach it back to the original driver.
with your device, for example `00:1c.2`: Replace `<BDF>` with your device, for example `00:1c.2`:
~~~ ~~~
echo 0000:<BDF> > /sys/bus/pci/drivers/pciback/unbind echo 0000:<BDF> > /sys/bus/pci/drivers/pciback/unbind