Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-10-01 01:25:40 -04:00
Code Issues Packages Projects Releases Wiki Activity

Improve clarity, grammar, links, and formatting

Browse Source
This commit is contained in:
Axon 2016-03-22 21:53:39 +00:00
parent 1a28ef4d40
commit 160a5f24c0
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
1 changed files with 66 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
configuration/assigning-devices.md
View File

@ -11,49 +11,72 @@ redirect_from:
Assigning Devices to VMs
========================
In order to assign a whole PCI(e) device to a VM, one should use `qvm-pci` tool. E.g.
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
~~~
Find the BDF address of the device you want to assign, and then:
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>
~~~
E.g. assuming 00:1a.0 is a BDF of the device I want to assign to the "personal" domain:
For example, if `00:1a.0` is the BDF of the device I want to assign to the
"personal" domain, I would do this:
~~~
qvm-pci -a personal 00:1a.0
~~~
Note that one can only assign full PCI or PCI Express devices. This means one cannot assign single USB devices -- only the whole USB controller with whatever USB devices connected to it. This limit is imposed by PC and VT-d architecture.
Note that one can only assign full PCI or PCI Express devices. This means one
cannot assign single USB devices -- only the whole USB controller with whatever
USB devices are connected to it. This limit is imposed by the PC and VT-d
architectures. More information on using and managing USB devices with qubes is
available on the [USB] page.
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
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 Qubes Manager
-------------------
TODO
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.
\<screenshot\>
Finding the right USB controller
--------------------------------
If you want assign certain USB device to a VM (by attaching a 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:
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:
~~~
lsusb
~~~
For example I want assign a broadband modem to the netvm. In lsusb output it can be listed as something like this (in this case device isn't fully identified):
For example, I want assign a broadband modem to the netvm. In the out put of
`lsusb` it can be listed as something like this. (In this case, the device isn't
fully identified):
~~~
Bus 003 Device 003: ID 413c:818d Dell Computer Corp.
~~~
The device is connected to the USB bus \#3. Then check which other devices are connected to the same bus - all of them will be assigned to the same VM. Now is the time to find right USB controller:
The device is connected to USB bus \#3. 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:
~~~
readlink /sys/bus/usb/devices/usb3
@ -65,18 +88,23 @@ This should output something like:
../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
~~~
Now you see BDF address in the path (right before final usb3). Strip leading "0000:" and pass the rest to qvm-pci tool:
Now you see the BDF address in the path (right before final `usb3`). Strip the
leading `0000:` and pass the rest to the `qvm-pci` tool:
~~~
qvm-pci -a netvm 00:1a.0
~~~
Possible issues
---------------
### DMA buffer size
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 larger buffer. To change this allocation, edit VM's kernel parameters (this is expressed in 512B chunks):
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
larger buffer. To change this allocation, edit VM's kernel parameters (this is
expressed in 512B chunks):
~~~
# qvm-prefs netvm |grep kernelopts
@ -84,11 +112,13 @@ kernelopts : iommu=soft swiotlb=2048 (default)
# qvm-prefs -s netvm kernelopts "iommu=soft swiotlb=4096"
~~~
This is [known to be needed](https://groups.google.com/group/qubes-devel/browse_thread/thread/631c4a3a9d1186e3) for Realtek RTL8111DL Gigabit Ethernet Controller.
This is [known to be needed][ml1] for the Realtek RTL8111DL Gigabit Ethernet
Controller.
### PCI passthrough issues
Sometimes PCI arbitrator is too strict. There is a way to enable permissive mode for it. Create `/etc/systemd/system/qubes-pre-netvm.service`:
Sometimes PCI arbitrator is too strict. There is a way to enable permissive mode
for it. Create `/etc/systemd/system/qubes-pre-netvm.service`:
~~~
[Unit]
@ -106,20 +136,32 @@ WantedBy=multi-user.target
Then enable it with `systemctl enable qubes-pre-netvm.service`
See also: [https://groups.google.com/forum/\#!topic/qubes-users/Fs94QAc3vQI](https://groups.google.com/forum/#!topic/qubes-users/Fs94QAc3vQI), [http://wiki.xen.org/wiki/Xen\_PCI\_Passthrough](http://wiki.xen.org/wiki/Xen_PCI_Passthrough)
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
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)
for more details.
**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 VT-d Interrupt Remapping unit -- see [this paper, page 7](http://www.invisiblethingslab.com/resources/2011/Software%20Attacks%20on%20Intel%20VT-d.pdf) for more details.
Bringing PCI device back to dom0
--------------------------------
By default device detached from some VM (or when VM with PCI device attached get shut down) isn't attached back to dom0. This is an intended feature. A device which was previously assigned to a less trusted AppVM could attack dom0 if it were automatically reassigned there. In order to re-enable the device in dom0, either:
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 assigned to a
VM less trusted than dom0 (which, in Qubes, is *all* of them) could attack dom0
if it were automatically reassigned there.
1. Reboot the physical machine.
In order to re-enable the device in dom0, either:
* Reboot the physical machine.
or
1. Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver and attach back to the original driver. Replace `<BDF>` with your device, for example `00:1c.2`:
* 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 device, for example `00:1c.2`:
~~~
echo 0000:<BDF> > /sys/bus/pci/drivers/pciback/unbind
@ -129,3 +171,9 @@ or
~~~
[usb]: /doc/usb/
[ml1]: https://groups.google.com/group/qubes-devel/browse_thread/thread/631c4a3a9d1186e3
[ml2]: https://groups.google.com/forum/\#!topic/qubes-users/Fs94QAc3vQI
[PCI passthrough]: http://wiki.xen.org/wiki/Xen_PCI_Passthrough
[Software Attacks on Intel VT-d]: http://www.invisiblethingslab.com/resources/2011/Software%20Attacks%20on%20Intel%20VT-d.pdf