Minor changes in how-to-install-software

This commit is contained in:
unman 2025-05-15 11:07:17 +00:00
commit aa62d0b296
No known key found for this signature in database
GPG key ID: BB52274595B71262
45 changed files with 1498 additions and 553 deletions

View file

@ -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.

View file

@ -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

View file

@ -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.

View file

@ -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.

View file

@ -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: ![device manager icon](/attachment/doc/media-removable.png)
A list of available devices appears.
USB-devices have a USB-icon to their right: ![usb icon](/attachment/doc/generic-usb.png)
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 ![eject icon](/attachment/doc/media-eject.png) 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.