mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-07-31 02:29:32 -04:00
Minor changes in how-to-install-software
This commit is contained in:
commit
aa62d0b296
45 changed files with 1498 additions and 553 deletions
|
@ -12,13 +12,17 @@ title: Emergency backup recovery (v4)
|
|||
This page describes how to perform an emergency restore of a backup created on
|
||||
Qubes R4.X (which uses backup format version 4).
|
||||
|
||||
The Qubes backup system has been designed with emergency disaster recovery in
|
||||
mind. No special Qubes-specific tools are required to access data backed up by
|
||||
Qubes. In the event a Qubes system is unavailable, you can access your data on
|
||||
any GNU/Linux system with the following procedure.
|
||||
The Qubes backup system is designed with emergency disaster recovery in mind. No
|
||||
special Qubes-specific tools are required to access data backed up by Qubes. In
|
||||
the event a Qubes system is unavailable, you can access your data on any
|
||||
GNU/Linux system by following the instructions on this page.
|
||||
|
||||
Required `scrypt` Utility
|
||||
-------------------------
|
||||
**Important:** You may wish to store a copy of these instructions with your
|
||||
Qubes backups. All Qubes documentation, including this page, is available in
|
||||
plain text format in the [qubes-doc](https://github.com/QubesOS/qubes-doc) Git
|
||||
repository.
|
||||
|
||||
## Required `scrypt` utility
|
||||
|
||||
In Qubes 4.X, backups are encrypted and integrity-protected with
|
||||
[scrypt](https://www.tarsnap.com/scrypt.html). You will need a copy of this
|
||||
|
@ -34,8 +38,8 @@ easier scripting, which means you'll need to enter the passphrase for each file
|
|||
separately, instead of using `echo ... | scrypt`.
|
||||
|
||||
Here are instructions for obtaining a compiled `scrypt` binary. This example
|
||||
uses an RPM-based system (Fedora), but the same general procedure should work
|
||||
on any GNU/Linux system.
|
||||
uses an RPM-based system (Fedora), but the same general procedure should work on
|
||||
any GNU/Linux system.
|
||||
|
||||
1. If you're not on Qubes 4.X, [import and authenticate the Release 4 Signing
|
||||
Key](/security/verifying-signatures/#how-to-import-and-authenticate-release-signing-keys).
|
||||
|
@ -46,7 +50,7 @@ on any GNU/Linux system.
|
|||
|
||||
[user@restore ~]$ dnf download scrypt
|
||||
|
||||
or, if that doesn't work:
|
||||
Or, if that doesn't work:
|
||||
|
||||
[user@restore ~]$ curl -O https://yum.qubes-os.org/r4.0/current/vm/fc28/rpm/scrypt-1.2.1-1.fc28.x86_64.rpm
|
||||
|
||||
|
@ -62,60 +66,35 @@ on any GNU/Linux system.
|
|||
|
||||
[user@restore ~]$ sudo dnf install rpmdevtools
|
||||
|
||||
5. Extract the `scrypt` binary from the RPM.
|
||||
5. Extract the `scrypt` binary from the RPM and make it conveniently
|
||||
available.
|
||||
|
||||
[user@restore ~]$ rpmdev-extract scrypt-*.rpm
|
||||
[user@restore ~]$ alias scrypt="$PWD/scrypt-*/usr/bin/scrypt"
|
||||
|
||||
6. (Optional) Create an alias for the new binary.
|
||||
|
||||
[user@restore ~]$ alias scrypt="scrypt-*/usr/bin/scrypt"
|
||||
|
||||
Emergency Recovery Instructions
|
||||
-------------------------------
|
||||
## Emergency recovery instructions
|
||||
|
||||
**Note:** In the following example, the backup file is both *encrypted* and
|
||||
*compressed*.
|
||||
|
||||
1. Untar the main backup file.
|
||||
1. Untar the backup metadata from the main backup file.
|
||||
|
||||
[user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456
|
||||
[user@restore ~]$ tar -i -xvf qubes-backup-2023-04-05T123456 \
|
||||
backup-header backup-header.hmac qubes.xml.000.enc
|
||||
backup-header
|
||||
backup-header.hmac
|
||||
qubes.xml.000.enc
|
||||
vm1/private.img.000.enc
|
||||
vm1/private.img.001.enc
|
||||
vm1/private.img.002.enc
|
||||
vm1/icon.png.000.enc
|
||||
vm1/firewall.xml.000.enc
|
||||
vm1/whitelisted-appmenus.list.000.enc
|
||||
dom0-home/dom0user.000.enc
|
||||
|
||||
**To extract only specific VMs:** Each VM in the backup file has its path
|
||||
listed in `qubes.xml.000.enc`. Decrypt it. (In this example, the password is
|
||||
`password`.)
|
||||
|
||||
[user@restore ~]$ cat backup-header | grep backup-id
|
||||
backup-id=20190128T123456-1234
|
||||
[user@restore ~]$ scrypt dec -P qubes.xml.000.enc qubes.xml.000
|
||||
Please enter passphrase: 20190128T123456-1234!qubes.xml.000!password
|
||||
[user@restore ~]$ tar -i -xvf qubes.xml.000
|
||||
|
||||
Now that you have the decrypted `qubes.xml.000` file, search for the
|
||||
`backup-path` property inside of it. With the `backup-path`, extract only
|
||||
the files necessary for your VM (`vmX`).
|
||||
|
||||
[user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456 \
|
||||
backup-header backup-header.hmac vmX/
|
||||
|
||||
2. Set the backup passphrase environment variable. While this isn't strictly
|
||||
required, it will be handy later and will avoid saving the passphrase in
|
||||
the shell's history.
|
||||
required, it will be handy later and will avoid saving the passphrase in the
|
||||
shell's history.
|
||||
|
||||
[user@restore ~]$ read -r backup_pass
|
||||
|
||||
3. Verify the integrity of `backup-header`. For compatibility reasons,
|
||||
`backup-header.hmac` is an encrypted *and integrity protected*
|
||||
version of `backup-header`.
|
||||
Type in your passphrase (it will be visible on screen!) and press Enter.
|
||||
|
||||
3. Verify the integrity of `backup-header` using `backup-header.hmac` (an
|
||||
encrypted *and integrity protected* version of `backup-header`).
|
||||
|
||||
[user@restore ~]$ set +H
|
||||
[user@restore ~]$ echo "backup-header!$backup_pass" |\
|
||||
|
@ -123,34 +102,34 @@ Emergency Recovery Instructions
|
|||
diff -qs backup-header backup-header.verified
|
||||
Files backup-header and backup-header.verified are identical
|
||||
|
||||
**Note:** If this command fails, it may be that the backup was tampered
|
||||
with or is in a different format. In the latter case, look inside
|
||||
`backup-header` at the `version` field. If it contains a value other than
|
||||
`version=4`, go to the instructions for that format version:
|
||||
**Note:** If this command fails, it may be that the backup was tampered with
|
||||
or is in a different format. In the latter case, look inside `backup-header`
|
||||
at the `version` field. If it contains a value other than `version=4`, go to
|
||||
the instructions for that format version:
|
||||
- [Emergency Backup Recovery without Qubes (v2)](/doc/backup-emergency-restore-v2/)
|
||||
- [Emergency Backup Recovery without Qubes (v3)](/doc/backup-emergency-restore-v3/)
|
||||
|
||||
4. Read `backup-header`:
|
||||
4. Read `backup-header`.
|
||||
|
||||
[user@restore ~]$ cat backup-header
|
||||
version=4
|
||||
encrypted=True
|
||||
compressed=True
|
||||
compression-filter=gzip
|
||||
backup_id=20161020T123455-1234
|
||||
hmac-algorithm=scrypt
|
||||
backup-id=20230405T123455-1234
|
||||
|
||||
5. Set `backup_id` to the value in the last line of `backup-header`:
|
||||
5. Set `backup_id` to the value in the last line of `backup-header`. (Note that
|
||||
there is a hyphen in `backup-id` in the file, whereas there is an underscore
|
||||
in `backup_id` in the variable you're setting.)
|
||||
|
||||
[user@restore ~]$ backup_id=20161020T123455-1234
|
||||
[user@restore ~]$ backup_id=20230405T123455-1234
|
||||
|
||||
6. Verify the integrity of your data, decrypt, decompress, and extract
|
||||
`private.img`:
|
||||
6. Verify and decrypt, decompress, and extract the `qubes.xml` file.
|
||||
|
||||
[user@restore ~]$ find vm1 -name 'private.img.*.enc' | sort -V | while read f_enc; do \
|
||||
f_dec=${f_enc%.enc}; \
|
||||
echo "$backup_id!$f_dec!$backup_pass" | scrypt dec -P $f_enc || break; \
|
||||
done | gzip -d | tar -xv
|
||||
vm1/private.img
|
||||
[user@restore ~]$ echo "$backup_id!qubes.xml.000!$backup_pass" |\
|
||||
scrypt dec -P qubes.xml.000.enc | gzip -d | tar -xv
|
||||
qubes.xml
|
||||
|
||||
If this pipeline fails, it is likely that the backup is corrupted or has
|
||||
been tampered with.
|
||||
|
@ -158,23 +137,66 @@ Emergency Recovery Instructions
|
|||
**Note:** If your backup was compressed with a program other than `gzip`,
|
||||
you must substitute the correct compression program in the command above.
|
||||
This information is contained in `backup-header` (see step 4). For example,
|
||||
if your backup is compressed with `bzip2`, use `bzip2 -d` instead in the
|
||||
command above.
|
||||
if your backup is compressed with `bzip2`, use `bzip2 -d` instead of `gzip
|
||||
-d` in the command above. You might need to install a package of the same
|
||||
name (in this example, `bzip2`) through your distribution's package manager.
|
||||
|
||||
7. Mount `private.img` and access your data.
|
||||
7. Search inside of the `qubes.xml` file for the `backup-path` of the qube
|
||||
whose data you wish to restore. If you install the `xmlstarlet` package, the
|
||||
following command will convert `qubes.xml` to a friendlier listing for this
|
||||
purpose:
|
||||
|
||||
[user@restore vm1]$ sudo mkdir /mnt/img
|
||||
[user@restore vm1]$ sudo mount -o loop vm1/private.img /mnt/img/
|
||||
[user@restore vm1]$ cat /mnt/img/home/user/your_data.txt
|
||||
This data has been successfully recovered!
|
||||
[user@restore ~]$ xmlstarlet sel -T -t -m //domain \
|
||||
-v 'concat(.//property[@name="name"], " ", .//feature[@name="backup-path"])' \
|
||||
-n qubes.xml
|
||||
|
||||
anon-whonix
|
||||
debian-11
|
||||
default-mgmt-dvm
|
||||
disp2345
|
||||
fedora-37
|
||||
fedora-37-dvm
|
||||
personal vm123/
|
||||
sys-firewall
|
||||
sys-net
|
||||
sys-usb
|
||||
sys-whonix
|
||||
untrusted
|
||||
vault vm321/
|
||||
whonix-gw-16
|
||||
whonix-ws-16
|
||||
whonix-ws-16-dvm
|
||||
work
|
||||
|
||||
8. Success! If you wish to recover data from more than one VM in your backup,
|
||||
simply repeat steps 6 and 7 for each additional VM.
|
||||
The example output above shows that the backup file includes a qube named
|
||||
`personal` and a qube named `vault`, with `backup-path` values of `vm123/`
|
||||
and `vm321/` respectively. (Every other listed qube was not selected to be
|
||||
included in the backup file.) Use the corresponding value to untar the
|
||||
necessary data files of the qube:
|
||||
|
||||
**Note:** You may wish to store a copy of these instructions with your
|
||||
Qubes backups in the event that you fail to recall the above procedure
|
||||
while this web page is inaccessible. All Qubes documentation, including
|
||||
this page, is available in plain text format in the following Git
|
||||
repository:
|
||||
[user@restore ~]$ tar -i -xvf qubes-backup-2023-04-05T123456 vm123/
|
||||
|
||||
https://github.com/QubesOS/qubes-doc.git
|
||||
8. Verify and decrypt the backed up data, decompress it, and extract it.
|
||||
|
||||
[user@restore ~]$ find vm123/ -name 'private.img.*.enc' | sort -V | while read f_enc; do \
|
||||
f_dec=${f_enc%.enc}; \
|
||||
echo "$backup_id!$f_dec!$backup_pass" | scrypt dec -P $f_enc || break; \
|
||||
done | gzip -d | tar -xv
|
||||
vm123/private.img
|
||||
|
||||
If this pipeline fails, it is likely that the backup is corrupted or has
|
||||
been tampered with.
|
||||
|
||||
Also see the note in step 6 about substituting a different compression
|
||||
program for `gzip`.
|
||||
|
||||
9. Mount `private.img` and access your data.
|
||||
|
||||
[user@restore ~]$ sudo mkdir /mnt/img
|
||||
[user@restore ~]$ sudo mount -o loop vm123/private.img /mnt/img/
|
||||
[user@restore ~]$ ls /mnt/img/home/user/
|
||||
example_data_file.txt
|
||||
...
|
||||
|
||||
Success! If you wish to recover data from more than one qube in your backup,
|
||||
simply repeat steps 7, 8, and 9 for each additional qube.
|
||||
|
|
|
@ -160,6 +160,12 @@ out.
|
|||
6. When you are ready, click **Next**. Qubes will proceed to restore from your
|
||||
backup. Once the progress bar has completed, you may click **Finish**.
|
||||
|
||||
In case that applications are not shown, i.e. "No applications found", open the
|
||||
settings of the qube -> select `Applications` -> click `Refresh applications`.
|
||||
|
||||
When a restored application qube refreshes, the application lists will open the template qubes on which it is based. In that case the template qube should also be restored, if it is missing the default qube will be assigned.
|
||||
The updated list of the installed software can be seen on the left and adjusted accordingly to the user's needs.
|
||||
|
||||
**Note:** When restoring from a dom0 backup, a new directory will be created in
|
||||
the current dom0 home directory, and the contents from the backup will be
|
||||
placed inside this new directory. This is intentional, as it allows users to
|
||||
|
|
|
@ -89,7 +89,7 @@ the other. Alice's setup looks like this:
|
|||
[bind-dirs](/doc/bind-dirs/) to make those changes persistent, but sometimes
|
||||
she doesn't want to get bogged down doing with all that and figures it
|
||||
wouldn't be worth it just for this one qube. She's secretly glad that Qubes
|
||||
OS doesn't judge her this and just gives her the freedom to do things however
|
||||
OS doesn't judge her for this and just gives her the freedom to do things however
|
||||
she likes while keeping everything securely compartmentalized. At times like
|
||||
these, she takes comfort in knowing that things can be messy and disorganized
|
||||
*within* a qube while her overall digital life remains well-organized.
|
||||
|
|
|
@ -17,6 +17,7 @@ Fully updating your Qubes OS system means updating:
|
|||
- [dom0](/doc/glossary/#dom0)
|
||||
- [templates](/doc/glossary/#template)
|
||||
- [standalones](/doc/glossary/#standalone) (if you have any)
|
||||
- [firmware](/doc/glossary/#firmware)
|
||||
|
||||
## Security updates
|
||||
|
||||
|
@ -65,10 +66,19 @@ If you use [Anti Evil Maid (AEM)](/doc/anti-evil-maid/), you'll have to "reseal"
|
|||
|
||||
<div class="alert alert-danger" role="alert">
|
||||
<i class="fa fa-exclamation-triangle"></i>
|
||||
<b>Warning:</b> Updating with direct commands such as <code>dnf update</code>, and <code>apt update</code> is <b>not</b> recommended, since these bypass built-in Qubes OS update security measures. Instead, we strongly recommend using the <b>Qubes Update</b> tool or its command-line equivalents, as described below. (By contrast, <a href="/doc/how-to-install-software/">installing</a> packages using direct package manager commands is fine.)
|
||||
<b>Warning:</b> Updating with direct commands such as <code>dnf update</code> and <code>apt update</code> is <b>not</b> recommended, since these bypass built-in Qubes OS update security measures. Instead, we strongly recommend using the <b>Qubes Update</b> tool or its command-line equivalents, as described below. (By contrast, <a href="/doc/how-to-install-software/">installing</a> packages using direct package manager commands is fine.)
|
||||
</div>
|
||||
|
||||
Advanced users may wish to perform updates via the command-line interface. To update templates and standalones non-interactively, use the command `qubes-vm-update`, and to update dom0, use `qubes-dom0-update`. If you want to perform an update with more advanced user-configurable options (e.g., custom pre- or post-update scripts, custom workarounds), see: [update.qubes-dom0](/doc/salt/#updatequbes-dom0) and [update.qubes-vm](/doc/salt/#updatequbes-vm).
|
||||
Advanced users may wish to perform updates via the command-line interface. There are two ways to do this:
|
||||
|
||||
- If you are using Salt, one can use the following two Salt states.
|
||||
|
||||
- [update.qubes-dom0](/doc/salt/#updatequbes-dom0)
|
||||
- [update.qubes-vm](/doc/salt/#updatequbes-vm)
|
||||
|
||||
- Alternatively, use `qubes-dom0-update` to update dom0, and use `qubes-vm-update` to update domUs.
|
||||
|
||||
Using either of these methods has the same effect as updating via the Qubes Update tool.
|
||||
|
||||
Advanced users may also be interested in learning [how to enable the testing repos](/doc/testing/).
|
||||
|
||||
|
@ -83,3 +93,61 @@ In the case of Qubes OS itself, we will make an [announcement](/news/categories/
|
|||
Periodic upgrades are also important for templates. For example, you might be using a [Fedora template](/doc/templates/fedora/). The [Fedora Project](https://getfedora.org/) is independent of the Qubes OS Project. They set their own [schedule](https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle#Maintenance_Schedule) for when each Fedora release reaches EOL. You can always find out when an OS reaches EOL from the upstream project that maintains it. We also pass along any EOL notices we receive for official template OSes as a convenience to Qubes users (see the [supported template releases](/doc/supported-releases/#templates)).
|
||||
|
||||
The one exception to all this is the specific release used for dom0 (not to be confused with Qubes OS as a whole), which [doesn't have to be upgraded](/doc/supported-releases/#note-on-dom0-and-eol).
|
||||
|
||||
## Microcode Updates
|
||||
|
||||
x86\_64 CPUs contain special low-level software called **microcode**, which
|
||||
is used to implement certain instructions and runs on various processors that
|
||||
are outside of Qubes OS's control. Most microcode is in an on-CPU ROM, but
|
||||
CPU vendors provide patches that modify small parts of this microcode. These
|
||||
patches can be loaded from the BIOS or by the OS.
|
||||
|
||||
The fixes for some QSBs require a microcode update to work. Furthermore,
|
||||
microcode updates will sometimes fix vulnerabilities "silently". This means
|
||||
that the vulnerability impacts the security of Qubes OS, but the Qubes OS
|
||||
Security Team is not informed that a vulnerability exists, so no QSB is ever
|
||||
issued. Therefore, it is critical to update microcode.
|
||||
|
||||
Intel provides microcode updates for all of their CPUs in a public Git
|
||||
repository, and allows OS vendors (such as Qubes OS) to distribute the updates
|
||||
free of charge. AMD, however, only provides microcode for server CPUs.
|
||||
AMD client CPUs can only receive microcode updates via a system firmware
|
||||
update. Worse, there is often a significant delay between when a vulnerability
|
||||
becomes public and when firmware that includes updated microcode is available
|
||||
to Qubes OS users. This is why Qubes OS recommends Intel CPUs instead of
|
||||
AMD CPUs.
|
||||
|
||||
## Firmware updates
|
||||
|
||||
Modern computers have many processors other than those that run Qubes OS.
|
||||
Furthermore, the main processor cores also run firmware, which is used to
|
||||
boot the system and often provides some services at runtime. Both kinds
|
||||
of firmware can have bugs and vulnerabilities, so it is critical to keep
|
||||
them updated.
|
||||
|
||||
Some firmware is loaded by the OS at runtime.
|
||||
Such firmware is provided by the `linux-firmware` package and can be updated the usual way.
|
||||
Other devices have persistent firmware that must be updated manually.
|
||||
|
||||
Qubes OS supports updating system firmware in three different ways.
|
||||
Which one to use depends on the device whose firmware is being updated.
|
||||
|
||||
- If a device is attached to a domU, it should be updated using **fwupd**.
|
||||
fwupd is included in both Debian and Fedora repositories.
|
||||
It requires Internet access to use, but you can use the updates proxy if you
|
||||
need to update firmware from an offline VM. You can use either the
|
||||
command-line `fwupdmgr` tool or any of the graphical interfaces to fwupd.
|
||||
|
||||
- If a device is attached to dom0, use the `qubes-fwupdmgr` command-line tool.
|
||||
This tool uses fwupd internally, but it fetches firmware and metadata over
|
||||
qrexec from the dom0 UpdateVM, rather than fetching them from the Internet.
|
||||
Unfortunately, their is no graphical interface for this tool yet.
|
||||
|
||||
- System76 systems use a special update tool which is simpler than fwupd.
|
||||
Support for this tool is currently in progress. Once it is finished,
|
||||
users will be able to use the **system76-firmware-cli** command-line
|
||||
tool to update the firmware.
|
||||
|
||||
Firmware updates are important on all systems, but they are especially
|
||||
important on AMD client systems. These doesn't support loading microcode from
|
||||
the OS, so firmware updates are the **only** way to obtain microcode updates.
|
||||
|
|
|
@ -13,7 +13,7 @@ title: How to use USB devices
|
|||
|
||||
If you are looking to handle USB *storage* devices (thumbdrives or USB-drives), please have a look at the [block device](/doc/how-to-use-block-storage-devices/) page.
|
||||
|
||||
**Note:** Attaching USB devices to VMs requires a [USB qube](/doc/usb-qubes/).
|
||||
**Note:** Attaching USB devices to qubes requires a [USB qube](/doc/usb-qubes/).
|
||||
|
||||
**Important security warning:** USB passthrough comes with many security implications.
|
||||
Please make sure you carefully read and understand the **[security considerations](/doc/device-handling-security/#usb-security)**.
|
||||
|
@ -28,15 +28,15 @@ Examples of valid cases for USB-passthrough:
|
|||
(If you are thinking to use a two-factor-authentication device, [there is an app for that](/doc/ctap-proxy/).
|
||||
But it has some [issues](https://github.com/QubesOS/qubes-issues/issues/4661).)
|
||||
|
||||
## Attaching And Detaching a USB Device
|
||||
## Attaching and detaching a USB device
|
||||
|
||||
### With Qubes Device Manager
|
||||
### With Qubes device manager
|
||||
|
||||
Click the device-manager-icon: 
|
||||
A list of available devices appears.
|
||||
USB-devices have a USB-icon to their right: 
|
||||
|
||||
Hover on one device to display a list of VMs you may attach it to.
|
||||
Hover on one device to display a list of qubes you may attach it to.
|
||||
|
||||
Click one of those.
|
||||
The USB device will be attached to it.
|
||||
|
@ -44,11 +44,11 @@ You're done.
|
|||
|
||||
After you finished using the USB-device, you can detach it the same way by clicking on the Devices Widget.
|
||||
You will see an entry in bold for your device such as **`sys-usb:2-5 - 058f_USB_2.0_Camera`**.
|
||||
Hover on the attached device to display a list of running VMs.
|
||||
Hover on the attached device to display a list of running qubes
|
||||
The one to which your device is connected will have an eject button  next to it.
|
||||
Click that and your device will be detached.
|
||||
|
||||
### With The Command Line Tool
|
||||
### With the command line tool
|
||||
|
||||
In dom0, you can use `qvm-usb` from the commandline to attach and detach devices.
|
||||
|
||||
|
@ -74,7 +74,7 @@ sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse
|
|||
```
|
||||
|
||||
Now, you can use your USB device (camera in this case) in the `work` qube.
|
||||
If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section](#installation-of-qubes-usb-proxy).
|
||||
If you see the error `ERROR: qubes-usb-proxy not installed in the qube` instead, please refer to the [Installation Section](#installation-of-qubes-usb-proxy).
|
||||
|
||||
When you finish, detach the device.
|
||||
|
||||
|
@ -87,20 +87,20 @@ sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
|
|||
sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse
|
||||
```
|
||||
|
||||
## Maintenance And Customisation
|
||||
## Maintenance and customisation
|
||||
|
||||
### Creating And Using a USB qube
|
||||
### Creating and using a USB qube
|
||||
|
||||
If you've selected to install a usb-qube during system installation, everything is already set up for you in `sys-usb`.
|
||||
If you've later decided to create a usb-qube, please follow [this guide](/doc/usb-qubes/).
|
||||
|
||||
### Installation Of `qubes-usb-proxy`
|
||||
### Installation of `qubes-usb-proxy`
|
||||
|
||||
To use this feature, the `qubes-usb-proxy` package needs to be installed in the templates used for the USB qube and qubes you want to connect USB devices to.
|
||||
This section exists for reference or in case something broke and you need to reinstall `qubes-usb-proxy`.
|
||||
Under normal conditions, `qubes-usb-proxy` should already be installed and good to go.
|
||||
|
||||
If you receive this error: `ERROR: qubes-usb-proxy not installed in the VM`, you can install the `qubes-usb-proxy` with the package manager in the VM you want to attach the USB device to.
|
||||
If you receive this error: `ERROR: qubes-usb-proxy not installed in the qube`, you can install the `qubes-usb-proxy` with the package manager in the qube you want to attach the USB device to.
|
||||
|
||||
- Fedora:
|
||||
```
|
||||
|
@ -111,18 +111,19 @@ If you receive this error: `ERROR: qubes-usb-proxy not installed in the VM`, you
|
|||
sudo apt-get install qubes-usb-proxy
|
||||
```
|
||||
|
||||
### Using USB Keyboards And Other Input Devices
|
||||
### Using USB keyboards and other input devices
|
||||
|
||||
**Warning:** especially keyboards need to be accepted by default when using them to login! Please make sure you carefully read and understood the **[security considerations](/doc/device-handling-security/#usb-security)** before continuing!
|
||||
|
||||
Mouse and keyboard setup are part of [setting up a USB qube](/doc/usb-qubes/).
|
||||
|
||||
### Finding The Right USB Controller
|
||||
### Finding the right USB controller
|
||||
|
||||
Some USB devices are not compatible with the USB pass-through method Qubes employs.
|
||||
In situations like these, you can try to pass through the entire USB controller to a qube as PCI device.
|
||||
However, with this approach one cannot attach single USB devices but has to attach the whole USB controller with whatever USB devices are connected to it.
|
||||
However, with this approach you cannot attach single *USB devices* but have to attach the whole *USB controller* with whatever USB devices are connected to it.
|
||||
|
||||
You can find your controller and its BDF address using the method described below, using the command-line tools `lsusb` and `readlink`.
|
||||
If you have multiple USB controllers, you must first figure out which PCI device is the right controller.
|
||||
|
||||
First, find out which USB bus the device is connected to (note that these steps need to be run from a terminal inside your USB qube):
|
||||
|
@ -141,7 +142,7 @@ Bus 003 Device 003: ID 413c:818d Dell Computer Corp.
|
|||
(In this case, the device isn't fully identified)
|
||||
|
||||
The device is connected to USB bus \#3.
|
||||
Check which other devices are connected to the same bus, since *all* of them will be attach to the same VM.
|
||||
Check which other devices are connected to the same bus, since *all* of them will be attached to the target qube.
|
||||
|
||||
To find the right controller, follow the usb bus:
|
||||
|
||||
|
@ -154,11 +155,29 @@ This should output something like:
|
|||
```
|
||||
../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
|
||||
```
|
||||
|
||||
Now you see the path and the text between `/pci0000:00/0000:` and `/usb3` i.e. `00:1a.0` is the BDF address. Strip the address and pass it to the [`qvm-pci` tool](/doc/how-to-use-pci-devices/) to attach the controller to the targetVM.
|
||||
|
||||
For example, On R 4.0 the command would look something like
|
||||
|
||||
Now you see the path: the text between `/pci0000:00/0000:` and `/usb3` i.e. `00:1a.0` is the BDF address. Strip the address and pass it to the [`qvm-pci` tool](/doc/how-to-use-pci-devices/) to attach the controller to the target qube, like this:
|
||||
```
|
||||
qvm-pci attach --persistent personal dom0:00_1a.0
|
||||
```
|
||||
|
||||
It is possible that on some system configurations the readlink method produces output which is different from the example above,
|
||||
For example, you might see output like this:
|
||||
```
|
||||
../../../devices/pci0000:00/0000:00:1c.0/0000:01:00.0/usb1
|
||||
```
|
||||
In this case, there is a PCI bridge, and the BDF address of the controller is the *last* item, 01:00.0
|
||||
|
||||
If the output format does not match this example, or you are unsure if it contains the correct BDF address, you can try finding the address using using the Qube Manager instead.
|
||||
|
||||
### Identifying controllers using the Qube Manager
|
||||
Using Qube Manager you can quickly determine the controllers on your system and their BDF addresses, but not which controller a particular device is attached to.
|
||||
|
||||
Open the Qube Manager, then right click on one of the qubes and open the settings. Go to the tab "Devices".
|
||||
Here you should see your available devices along with their BDF addresses. Look for the lines containing "USB controller".
|
||||
They should look something like: `01:00.0 USB controller: Name of manufacturer`
|
||||
|
||||
The first part is the BDF address, in this example: `01:00.0`
|
||||
|
||||
If, for example, you have 2 USB controllers in your system because you added one you should see 2 such lines and you can probably guess which controller is the one on the mainboard and which one you added. For example, if you have a mainboard with an Intel chipset, it is possible that all of the mainboard devices show as "Intel Corporation", while the added controller shows another manufacturer's name.
|
||||
|
||||
Now you should be able to tell which is the BDF address of the mainboard USB controller or the added USB controller.
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue