From dc0819594baa7b2e4ecb28672495e49ba975cb04 Mon Sep 17 00:00:00 2001 From: qubesbugreport <112062467+qubesbugreport@users.noreply.github.com> Date: Thu, 1 Sep 2022 07:32:52 +0200 Subject: [PATCH 01/53] Use sentence case instead of title case As required by the style guide --- user/how-to-guides/how-to-use-usb-devices.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/user/how-to-guides/how-to-use-usb-devices.md b/user/how-to-guides/how-to-use-usb-devices.md index e515231f..c3db0601 100644 --- a/user/how-to-guides/how-to-use-usb-devices.md +++ b/user/how-to-guides/how-to-use-usb-devices.md @@ -28,9 +28,9 @@ 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/u2f-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. @@ -48,7 +48,7 @@ Hover on the attached device to display a list of running VMs. 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. @@ -87,14 +87,14 @@ 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`. @@ -111,13 +111,13 @@ 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. From 2b24640962d12880aa91c93a478d0b71d4553444 Mon Sep 17 00:00:00 2001 From: qubesbugreport <112062467+qubesbugreport@users.noreply.github.com> Date: Thu, 1 Sep 2022 08:00:33 +0200 Subject: [PATCH 02/53] Add instructions for using Qube Manager Using the Qube Manager to determine USB controller and address --- user/how-to-guides/how-to-use-usb-devices.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/user/how-to-guides/how-to-use-usb-devices.md b/user/how-to-guides/how-to-use-usb-devices.md index c3db0601..f845f89e 100644 --- a/user/how-to-guides/how-to-use-usb-devices.md +++ b/user/how-to-guides/how-to-use-usb-devices.md @@ -123,6 +123,10 @@ Some USB devices are not compatible with the USB pass-through method Qubes emplo 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. +You can find your controller and its BDF address using either of two methods described below. Using the command-line tools lsusb and readlink or by using the Qube Manager GUI. It is possible that on some system configurations the readlink method produces output which is different from the example below, while the Qube Manager method allows one to easily determine the correct controller and BDF address. + +#### Method 1: Using 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): @@ -155,6 +159,8 @@ This should output something like: ../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3 ``` +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 method 2 using the Qube Manager instead. + 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 @@ -162,3 +168,17 @@ For example, On R 4.0 the command would look something like ``` qvm-pci attach --persistent personal dom0:00_1a.0 ``` + +#### Method 2: Using the Qube Manager + +Open the Qube Manager, then right click on one of the VMs 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 name of manufacturer. + +Now you should be able to tell which is the correct BDF address of the mainboard USB controller or the added USB controller. From 9eb7926ffe515a044d0f4ec31ca9eecb5c54bc09 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 23 Nov 2022 17:34:08 -0800 Subject: [PATCH 03/53] Update and improve Emergency backup restore v4 page - Update formatting and style to be consistent with the rest of the docs - Improve language - Clarify instructions - Improve organization --- .../backup-emergency-restore-v4.md | 109 ++++++++---------- 1 file changed, 47 insertions(+), 62 deletions(-) diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md index 19367a24..38df4b12 100644 --- a/user/how-to-guides/backup-emergency-restore-v4.md +++ b/user/how-to-guides/backup-emergency-restore-v4.md @@ -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 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 @@ -66,17 +70,19 @@ on any GNU/Linux system. [user@restore ~]$ rpmdev-extract scrypt-*.rpm - 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. (Optional) If you're working with binaries that you saved with your backup, + such as `scrypt` or `bzip2`, you can make things easier by aliasing those + binaries now, e.g., + + [user@restore ~]$ alias scrypt="/home/user/scrypt-*" + [user@restore ~]$ alias bzip2="/home/user/bzip2-*" + + 2. Untar the main backup file. [user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456 backup-header @@ -90,32 +96,15 @@ Emergency Recovery Instructions 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. + 3. 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. [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`. + 4. Verify the integrity of `backup-header`. For compatibility reasons, + `backup-header.hmac` is an encrypted *and integrity protected* version of + `backup-header`. [user@restore ~]$ set +H [user@restore ~]$ echo "backup-header!$backup_pass" |\ @@ -123,28 +112,31 @@ 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`: + 5. 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=20161020T123455-1234 - 5. Set `backup_id` to the value in the last line of `backup-header`: + 6. 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 - 6. Verify the integrity of your data, decrypt, decompress, and extract - `private.img`: + 7. Choose a qube whose data you wish to restore. Verify the data's integrity, + decrypt it, decompress it, and extract it. [user@restore ~]$ find vm1 -name 'private.img.*.enc' | sort -V | while read f_enc; do \ f_dec=${f_enc%.enc}; \ @@ -157,24 +149,17 @@ 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. + This information is contained in `backup-header` (see step 5). For example, + if your backup is compressed with `bzip2`, use `bzip2 -d` instead of `gzip + -d` in the command above. - 7. Mount `private.img` and access your data. + 8. Enter the decrypted directory, mount `private.img`, and access your data. + [user@restore ~]$ cd vm1/ [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! - 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. - - **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: - - https://github.com/QubesOS/qubes-doc.git +Success! If you wish to recover data from more than one qube in your backup, +simply repeat steps 7 and 8 for each additional qube. From b6c99d486bf7fb38f9958dabb56107cf20223e7d Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 23 Nov 2022 17:53:29 -0800 Subject: [PATCH 04/53] Fix typo --- user/how-to-guides/backup-emergency-restore-v4.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md index 38df4b12..026de11f 100644 --- a/user/how-to-guides/backup-emergency-restore-v4.md +++ b/user/how-to-guides/backup-emergency-restore-v4.md @@ -19,8 +19,8 @@ GNU/Linux system by following the instructions on this page. **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 the [qubes-doc](https://github.com/QubesOS/qubes-doc) -Git repository. +plain text format in the [qubes-doc](https://github.com/QubesOS/qubes-doc) Git +repository. ## Required `scrypt` utility From 39342e8c98066603839d7f77ce0416e4af439b75 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 23 Nov 2022 17:55:04 -0800 Subject: [PATCH 05/53] Clarify example --- user/how-to-guides/backup-emergency-restore-v4.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md index 026de11f..1caa526b 100644 --- a/user/how-to-guides/backup-emergency-restore-v4.md +++ b/user/how-to-guides/backup-emergency-restore-v4.md @@ -135,8 +135,8 @@ any GNU/Linux system. [user@restore ~]$ backup_id=20161020T123455-1234 - 7. Choose a qube whose data you wish to restore. Verify the data's integrity, - decrypt it, decompress it, and extract it. + 7. Choose a qube whose data you wish to restore (in this example, `vm1`). + Verify the data's integrity, decrypt it, decompress it, and extract it. [user@restore ~]$ find vm1 -name 'private.img.*.enc' | sort -V | while read f_enc; do \ f_dec=${f_enc%.enc}; \ From c5314bed7f3001996c10458145cc5ba4a0ebaad8 Mon Sep 17 00:00:00 2001 From: zenkuro <42751749+zenkuro@users.noreply.github.com> Date: Thu, 5 Jan 2023 22:57:18 -0500 Subject: [PATCH 06/53] Eetend VPN troubleshooting by notify-send case There are guides and scripts on internet that are helping to configure and run VPN service on QubesOS This record provides explanation how to identify and what to do to fix possible issues with notify-send that being used by this guides. --- user/troubleshooting/vpn-troubleshooting.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/user/troubleshooting/vpn-troubleshooting.md b/user/troubleshooting/vpn-troubleshooting.md index d63bbe0c..d06eb5d1 100644 --- a/user/troubleshooting/vpn-troubleshooting.md +++ b/user/troubleshooting/vpn-troubleshooting.md @@ -31,3 +31,20 @@ After suspend/resume, OpenVPN may not automatically reconnect. In order to get i After setting up OpenVPN and restarting the VM, you may be repeatedly getting the popup "Ready to start link", but the VPN isn't connected. To figure out the root of the problem, check the VPN logs in `/var/logs/syslog`. The log may reveal issues like missing OpenVPN libraries, which you can then install. + +## `notify-send` induced failure +[Some VPN guides](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md) use complex scripts that by themselves include call of `notify-send`, yet some images may not contain this tool or may not have it working properly. +For instance calling `notify-send` on `fedora-36` template VM gives: +``` +Failed to execute child process “dbus-launch” (No such file or directory) +``` + +To check this tool is working properly run: +```bash +sudo notify-send "$(hostname): Test notify-send OK" --icon=network-idle +``` +You should see `info` message appear on the top of your scree. +If that is the case then, `notify-send` is not the issue. +If it is not, and you have an error of some sort you can: +1. Remove all calls of `notify-send` from scripts you are using to start VPN +2. Use other template VM that have `notify-send` working or find proper guide and make your current template VM run `notify-send` work properly. From a65a507db57fc5166163f05c4f1244edcd5bf3fa Mon Sep 17 00:00:00 2001 From: zenkuro <42751749+zenkuro@users.noreply.github.com> Date: Sat, 7 Jan 2023 02:47:34 -0500 Subject: [PATCH 07/53] Update vpn-troubleshooting.md Fix typo --- user/troubleshooting/vpn-troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user/troubleshooting/vpn-troubleshooting.md b/user/troubleshooting/vpn-troubleshooting.md index d06eb5d1..4671066c 100644 --- a/user/troubleshooting/vpn-troubleshooting.md +++ b/user/troubleshooting/vpn-troubleshooting.md @@ -43,7 +43,7 @@ To check this tool is working properly run: ```bash sudo notify-send "$(hostname): Test notify-send OK" --icon=network-idle ``` -You should see `info` message appear on the top of your scree. +You should see `info` message appear on the top of your screen. If that is the case then, `notify-send` is not the issue. If it is not, and you have an error of some sort you can: 1. Remove all calls of `notify-send` from scripts you are using to start VPN From edbfa3c9b6fc133af765687e796520118cd7f3dc Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Tue, 11 Apr 2023 16:35:19 -0700 Subject: [PATCH 08/53] Update user/how-to-guides/backup-emergency-restore-v4.md Co-authored-by: Rusty Bird --- user/how-to-guides/backup-emergency-restore-v4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md index 1caa526b..ce04ba70 100644 --- a/user/how-to-guides/backup-emergency-restore-v4.md +++ b/user/how-to-guides/backup-emergency-restore-v4.md @@ -79,7 +79,7 @@ any GNU/Linux system. such as `scrypt` or `bzip2`, you can make things easier by aliasing those binaries now, e.g., - [user@restore ~]$ alias scrypt="/home/user/scrypt-*" + [user@restore ~]$ alias scrypt="$PWD/scrypt-*/usr/bin/scrypt" [user@restore ~]$ alias bzip2="/home/user/bzip2-*" 2. Untar the main backup file. From f43e54f3a5736f9ce972e0d4889dd42cc0dfff4d Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Tue, 11 Apr 2023 16:42:34 -0700 Subject: [PATCH 09/53] Remove unnecessary example and step Per @rustybird's suggestions on #1279 --- user/how-to-guides/backup-emergency-restore-v4.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md index ce04ba70..f3ca1129 100644 --- a/user/how-to-guides/backup-emergency-restore-v4.md +++ b/user/how-to-guides/backup-emergency-restore-v4.md @@ -76,11 +76,10 @@ any GNU/Linux system. *compressed*. 1. (Optional) If you're working with binaries that you saved with your backup, - such as `scrypt` or `bzip2`, you can make things easier by aliasing those - binaries now, e.g., + such as `scrypt`, you can make things easier by aliasing those binaries now, + e.g., [user@restore ~]$ alias scrypt="$PWD/scrypt-*/usr/bin/scrypt" - [user@restore ~]$ alias bzip2="/home/user/bzip2-*" 2. Untar the main backup file. @@ -155,10 +154,9 @@ any GNU/Linux system. 8. Enter the decrypted directory, mount `private.img`, and access your data. - [user@restore ~]$ cd vm1/ - [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 + [user@restore]$ sudo mkdir /mnt/img + [user@restore]$ sudo mount -o loop vm1/private.img /mnt/img/ + [user@restore]$ cat /mnt/img/home/user/your_data.txt This data has been successfully recovered! Success! If you wish to recover data from more than one qube in your backup, From 3b550699afcd692e63c1a554a1dfdf6619f93aa7 Mon Sep 17 00:00:00 2001 From: Rusty Bird Date: Thu, 13 Apr 2023 06:47:22 +0000 Subject: [PATCH 10/53] Emergency backup restore v4 tweaks --- .../backup-emergency-restore-v4.md | 76 ++++++++++--------- 1 file changed, 41 insertions(+), 35 deletions(-) diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md index f3ca1129..54844e96 100644 --- a/user/how-to-guides/backup-emergency-restore-v4.md +++ b/user/how-to-guides/backup-emergency-restore-v4.md @@ -66,44 +66,33 @@ 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" ## Emergency recovery instructions **Note:** In the following example, the backup file is both *encrypted* and *compressed*. - 1. (Optional) If you're working with binaries that you saved with your backup, - such as `scrypt`, you can make things easier by aliasing those binaries now, - e.g., + 1. Untar the backup metadata from the main backup file. - [user@restore ~]$ alias scrypt="$PWD/scrypt-*/usr/bin/scrypt" - - 2. Untar the main backup file. - - [user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456 + [user@restore ~]$ tar -i -xvf qubes-backup-2015-06-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 - 3. Set the backup passphrase environment variable. While this isn't strictly + 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. [user@restore ~]$ read -r backup_pass - 4. Verify the integrity of `backup-header`. For compatibility reasons, - `backup-header.hmac` is an encrypted *and integrity protected* version of - `backup-header`. + 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" |\ @@ -118,7 +107,7 @@ any GNU/Linux system. - [Emergency Backup Recovery without Qubes (v2)](/doc/backup-emergency-restore-v2/) - [Emergency Backup Recovery without Qubes (v3)](/doc/backup-emergency-restore-v3/) - 5. Read `backup-header`. + 4. Read `backup-header`. [user@restore ~]$ cat backup-header version=4 @@ -128,36 +117,53 @@ any GNU/Linux system. hmac-algorithm=scrypt backup-id=20161020T123455-1234 - 6. Set `backup_id` to the value in the last line of `backup-header`. (Note that + 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 - 7. Choose a qube whose data you wish to restore (in this example, `vm1`). - Verify the data's integrity, decrypt it, decompress it, and extract it. + 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. **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 5). For example, + This information is contained in `backup-header` (see step 4). For example, if your backup is compressed with `bzip2`, use `bzip2 -d` instead of `gzip -d` in the command above. - 8. Enter the decrypted directory, mount `private.img`, and access your data. + 7. Search inside of `qubes.xml` for the `backup-path` property of the qube + whose data you wish to restore. Using the value of this property (e.g. + `vm123`), untar the necessary data files: - [user@restore]$ sudo mkdir /mnt/img - [user@restore]$ sudo mount -o loop vm1/private.img /mnt/img/ - [user@restore]$ cat /mnt/img/home/user/your_data.txt + [user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456 vm123 + + 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 ~]$ cat /mnt/img/home/user/your_data.txt This data has been successfully recovered! Success! If you wish to recover data from more than one qube in your backup, -simply repeat steps 7 and 8 for each additional qube. +simply repeat steps 7, 8, and 9 for each additional qube. From 034976f80fe61562412a2ae3d18fb7adb7093f77 Mon Sep 17 00:00:00 2001 From: Rusty Bird Date: Fri, 14 Apr 2023 16:28:59 +0000 Subject: [PATCH 11/53] Use vm123/ with a trailing slash like in the backup-path value --- user/how-to-guides/backup-emergency-restore-v4.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md index 54844e96..2cf18a51 100644 --- a/user/how-to-guides/backup-emergency-restore-v4.md +++ b/user/how-to-guides/backup-emergency-restore-v4.md @@ -140,13 +140,13 @@ any GNU/Linux system. 7. Search inside of `qubes.xml` for the `backup-path` property of the qube whose data you wish to restore. Using the value of this property (e.g. - `vm123`), untar the necessary data files: + `vm123/`), untar the necessary data files: - [user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456 vm123 + [user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456 vm123/ 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 \ + [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 From 35b16e2e372a80ccd81e9c4e4d5b87a56a507a49 Mon Sep 17 00:00:00 2001 From: Rusty Bird Date: Fri, 14 Apr 2023 16:29:00 +0000 Subject: [PATCH 12/53] Mention installing the compression program --- user/how-to-guides/backup-emergency-restore-v4.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md index 2cf18a51..ea47708f 100644 --- a/user/how-to-guides/backup-emergency-restore-v4.md +++ b/user/how-to-guides/backup-emergency-restore-v4.md @@ -136,7 +136,8 @@ any GNU/Linux system. 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 of `gzip - -d` in the command above. + -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. Search inside of `qubes.xml` for the `backup-path` property of the qube whose data you wish to restore. Using the value of this property (e.g. From 51d387a9fe935781d741eafcec818472d4e235a0 Mon Sep 17 00:00:00 2001 From: Rusty Bird Date: Sat, 15 Apr 2023 10:45:27 +0000 Subject: [PATCH 13/53] Add xmlstarlet command Also update the backup filename's date to avoid anachronisms in the resulting example qube list (e.g. a backup of fedora-37 in 2015) --- .../backup-emergency-restore-v4.md | 38 ++++++++++++++++--- 1 file changed, 33 insertions(+), 5 deletions(-) diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md index ea47708f..b42d400b 100644 --- a/user/how-to-guides/backup-emergency-restore-v4.md +++ b/user/how-to-guides/backup-emergency-restore-v4.md @@ -79,7 +79,7 @@ any GNU/Linux system. 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 @@ -139,11 +139,39 @@ any GNU/Linux system. -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. Search inside of `qubes.xml` for the `backup-path` property of the qube - whose data you wish to restore. Using the value of this property (e.g. - `vm123/`), untar the necessary data files: + 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 ~]$ tar -i -xvf qubes-backup-2015-06-05T123456 vm123/ + [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 + untrusted + vault vm321/ + whonix-gw-16 + whonix-ws-16 + whonix-ws-16-dvm + work + + 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: + + [user@restore ~]$ tar -i -xvf qubes-backup-2023-04-05T123456 vm123/ 8. Verify and decrypt the backed up data, decompress it, and extract it. From 0251ed63d5d63474d5ce9dadedec3b270448ba50 Mon Sep 17 00:00:00 2001 From: Rusty Bird Date: Sat, 15 Apr 2023 11:08:35 +0000 Subject: [PATCH 14/53] Update to a plausible timestamp in the backup ID too --- user/how-to-guides/backup-emergency-restore-v4.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md index b42d400b..0d318b5e 100644 --- a/user/how-to-guides/backup-emergency-restore-v4.md +++ b/user/how-to-guides/backup-emergency-restore-v4.md @@ -115,13 +115,13 @@ any GNU/Linux system. compressed=True compression-filter=gzip hmac-algorithm=scrypt - backup-id=20161020T123455-1234 + backup-id=20230405T123455-1234 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 and decrypt, decompress, and extract the `qubes.xml` file. From d4778384da7ae12bec3cd691b88cacb8900d9090 Mon Sep 17 00:00:00 2001 From: Rusty Bird Date: Sat, 15 Apr 2023 16:05:47 +0000 Subject: [PATCH 15/53] Add sys-whonix to example qube list --- user/how-to-guides/backup-emergency-restore-v4.md | 1 + 1 file changed, 1 insertion(+) diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md index 0d318b5e..92b4866c 100644 --- a/user/how-to-guides/backup-emergency-restore-v4.md +++ b/user/how-to-guides/backup-emergency-restore-v4.md @@ -158,6 +158,7 @@ any GNU/Linux system. sys-firewall sys-net sys-usb + sys-whonix untrusted vault vm321/ whonix-gw-16 From f24299be1ebdd81a5acb6af66967104955ae885a Mon Sep 17 00:00:00 2001 From: Oni Date: Wed, 7 Jun 2023 05:59:45 -0400 Subject: [PATCH 16/53] Use 'qvm-template' to uninstall templates The 'dnf remove' command no longer removes templates and mentions "No Match" when using . The 'qvm-template' command will remove templates from both package installation and cloning. 'qvm-template' also warns about qubes dependent on the template which reduces the need for the user to preemptively check that relationship. In its implementation, 'qvm-template' imports and calls 'qvm-remove' to remove the template. 'qvm-template' was selected as the command to present as it provides a more consistent interface when installing, listing, and removing among other commands. --- user/templates/templates.md | 27 +++++++++------------------ 1 file changed, 9 insertions(+), 18 deletions(-) diff --git a/user/templates/templates.md b/user/templates/templates.md index f3740dec..30e40635 100644 --- a/user/templates/templates.md +++ b/user/templates/templates.md @@ -144,28 +144,19 @@ Please see [How to Install Software](/doc/how-to-install-software). ## Uninstalling -If you want to remove a template you must make sure that it is not being used. -You should check that the template is not being used by any qubes, -and also that it is not set as the default template. - -The procedure for uninstalling a template depends on how it was created. - -If the template was originaly created by cloning another template, then you can -delete it the same way as you would any other qube. In the Qube Manager, -right-click on the template and select **Delete qube**. (If you're not sure, -you can safely try this method first to see if it works.) - -If, on the other hand, the template came pre-installed or was installed by -installing a template package in dom0, per the instructions -[above](#installing), then you must execute the following type of command in -dom0 in order to uninstall it: +To remove a template, the graphical `Qube Manager` (Qubes Menu > Qubes Tools > Qube Manager) may be used. Right-click the template to be uninstalled and click "Delete qube" to begin removal. +Alternatively, to remove a template via the command line in dom0: ``` -$ sudo dnf remove qubes-template-- +$ qvm-template remove ``` -`qubes-template--` is the name of the desired -template package. +\ is the first column from the output of: +``` +$ qvm-template list --installed +``` + +In either case, if another qube is based on the template, the template will remain installed and a list of the dependent qubes will be displayed. [Switch](#switching) the dependent qubes to another template before attempting the removal again. You may see warning messages like the following: From e1abb55e638ce29bf8ae17f504a83b4ba024e101 Mon Sep 17 00:00:00 2001 From: Oni Date: Mon, 19 Jun 2023 06:26:18 -0400 Subject: [PATCH 17/53] Retire template removal warning messages This section was added in response to: https://github.com/QubesOS/qubes-issues/issues/6432 Seven months later, 'qvm-template' became the installation redirection target: https://github.com/QubesOS/qubes-core-admin-linux/pull/80 Now that 'dnf remove' is not being called directly, these warnings should not be an issue. --- user/templates/templates.md | 26 -------------------------- 1 file changed, 26 deletions(-) diff --git a/user/templates/templates.md b/user/templates/templates.md index 30e40635..a15bfc16 100644 --- a/user/templates/templates.md +++ b/user/templates/templates.md @@ -158,32 +158,6 @@ $ qvm-template list --installed In either case, if another qube is based on the template, the template will remain installed and a list of the dependent qubes will be displayed. [Switch](#switching) the dependent qubes to another template before attempting the removal again. -You may see warning messages like the following: - -``` -warning: file /var/lib/qubes/vm-templates/fedora-XX/whitelisted-appmenus.list: remove failed: No such file or directory -warning: file /var/lib/qubes/vm-templates/fedora-XX/vm-whitelisted-appmenus.list: remove failed: No such file or directory -warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.04: remove failed: No such file or directory -warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.03: remove failed: No such file or directory -warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.02: remove failed: No such file or directory -warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.01: remove failed: No such file or directory -warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.00: remove failed: No such file or directory -warning: file /var/lib/qubes/vm-templates/fedora-XX/netvm-whitelisted-appmenus.list: remove failed: No such file or directory -warning: file /var/lib/qubes/vm-templates/fedora-XX/icon.png: remove failed: No such file or directory -warning: file /var/lib/qubes/vm-templates/fedora-XX/clean-volatile.img.tar: remove failed: No such file or directory -warning: file /var/lib/qubes/vm-templates/fedora-XX/apps.templates: remove failed: No such file or directory -warning: file /var/lib/qubes/vm-templates/fedora-XX/apps.tempicons: remove failed: No such file or directory -warning: file /var/lib/qubes/vm-templates/fedora-XX/apps: remove failed: No such file or directory -warning: file /var/lib/qubes/vm-templates/fedora-XX: remove failed: No such file or directory -``` - -These are normal and expected. Nothing is wrong, and no action is required to -address these warnings. - -If the uninstallation command doesn't work, pay close attention to -any error message: it may tell you what qube is using the template, -or if the template is default. In other cases, please see [VM Troubleshooting](/doc/vm-troubleshooting/). - If the Applications Menu entry doesn't go away after you uninstall a template, execute the following type of command in dom0: From 781780f07e7bd24618bfef64e650f482fd914b16 Mon Sep 17 00:00:00 2001 From: Oni Date: Mon, 19 Jun 2023 06:59:06 -0400 Subject: [PATCH 18/53] Redirect Qubes Menu issues with template uninstallation Manually removing Qubes Menu entries is covered on the linked page. --- user/templates/templates.md | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/user/templates/templates.md b/user/templates/templates.md index a15bfc16..7bd6a9a3 100644 --- a/user/templates/templates.md +++ b/user/templates/templates.md @@ -158,19 +158,7 @@ $ qvm-template list --installed In either case, if another qube is based on the template, the template will remain installed and a list of the dependent qubes will be displayed. [Switch](#switching) the dependent qubes to another template before attempting the removal again. -If the Applications Menu entry doesn't go away after you uninstall a template, -execute the following type of command in dom0: - -``` -$ rm ~/.local/share/applications/ -``` - -Applications Menu entries for backups of removed qubes can also be found in -`/usr/local/share/applications/` of dom0. - -``` -$ rm /usr/local/share/applications/ -``` +If the template's entry in the Qubes Menu is not removed with its uninstallation, consult the [troubleshooting page](/doc/app-menu-shortcut-troubleshooting/#fixing-shortcuts). ## Reinstalling From 1e7a9f7437f6428e9fba97be3dea67de172a80b3 Mon Sep 17 00:00:00 2001 From: Oni Date: Mon, 19 Jun 2023 08:42:59 -0400 Subject: [PATCH 19/53] Address two potential issues raised when removing a template Mentioned the final confirmation step asked for by the `Qube Manager` to type the template's name. However, before this final confirmation is displayed, issues may be raised. Deleting templates may run afoul of dependent qubes and the "default_template" global property. Instructions to resolve via switching are linked. --- user/templates/templates.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/user/templates/templates.md b/user/templates/templates.md index 7bd6a9a3..651c7a88 100644 --- a/user/templates/templates.md +++ b/user/templates/templates.md @@ -144,7 +144,7 @@ Please see [How to Install Software](/doc/how-to-install-software). ## Uninstalling -To remove a template, the graphical `Qube Manager` (Qubes Menu > Qubes Tools > Qube Manager) may be used. Right-click the template to be uninstalled and click "Delete qube" to begin removal. +To remove a template, the graphical `Qube Manager` (Qubes Menu > Qubes Tools > Qube Manager) may be used. Right-click the template to be uninstalled and click "Delete qube" to begin removal. If no issues are found, a dialog box will request the template's name be typed as a final confirmation. Upon completion, the template will be deleted. Alternatively, to remove a template via the command line in dom0: ``` @@ -156,7 +156,7 @@ $ qvm-template remove $ qvm-template list --installed ``` -In either case, if another qube is based on the template, the template will remain installed and a list of the dependent qubes will be displayed. [Switch](#switching) the dependent qubes to another template before attempting the removal again. +In either case, issues with template removal may be raised. If an issue is raised, the template will remain installed and a list of concerns displayed. "Global property default_template" requires [switching](#switching) the default_template property to another template. "Template for" can be resolved by [switching](#switching) the dependent qubes' template. Once the issues are addressed, attempt the removal again. If the template's entry in the Qubes Menu is not removed with its uninstallation, consult the [troubleshooting page](/doc/app-menu-shortcut-troubleshooting/#fixing-shortcuts). From 6e15603483b02bef6ae8f76fca78be3bc93b353e Mon Sep 17 00:00:00 2001 From: Rusty Bird Date: Tue, 20 Jun 2023 13:52:30 +0000 Subject: [PATCH 20/53] Clarify reading the passphrase https://forum.qubes-os.org/t/getting-stuck-on-emergency-backup-recovery/18520/5 https://forum.qubes-os.org/t/getting-stuck-on-emergency-backup-recovery/18520/6 --- user/how-to-guides/backup-emergency-restore-v4.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md index 92b4866c..8688f5b0 100644 --- a/user/how-to-guides/backup-emergency-restore-v4.md +++ b/user/how-to-guides/backup-emergency-restore-v4.md @@ -91,6 +91,8 @@ any GNU/Linux system. [user@restore ~]$ read -r backup_pass + 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`). From 0aee55a8dd6b29a0a55006532c046b56e04c5416 Mon Sep 17 00:00:00 2001 From: Rusty Bird Date: Tue, 20 Jun 2023 13:52:31 +0000 Subject: [PATCH 21/53] Use ls instead of cat to show example data https://forum.qubes-os.org/t/getting-stuck-on-emergency-backup-recovery/18520/5 --- user/how-to-guides/backup-emergency-restore-v4.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md index 8688f5b0..d4baa698 100644 --- a/user/how-to-guides/backup-emergency-restore-v4.md +++ b/user/how-to-guides/backup-emergency-restore-v4.md @@ -194,8 +194,9 @@ any GNU/Linux system. [user@restore ~]$ sudo mkdir /mnt/img [user@restore ~]$ sudo mount -o loop vm123/private.img /mnt/img/ - [user@restore ~]$ cat /mnt/img/home/user/your_data.txt - This data has been successfully recovered! + [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. From 108fb1e106a65e0d5c0a7f13913be8fd288a62d0 Mon Sep 17 00:00:00 2001 From: chomiczosc <155738605+chomiczosc@users.noreply.github.com> Date: Fri, 5 Jan 2024 15:26:36 +0100 Subject: [PATCH 22/53] Update getting-started.md - simplifying "Getting started section" to make it more comprehensible - updating the section to match Qubes 4.2 --- introduction/getting-started.md | 135 +++++++++++++++----------------- 1 file changed, 64 insertions(+), 71 deletions(-) diff --git a/introduction/getting-started.md b/introduction/getting-started.md index 1ac922d5..92409e27 100644 --- a/introduction/getting-started.md +++ b/introduction/getting-started.md @@ -18,14 +18,13 @@ Dive right in to [organizing your qubes](/doc/how-to-organize-your-qubes/).) ## The Basics -Qubes OS is an operating system built out of securely-isolated compartments -called [qubes](/doc/glossary/#qube). For example, you might have a work qube, a -personal qube, a banking qube, a web browsing qube, and so on. You can have as -many qubes as you want! Most of the time, you'll be using an [app -qube](/doc/glossary/#app-qube), which is a qube intended for running software +Qubes OS is an operating system built out of securely-isolated compartments, or [qubes](/doc/glossary/#qube). +You can have a work qube, a personal qube, a banking qube, a web browsing qube, a standalone Windows qube and so on. +You can have as many qubes as you want! Most of the time, you'll be using an [app +qube](/doc/glossary/#app-qube), a qube for running software programs like web browsers, email clients, and word processors. Each app qube is based on another type of qube called a [template](/doc/glossary/#template). -More than one qube can be based on the same template. Importantly, a qube +The same template can be a base for various cubes. Importantly, a qube cannot modify its template in any way. This means that, if a qube is ever compromised, its template and any other qubes based on that template will remain safe. This is what makes Qubes OS so secure. Even if an attack is @@ -35,9 +34,8 @@ Suppose you want to use your favorite web browser in several different qubes. You'd install the web browser in a template, then every qube based on that template would be able to run the web browser software (while still being forbidden from modifying the template and any other qubes). This way, you only -have to install the web browser a single time, and updating the template serves -to update all the qubes based on it. This elegant design saves time and space -while enhancing security. +have to install the web browser a single time, and updating the template updates all the qubes based on it. +This elegant design saves time and space while enhancing security. There are also some "helper" qubes in your system. Each qube that connects to the Internet does so through a network-providing [service @@ -54,27 +52,24 @@ corresponding version number. There are many ready-to-use many as you like. Last but not least, there's a very special [admin -qube](/doc/glossary/#admin-qube) which, as the name suggests, is used to -administer your entire system. There's only one admin qube, and it's called -[dom0](/doc/glossary/#dom0). You can think of it as the master qube, holding -ultimate power over everything that happens in Qubes OS. Dom0 is more trusted -than any other qube. If dom0 were ever compromised, it would be "game over." -The entire system would effectively be compromised. That's why everything in -Qubes OS is specifically designed to protect dom0 and ensure that doesn't +qube](/doc/glossary/#admin-qube) used to administer your entire system. +There's only one admin qube, and it's called [dom0](/doc/glossary/#dom0). +You can think of it as the master qube, holding ultimate power over everything that happens in Qubes OS. +Dom0 is the most trusted one of all qubes. If dom0 were ever to be compromised, it would be "game over"- an effective compromise of the entire system. +That's why everything in Qubes OS is specifically designed to protect dom0 and ensure that doesn't happen. Due to its overarching importance, dom0 has no network connectivity and is used only for running the [desktop environment](https://en.wikipedia.org/wiki/Desktop_environment) and [window manager](https://en.wikipedia.org/wiki/Window_manager). Dom0 should never be used for anything else. In particular, you should never run user applications -in dom0. (That's what your app qubes are for!) +in dom0. (That's what your app qubes are for!) In short, do not interact directly with dom0 in any way, shape or form. ### Color & Security You'll choose a **color** for each of your qubes out of a predefined set of -colors. Each window on your desktop will have its frame colored according to -the color of that qube. These colored frames help you keep track of which qube -each window belongs to and how trustworthy it is. This is especially helpful -when you have the same app running in multiple qubes at the same time. For +colors. The color of the frame of each window on your desktop will correspond to the color of that cube. +These colored frames help you keep track of which qube you're currently using and how trustworthy it is. This is especially helpful +when you have the same program running in multiple qubes at the same time. For example, if you're logged in to your bank account in one qube while doing some random web surfing in a different qube, you wouldn't want to accidentally enter your banking password in the latter! The colored frames help to avoid such @@ -83,16 +78,16 @@ mistakes. [![snapshot_40.png](/attachment/doc/r4.0-snapshot_40.png)](/attachment/doc/r4.0-snapshot_40.png) Most Qubes users associate red with what's untrusted and dangerous (like a red -light: stop! danger!), green with what's safe and trusted, and yellow and -orange with things in the middle. This color scheme also extends to include -blue and black, which are usually interpreted as indicating progressively more -trusted domains than green, with black being ultimately trusted. Color and -associated meanings are ultimately up to you, however. The system itself does -not treat the colors differently. If you create two identical qubes --- black +stop light signalling danger), green with what's safe and trusted, and yellow and +orange with things in-between. This color scheme also includes +blue and black, commonly interpreted as indicating progressively more +trusted domains than green, with black being ultimately trusted. However, color and +associated meanings are entirely up to you. The system itself does +not treat the colors differently - they're all equally safe on their own. If you create two identical qubes --- black and red, say --- they'll be the same until you start using them differently. -Feel free to use the colors in whatever way is most useful to you. For example, +Feel free to use the colors in the way that best meets your needs. For example, you might decide to use three or four qubes for work activities and give them -all the same color --- or all different colors. It's entirely up to you. +all the same color --- or all different colors depending on the nature of the task they are used for. ### User Interface @@ -104,27 +99,24 @@ the window managers [i3](/doc/i3/) and [AwesomeWM](/doc/awesomewm/). [![r4.0-taskbar.png](/attachment/doc/r4.0-taskbar.png)](/attachment/doc/r4.0-taskbar.png) -The bar at the top of your screen in Qubes 4.0 includes the following XFCE +The bar at the top of your screen in Qubes 4.2 includes the following XFCE component areas: -- The **Tray**, where many functional widgets live. +- The **App Menu**, where you go to open an application within a qube, to open + a dom0 terminal, to access administrative UI tools such as the Qube Manager, + or to access settings panels for your desktop environment. +- The **Task Bar** where buttons for open and hidden windows live. - **Spaces**, an interface for [virtual desktops](https://en.wikipedia.org/wiki/Virtual_desktop). Virtual desktops do not have any inherent security isolation properties, but some users find them useful for organizing things. -- The **Task Bar** where buttons for open and hidden windows live. -- The **App Menu**, where you go to open an application within a qube, to open - a dom0 terminal, to access administrative UI tools such as the Qube Manager, - or to access settings panels for your desktop environment. - -To learn more about how to customize your desktop environment, we recommend you -spend some time going through [XFCE's documentation](https://docs.xfce.org/). +- The **Tray**, where many functional widgets live. There are several tray widgets that are unique to Qubes OS: - The **Whonix SDWDate** allows you to control the Tor connection in your [`sys-whonix`](https://www.whonix.org/wiki/Qubes) qube. -- The **Qubes Clipboard** lets you easily copy text from dom0. +- The **Qubes Clipboard** lets you easily [copy text](https://wwwpreview.qubes-os.org/doc/how-to-copy-and-paste-text/) between various qubes and from dom0. - The **Qubes Devices** widget allows you to attach and detach devices --- such as USB drives and cameras --- to qubes. - The **Qubes Disk Space** widget shows you how much storage you're using. @@ -136,50 +128,57 @@ There are several tray widgets that are unique to Qubes OS: [![r4.1-widgets.png](/attachment/doc/r4.1-widgets.png)](/attachment/doc/r4.1-widgets.png) +To learn more about how to customize your desktop environment, we recommend you +go through [XFCE's documentation](https://docs.xfce.org/). + #### Qube Manager -To see all of your qubes at the same time, you can use the **Qube Manager** (go -to the App Menu → Qubes Tools → Qube Manager), which displays the states of -all the qubes in your system, even the ones that aren't running. +To see all of your qubes at the same time, you can use the **Qube Manager**. +It displays the states of all the qubes in your system, even the ones that aren’t running. + +To access Qube Manager go to: +Qubes Icon (App Menu) → Settings Icon → Qubes Tools → **Qube Manager** [![r4.0-qubes-manager.png](/attachment/doc/r4.0-qubes-manager.png)](/attachment/doc/r4.0-qubes-manager.png) #### Command-line interface -All aspects of Qubes OS can be controlled using command-line tools. Opening a -terminal emulator in dom0 can be done in several ways: +All aspects of Qubes OS can be controlled using command-line tools such as the terminal emulator. +The default terminal emulator in Qubes is Xfce Terminal. +Opening a terminal emulator in dom0 can be done in several ways: -- Go to the App Menu and select **Terminal Emulator** at the top. +- Go to the App Menu, click on the Settings icon, choose Other from the drop-down menu, and select **Xfce Terminal Emulator** at the bottom. - Press `Alt`+`F3` and search for `xfce terminal`. - Right-click on the desktop and select **Open Terminal Here**. -Terminal emulators can also be run in other qubes as normal programs. Various -command-line tools are described as part of this guide, and the whole reference -can be found [here](/doc/tools/). +Various command-line tools are described as part of this guide, and the whole reference can be found [here](/doc/tools/). +Terminal emulators can also be run in other qubes as normal programs. ## First boot When you install Qubes OS, a number of qubes are pre-configured for you: -- **Templates:** `fedora-XX` (`XX` being the version number) +- **App qubes** such as `work`, `personal`, `untrusted`, and `vault` are your "starter pack" qubes to compartmentalize tasks + and types of data to suit most basic needs. (There is nothing special about these pre-configured qubes - they are identical in nature to more specific ones you might wish to create later.) +- **Templates:** `fedora-XX`, `debian-XX` (`XX` being the version number) +- **Service qubes:** `sys-usb`, `sys-net`, `sys-firewall`, and `sys-whonix`) - **Admin qube:** `dom0` -- **Service qubes:** `sys-usb`, `sys-net`, `sys-firewall`, and `sys-whonix` -- **App qubes** configured to prioritize security by compartmentalizing tasks - and types of data: `work`, `personal`, `untrusted`, and `vault`. (There is - nothing special about these qubes. If you were to create a black qube and - name it `vault`, it would be the same as the pre-configured `vault` qube. - They're just suggestions to get you started. ) -A variety of open-source applications such as file managers, command-line -terminals, printer managers, text editors, and "applets" used to configure -different things like audio or parts of the user interface are also installed -by default—most within the templates. Most are bundled with each template. +Other software installed in Qubes OS by default includes open-source applications such as file managers, +command-line terminals, printer managers, text editors, and applets for configuring audio and user interface settings. +Most of these applications are incorporated within each template. ### Adding, removing, and listing qubes -You can easily create a new qube with the **Create Qubes VM** option in the App -Menu. If you need to add or remove qubes, simply use the Qube Manager's **Add** -and **Remove** buttons. You can also add, remove, and list qubes from the +To create a new qube or remove one, use **Create Qubes VM** option in the App Menu. + +Creating a New Qube: +Qubes Icon → Settings → Qubes Tools → Qube Manager → Create Qubes VM → **New Qube** + +Removing a qube: +To remove a qube, use the **Delete qube button** as the final step instead. + +You can also add, remove, and list qubes from the command line using the following tools: - `qvm-create` @@ -188,14 +187,8 @@ command line using the following tools: ### How many qubes do I need? -That's a great question, but there's no one-size-fits-all answer. It depends on -the structure of your digital life, and this is at least a little different for -everyone. If you plan on using your system for work, then it also depends on -what kind of job you do. - -It's a good idea to start out with the qubes created automatically by the -installer: `work`, `personal`, `untrusted`, and `vault`. If and when you start -to feel that some activity just doesn't fit into any of your existing qubes, or +It's a good idea to start out with the pre-installed app qubes: `work`, `personal`, `untrusted`, and `vault`. +If you start to feel that some activity just doesn't fit into any of your existing qubes, or you want to partition some part of your life, you can easily create a new qube for it. You'll also be able to easily [copy any files](/doc/how-to-copy-and-move-files) you need to the newly-created qube. @@ -252,5 +245,5 @@ GitHub](https://github.com/QubesOS). ## Documentation -Peruse our extensive library of [documentation](/doc/) for users and developers +Browse our extensive library of [documentation](/doc/) for users and developers of Qubes OS. You can even [help us improve it](/doc/how-to-edit-the-documentation/)! From 4a9ab9fac587590027d8330dcc25e6a825d93182 Mon Sep 17 00:00:00 2001 From: chomiczosc <155738605+chomiczosc@users.noreply.github.com> Date: Fri, 5 Jan 2024 15:45:08 +0100 Subject: [PATCH 23/53] Update getting-started.md Fixes from review --- introduction/getting-started.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/introduction/getting-started.md b/introduction/getting-started.md index 92409e27..4a02083c 100644 --- a/introduction/getting-started.md +++ b/introduction/getting-started.md @@ -24,7 +24,7 @@ You can have as many qubes as you want! Most of the time, you'll be using an [ap qube](/doc/glossary/#app-qube), a qube for running software programs like web browsers, email clients, and word processors. Each app qube is based on another type of qube called a [template](/doc/glossary/#template). -The same template can be a base for various cubes. Importantly, a qube +The same template can be a base for various qubes. Importantly, a qube cannot modify its template in any way. This means that, if a qube is ever compromised, its template and any other qubes based on that template will remain safe. This is what makes Qubes OS so secure. Even if an attack is @@ -62,7 +62,7 @@ is used only for running the [desktop environment](https://en.wikipedia.org/wiki/Desktop_environment) and [window manager](https://en.wikipedia.org/wiki/Window_manager). Dom0 should never be used for anything else. In particular, you should never run user applications -in dom0. (That's what your app qubes are for!) In short, do not interact directly with dom0 in any way, shape or form. +in dom0. (That's what your app qubes are for!) In short, be very careful when interacting with dom0. ### Color & Security From 3cec58bf7d108e4104c30c8b5e3942149e9e94d0 Mon Sep 17 00:00:00 2001 From: Piotr Bartman Date: Wed, 20 Mar 2024 22:20:01 +0100 Subject: [PATCH 24/53] q-dev: update docs --- developer/services/admin-api.md | 233 ++++++++++++++++++++------------ 1 file changed, 144 insertions(+), 89 deletions(-) diff --git a/developer/services/admin-api.md b/developer/services/admin-api.md index 0087bcaf..74314ed7 100644 --- a/developer/services/admin-api.md +++ b/developer/services/admin-api.md @@ -62,95 +62,98 @@ yet documented. The API should be implemented as a set of qrexec calls. This is to make it easy to set the policy using current mechanism. -| call | dest | argument | inside | return | note | -| ------------------------------------- | --------- | --------- | ----------------------------------------- | --------------------------------------------------------- | ---- | -| `admin.vmclass.List` | `dom0` | - | - | `\n` | -| `admin.vm.List` | `dom0|` | - | - | ` class= state=\n` | -| `admin.vm.Create.` | `dom0` | template | `name= label=