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

typos, fixes in block-devices.md

Browse Source
This commit is contained in:
GammaSQ 2019-03-14 23:57:26 +01:00
parent 6d6f32f788
commit 440b319fb0
No known key found for this signature in database
GPG Key ID: D552FD2F98647C64
3 changed files with 12 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
common-tasks/block-devices.md
View File

@ -13,7 +13,7 @@ Block or Storage Devices in Qubes R4.0
If you don't know what a "block device" is, just think of it as a fancy way to say "something that stores data". If you don't know what a "block device" is, just think of it as a fancy way to say "something that stores data".
#Using The GUI to Attach a Drive # Using The GUI to Attach a Drive #
(**Note:** In the present context, the term "USB drive" denotes any [USB mass storage device][mass-storage]. (**Note:** In the present context, the term "USB drive" denotes any [USB mass storage device][mass-storage].
In addition to smaller flash memory sticks, this includes things like USB external hard drives.) In addition to smaller flash memory sticks, this includes things like USB external hard drives.)
@ -33,7 +33,7 @@ Click on one and your USB drive will be attached!
However, it often means the AppVM won't detect the new partition and you will need to manually mount it inside the AppVM. However, it often means the AppVM won't detect the new partition and you will need to manually mount it inside the AppVM.
See below for more detailed steps. See below for more detailed steps.
#Block Devices in VMs # 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: 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:
cd ~ cd ~
@ -49,7 +49,7 @@ If several different block-devices are attached to a single VM, the last letter
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 [`frontend-dev`-option][frontend-dev].
#Command Line Tool Guide # 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 `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. `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.
@ -96,7 +96,7 @@ In case of a USB-drive, make sure it's attached to your computer. If you don't s
6. You may now remove the device or attach it to another qube. 6. You may now remove the device or attach it to another qube.
#Recovering From Premature Device Destruction # Recovering From Premature Device Destruction #
If the you fail to detach the device before it's destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), [there will be problems][premature removal]. If the you fail to detach the device before it's destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), [there will be problems][premature removal].
To recover from this error state, in dom0 run To recover from this error state, in dom0 run
@ -107,7 +107,7 @@ To recover from this error state, in dom0 run
However, if the block device originated in dom0, you will have to refer to the [old way][detach dom0 device]. However, if the block device originated in dom0, you will have to refer to the [old way][detach dom0 device].
#Attaching a File # Attaching a File #
To attach a file as block device to another qube, first turn it into a loopback device inside the sourceVM. 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 1. In the linux sourceVM run
@ -134,10 +134,10 @@ To attach a file as block device to another qube, first turn it into a loopback
sudo losetup -d /dev/loop0 sudo losetup -d /dev/loop0
#Additional Attach Options # 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).) 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 ## 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 ...) 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 ...)
usage example: usage example:
@ -146,7 +146,7 @@ usage example:
This command will attach the partition `sda1` to `work` as `/dev/xvdz`. This command will attach the partition `sda1` to `work` as `/dev/xvdz`.
##read-only ## read-only ##
Attach device in read-only mode. Protects the block device in case you don't trust the targetVM. Attach device in read-only mode. Protects the block device in case you don't trust the targetVM.
If the device is a read-only device, this option is forced true. If the device is a read-only device, this option is forced true.
@ -161,7 +161,7 @@ There exists a shortcut to set read-only `true`, `--ro`:
The two commands are equivalent. The two commands are equivalent.
##devtype ## devtype ##
Usually, a block device is attached as disk. In case you need to attach a block device as cdrom, this option allows that. Usually, a block device is attached as disk. In case you need to attach a block device as cdrom, this option allows that.
usage example: usage example:
@ -174,7 +174,7 @@ This option accepts `cdrom` and `disk`, default is `disk`.
[device handling in qubes]: /doc/device-handling/ [device handling in qubes]: /doc/device-handling/
[mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class [mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class
[device manager icon]:https://raw.githubusercontent.com/hrdwrrsk/adwaita-xfce-icon-theme/master/Adwaita-Xfce/22x22/devices/media-removable.png <!--TODO: find actual icon used in qubes!--> [device manager icon]:/attachment/wiki/Devices/media-removable.png
[frontend-dev]: #frontend-dev [frontend-dev]: #frontend-dev
[premature removal]: https://github.com/QubesOS/qubes-issues/issues/1082 [premature removal]: https://github.com/QubesOS/qubes-issues/issues/1082
[detach dom0 device]: /doc/usb/#what-if-i-removed-the-device-before-detaching-it-from-the-vm [detach dom0 device]: /doc/usb/#what-if-i-removed-the-device-before-detaching-it-from-the-vm

2
common-tasks/pci-devices.md
View File

@ -21,7 +21,7 @@ Unlike other devices ([USB], [block], mic), PCI devices need to be attached on V
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. 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. 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 aformentioned [security considerations]. 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 [security considerations].
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. 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. 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.

2
security/device-considerations.md
View File

@ -18,7 +18,7 @@ Attaching a full block device (e.g. `sda`) again offers more attack surface than
PCI Security PCI Security
------------ ------------
Attaching a PCI device to a qube has serious security implications. It exposes the device driver running in the qube to an external device (and sourceVM, which contains the device - e.g. `sys-usb`). In many cases a malicious device can choose what driver will be loaded (for example by manipulating device metadata like vendor and product identifiers) - even if the intended driver is sufficiently secure, the device may try to attack a different, less secure driver. Attaching a PCI device to a qube has serious security implications. It exposes the device driver running in the qube to an external device (and sourceVM, which contains the device - e.g. `sys-usb`). In many cases a malicious device can choose what driver will be loaded (for example by manipulating device metadata like vendor and product identifiers) - even if the intended driver is sufficiently secure, the device may try to attack a different, less secure driver.
Furthermore that VM has full controll of the device and may be able to exploit bugs or malicious implementation of the hardware, as well as plain security problems the hardware may pose. (For example, if you attach a USB controller, all the security implications of USB passthrough apply as well.) Furthermore that VM has full control of the device and may be able to exploit bugs or malicious implementation of the hardware, as well as plain security problems the hardware may pose. (For example, if you attach a USB controller, all the security implications of USB passthrough apply as well.)
By default, Qubes requires any PCI device to be resettable from the outside (i.e. via the hypervisor), which completely reinitialises the device. This ensures that any device that was attached to a compromised VM, even if that VM was able to use bugs in the PCI device to inject malicious code, can be trusted again. (Or at least as trusted as it was when Qubes booted.) By default, Qubes requires any PCI device to be resettable from the outside (i.e. via the hypervisor), which completely reinitialises the device. This ensures that any device that was attached to a compromised VM, even if that VM was able to use bugs in the PCI device to inject malicious code, can be trusted again. (Or at least as trusted as it was when Qubes booted.)