From 9eb7926ffe515a044d0f4ec31ca9eecb5c54bc09 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 23 Nov 2022 17:34:08 -0800 Subject: [PATCH 01/27] 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 02/27] 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 03/27] 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 edbfa3c9b6fc133af765687e796520118cd7f3dc Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Tue, 11 Apr 2023 16:35:19 -0700 Subject: [PATCH 04/27] 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 05/27] 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 06/27] 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 07/27] 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 08/27] 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 09/27] 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 10/27] 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 11/27] 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 12/27] 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 13/27] 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 14/27] 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 15/27] 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 16/27] 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 17/27] 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 ec1f501c538d5775edb0d082581d58cc19f08d3b Mon Sep 17 00:00:00 2001 From: apparatius <151992958+apparatius@users.noreply.github.com> Date: Fri, 12 Jul 2024 09:31:11 +0000 Subject: [PATCH 18/27] Update firewall.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The disappearance of the eth0 interface when you restart the net qube of the sys-firewall or set it’s net qube to none is causing `iif == "eth0"` to become `iif 2` and the rules won't work anymore. It’s better to use `iifgroup 1` instead of `iif == "eth0"`. Related discussion: https://forum.qubes-os.org/t/iptables-not-available-in-sys-net-in-qubes-os-4-2-1/26706/26 --- user/security-in-qubes/firewall.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/user/security-in-qubes/firewall.md b/user/security-in-qubes/firewall.md index 95b28673..0fc9a2f8 100644 --- a/user/security-in-qubes/firewall.md +++ b/user/security-in-qubes/firewall.md @@ -297,13 +297,13 @@ nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority fi Second step, code a natting firewall rule to route traffic on the outside interface for the service to the sys-firewall VM ``` -nft add rule qubes custom-dnat-qubeDEST iif == "ens6" ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z +nft add rule qubes custom-dnat-qubeDEST iifgroup 1 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z ``` Third step, code the appropriate new filtering firewall rule to allow new connections for the service ``` -nft add rule qubes custom-forward iif == "ens6" ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept +nft add rule qubes custom-forward iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept ``` > Note: If you do not wish to limit the IP addresses connecting to the service, remove `ip saddr 192.168.x.y/24` from the rules @@ -320,12 +320,12 @@ In this example, we can see 7 packets in the forward rule, and 3 packets in the ``` chain custom-forward { - iif "ens6" ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter packets 7 bytes 448 accept + iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter packets 7 bytes 448 accept } chain custom-dnat-qubeDEST { type nat hook prerouting priority filter + 1; policy accept; - iif "ens6" ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter packets 3 bytes 192 dnat to 10.138.33.59 + iifgroup 1 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter packets 3 bytes 192 dnat to 10.138.33.59 } ``` @@ -351,10 +351,10 @@ Content of `/rw/config/qubes-firewall-user-script` in `sys-net`: if nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }' then # create the dnat rule - nft add rule qubes custom-dnat-qubeDEST iif == "ens6" saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z + nft add rule qubes custom-dnat-qubeDEST iifgroup 1 saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z # allow forwarded traffic - nft add rule qubes custom-forward iif == "ens6" ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept + nft add rule qubes custom-forward iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept fi ~~~ @@ -371,13 +371,13 @@ nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority fi Second step, code a natting firewall rule to route traffic on the outside interface for the service to the destination qube ``` -nft add rule qubes custom-dnat-qubeDEST iif == "eth0" ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.0.xx +nft add rule qubes custom-dnat-qubeDEST iifgroup 1 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.0.xx ``` Third step, code the appropriate new filtering firewall rule to allow new connections for the service ``` -nft add rule qubes custom-forward iif == "eth0" ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept +nft add rule qubes custom-forward iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept ``` > Note: If you do not wish to limit the IP addresses connecting to the service, remove `ip saddr 192.168.x.y/24` from the rules @@ -398,10 +398,10 @@ Content of `/rw/config/qubes-firewall-user-script` in `sys-firewall`: if nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }' then # create the dnat rule - nft add rule qubes custom-dnat-qubeDEST iif == "eth0" tcp dport 443 ct state new,established,related counter dnat 10.137.0.xx + nft add rule qubes custom-dnat-qubeDEST iifgroup 1 tcp dport 443 ct state new,established,related counter dnat 10.137.0.xx # allow forwarded traffic - nft add rule qubes custom-forward iif == "eth0" ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept + nft add rule qubes custom-forward iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept fi ~~~ From 8ae7c2495886fa33c0b7fa63c5329bbc7fb796c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Sun, 20 Oct 2024 00:41:01 +0200 Subject: [PATCH 19/27] Update docs about /rw/config/rc.local* scripts Specify that files needs to be executable. Add info about `/rw/config/rc.local.d/*.rc`. Add info about `/rw/config/rc.local-early.d/*.rc` and `/rw/config/rc.local-early` (https://github.com/QubesOS/qubes-core-agent-linux/pull/386) --- user/advanced-topics/config-files.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/user/advanced-topics/config-files.md b/user/advanced-topics/config-files.md index 3ffdfd55..db8a7f07 100644 --- a/user/advanced-topics/config-files.md +++ b/user/advanced-topics/config-files.md @@ -19,7 +19,7 @@ That way, they can be used to customize a single VM instead of all VMs based on The scripts here all run as root. - `/rw/config/rc.local` - script runs at VM startup. - Good place to change some service settings, replace config files with its copy stored in `/rw/config`, etc. + Good place to change some service settings, replace config files with its copy stored in `/rw/config`, etc. The script need to have the executable permission set to be executed. Example usage: ~~~ @@ -33,6 +33,8 @@ The scripts here all run as root. echo '127.0.0.1 example.com' >> /etc/hosts ~~~ +- `/rw/config/rc.local.d/*.rc` - scripts run at VM startup just before `/rw/config/rc.local` +- `/rw/config/rc.local-early.d/*.rc`, `/rw/config/rc.local-early` - scripts similar to `/rw/config/rc.local`, but running earlier in the system startup sequence - just before `sysinit.target`, and setting up the network. - `/rw/config/qubes-ip-change-hook` - script runs in NetVM after every external IP change and on "hardware" link status change. - In ProxyVMs (or app qubes with `qubes-firewall` service enabled), scripts placed in the following directories will be executed in the listed order followed by `qubes-firewall-user-script` at start up. From 06e37e444b7d2745caf7e6cbf5e5854c26c3e722 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marta=20Marczykowska-G=C3=B3recka?= Date: Tue, 2 Jul 2024 16:37:26 +0200 Subject: [PATCH 20/27] Add intro for Builder v2 --- developer/building/development-workflow.md | 53 +++--- developer/building/qubes-builder-v2.md | 160 ++++++++++++++++++ developer/debugging/automated-tests.md | 2 +- developer/debugging/test-bench.md | 5 +- developer/general/gsoc.md | 4 +- introduction/faq.md | 2 +- .../testing.md | 2 +- user/templates/templates.md | 7 +- 8 files changed, 192 insertions(+), 43 deletions(-) create mode 100644 developer/building/qubes-builder-v2.md diff --git a/developer/building/development-workflow.md b/developer/building/development-workflow.md index dd72699a..e4967756 100644 --- a/developer/building/development-workflow.md +++ b/developer/building/development-workflow.md @@ -12,14 +12,14 @@ title: Development workflow A workflow for developing Qubes OS+ -First things first, setup [QubesBuilder](/doc/qubes-builder/). This guide -assumes you're using qubes-builder to build Qubes. +First things first, setup [QubesBuilder](/doc/qubes-builder-v2/). This guide +assumes you're using qubes-builder v2 to build Qubes. ## Repositories and committing Code Qubes is split into a bunch of git repos. These are all contained in the -`qubes-src` directory under qubes-builder. Subdirectories there are separate -components, stored in separate git repositories. +`artifacts/sources` directory under qubes-builder. Subdirectories there are +separate components, stored in separate git repositories. The best way to write and contribute code is to create a git repo somewhere (e.g., github) for the repo you are interested in editing (e.g., @@ -29,7 +29,7 @@ of Qubes, cd to the repo directory and add your repository as a remote in git **Example:** ~~~ -$ cd qubes-builder/qubes-src/qubes-manager +$ cd qubes-builder/artifacts/sources/qubes-manager $ git remote add abel git@github.com:abeluck/qubes-manager.git ~~~ @@ -47,7 +47,7 @@ include your public PGP key you use to sign your tags. #### Prepare fresh version of kernel sources, with Qubes-specific patches applied -In qubes-builder/qubes-src/linux-kernel: +In qubes-builder/artifacts/sources/linux-kernel: ~~~ make prep @@ -66,7 +66,7 @@ drwxr-xr-x 6 user user 4096 Nov 21 20:48 kernel-3.4.18/linux-obj #### Go to the kernel tree and update the version -In qubes-builder/qubes-src/linux-kernel: +In qubes-builder/artifacts/sources/linux-kernel: ~~~ cd kernel-3.4.18/linux-3.4.18 @@ -117,8 +117,6 @@ vi series.conf #### Building RPMs -TODO: Is this step generic for all subsystems? - Now it is a good moment to make sure you have changed kernel release name in rel file. For example, if you change it to '1debug201211116c' the resulting RPMs will be named @@ -131,34 +129,23 @@ your changes locally. To actually build RPMs, in qubes-builder: ~~~ -make linux-kernel +./qb -c linux-kernel package fetch prep build ~~~ -RPMs will appear in qubes-src/linux-kernel/pkgs/fc20/x86\_64: +RPMs will appear in +`artifacts/repository/destination_name/package_name` +(for example `artifacts/repository/host-fc37/linux-kernel-6.6.31-1.1/` -~~~ --rw-rw-r-- 1 user user 42996126 Nov 17 04:08 kernel-3.4.18-1debug20121116c.pvops.qubes.x86_64.rpm --rw-rw-r-- 1 user user 43001450 Nov 17 05:36 kernel-3.4.18-1debug20121117a.pvops.qubes.x86_64.rpm --rw-rw-r-- 1 user user 8940138 Nov 17 04:08 kernel-devel-3.4.18-1debug20121116c.pvops.qubes.x86_64.rpm --rw-rw-r-- 1 user user 8937818 Nov 17 05:36 kernel-devel-3.4.18-1debug20121117a.pvops.qubes.x86_64.rpm --rw-rw-r-- 1 user user 54490741 Nov 17 04:08 kernel-qubes-vm-3.4.18-1debug20121116c.pvops.qubes.x86_64.rpm --rw-rw-r-- 1 user user 54502117 Nov 17 05:37 kernel-qubes-vm-3.4.18-1debug20121117a.pvops.qubes.x86_64.rpm -~~~ +### Useful [QubesBuilder](/doc/qubes-builder-v2/) commands -### Useful [QubesBuilder](/doc/qubes-builder/) commands - -1. `make check` - will check if all the code was committed into repository and -if all repository are tagged with signed tag. -2. `make show-vtags` - show version of each component (based on git tags) - -mostly useful just before building ISO. **Note:** this will not show version -for components containing changes since last version tag. -3. `make push` - push change from **all** repositories to git server. You must -set proper remotes (see above) for all repositories first. -4. `make prepare-merge` - fetch changes from remote repositories (can be -specified on commandline via GIT\_SUBDIR or GIT\_REMOTE vars), (optionally) -verify tags and show the changes. This do not merge the changes - there are -left for review as FETCH\_HEAD ref. You can merge them using `git merge -FETCH_HEAD` (in each repo directory). Or `make do-merge` to merge all of them. +1. `./qb package diff` - show uncommitted changes +2. ` ./qb repository check-release-status-for-component` and +`./qb repository check-release-status-for-template`- show version of each + component/template (based on git tags) +3. `./qb package sign` - sign built packages +4. `./qb package publish` and `./qb package upload` - publish signed packages + and upload published + repository ## Copying Code to dom0 diff --git a/developer/building/qubes-builder-v2.md b/developer/building/qubes-builder-v2.md new file mode 100644 index 00000000..79d85e21 --- /dev/null +++ b/developer/building/qubes-builder-v2.md @@ -0,0 +1,160 @@ +--- +lang: en +layout: doc +permalink: /doc/qubes-builder-v2/ +redirect_from: +- /en/doc/qubes-builder-v2/ +- /doc/QubesBuilder2/ +- /wiki/QubesBuilder2/ +ref: 311 +title: Qubes builder v2 +--- + +This is a brief introduction of using Qubes Builder v2 to work with Qubes OS +sources. It will walk you through installing and configuring Builder v2 and +using it to fetch and build Qubes OS packages. + +For details and customization, use [Qubes OS v2 builder documentation](https://github.com/QubesOS/qubes-builderv2/). + +# Overview + +In the second generation of Qubes OS builder, container or disposable qube +isolation is used to perform every stage of the build and release process. +From fetching sources to building, everything is executed inside an isolated +*cage* (either a disposable or a container) using an *executor*. For every +command that needs to perform an action on sources, like cloning and +verifying Git repos, rendering a SPEC file, generating SRPM or Debian +source packages, a new cage is used. Only the signing, publishing, and +uploading stages are executed locally outside a cage. + + +# Setup + +This is a simple setup for using a docker executor (a good default choice, +if you don't know which executor to use, use docker). + +1. First, decide what qube are you going to use for working with Qubes + Builder v2. It can be an AppVM or a Standalone qube, with some steps + different between the two. + +2. Then, clone the qubes-builder v2 repository into a location of your + choice: + ```shell + git clone https://github.com/QubesOS/qubes-builderv2 + cd qubes-builderv2/ + ``` + +3. Installing dependencies + + Dependencies need to be installed for the qube you want to be developing + using Qubes Builder v2 - either in its template, or in the qube itself, + if it's a standalone. + Dependencies are specified in `dependencies-*. + txt` files in the main builder directory, and you can install them easily + in the following ways: + 1. for Fedora, use: + ```shell + $ sudo dnf install $(cat dependencies-fedora.txt) + $ test -f /usr/share/qubes/marker-vm && sudo dnf install qubes-gpg-split + ``` + 2. for Debian (note: some Debian packages require Debian version 13 or + later), use: + ```shell + $ sudo apt install $(cat dependencies-debian.txt) + $ test -f /usr/share/qubes/marker-vm && sudo apt install qubes-gpg-split + ``` + +4. If you haven't used docker in the current qube, you need also to set up + some permissions. In particular, the user has to be added to the `docker` + group: + ```shell + $ sudo usermod -aG docker user + ``` + Next, **restart the qube**. + +5. Finally, you need to generate a docker image: + ```shell + $ tools/generate-container-image.sh docker + ``` + + In an AppVM, as `/var/lib/docker` is not persistent by default, you also + need to use bind-dirs to avoid repeating this step after reboot, adding + the following to the `/rw/config/qubes-bind-dirs.d/docker.conf` file in + this qube: + + ``` + binds+=( '/var/lib/docker' ) + ``` + +# Configuration + +To use Qubes OS Builder v2, you need to have a `builder.yml` configuration file. +You can use one of the sample files from the `example-configs/` directory; for a +more readable `builder.yml`, you can also include one of the files from that +directory in your `builder.yml`. An example `builder.yml` is: + +```yaml +# include configuration relevant for the current release +include: +- example-configs/qubes-os-r4.2.yml + +# which repository to use to fetch sources +use-qubes-repo: + version: 4.2 + testing: true + +# each package built will have local build number appended to package release +# number. It makes it easier to update in testing environment +increment-devel-versions: true + +# reduce output +debug: false + +# this can be set to true if you do not want sources to be automatically +# fetched from git +skip-git-fetch: false + +# executor configuration +executor: + type: docker + options: + image: "qubes-builder-fedora:latest" + +``` + + +# Using Builder v2 + +To fetch sources - in this example, for the `core-admin-client` package, you +can use the following command: + +```shell +$ ./qb -c core-admin-client package fetch +``` + +This will fetch the sources for the listed package and place them in +`artifacts/sources` directory. + +To build a package (from sources in the `artifacts/sources` directory), use: + +```shell +$ ./qb -c core-admin-client package fetch prep build +``` + +or, if you want to build for a specific target (`host-fc37` is a `dom0` +using Fedora 37, `vm-fc40` would be a qube using Fedora 40 etc.), use: + +```shell +$ ./qb -c core-admin-client -d host-fc37 package fetch prep build +``` + +If you want to fetch entire Qubes OS sources (caution: some repositories might +have additional requirements; you can disable repositories that are not +needed in the `example-configs/*.yml` file you are using by commenting them +out. In particular, `python-fido2`, `lvm` and `windows`-related repositories +have +special requirements), use the following: + +```shell +$ ./qb package fetch +``` diff --git a/developer/debugging/automated-tests.md b/developer/debugging/automated-tests.md index 38e4aca2..1f72ede8 100644 --- a/developer/debugging/automated-tests.md +++ b/developer/debugging/automated-tests.md @@ -132,7 +132,7 @@ Whereas integration tests are mostly stored in the [qubes-core-admin](https://gi To for example run the `qubes-core-admin` unit tests, you currently have to clone at least [qubes-core-admin](https://github.com/QubesOS/qubes-core-admin) and its dependency [qubes-core-qrexec](https://github.com/QubesOS/qubes-core-qrexec) repository in the branches that you want to test. -The below example however will assume that you set up a build environment as described in the [Qubes Builder documentation](/doc/qubes-builder/). +The below example however will assume that you set up a build environment as described in the [Qubes Builder documentation](/doc/qubes-builder-v2/). Assuming you cloned the `qubes-builder` repository to your home directory inside a fedora VM, you can use the following commands to run the unit tests: diff --git a/developer/debugging/test-bench.md b/developer/debugging/test-bench.md index ca48a5ea..66a072c5 100644 --- a/developer/debugging/test-bench.md +++ b/developer/debugging/test-bench.md @@ -205,9 +205,10 @@ pushd ${HOME}/builder >/dev/null # the following are needed only if you have sources outside builder #rm -rf qubes-src/core-admin -#make COMPONENTS=core-admin get-sources +#qb -c core-admin package fetch -make core-admin +qb -c core-admin -d host-fc41 prep build +# update your dom0 fedora distribution as appropriate qtb-install qubes-src/core-admin/rpm/x86_64/qubes-core-dom0-*.rpm qtb-runtests ``` diff --git a/developer/general/gsoc.md b/developer/general/gsoc.md index e49d66d9..a2990cd9 100644 --- a/developer/general/gsoc.md +++ b/developer/general/gsoc.md @@ -31,7 +31,7 @@ You should start learning the components that you plan on working on before the Coming up with an interesting idea that you can realistically achieve in the time available to you (one summer) is probably the most difficult part. We strongly recommend getting involved in advance of the beginning of GSoC, and we will look favorably on applications from prospective contributors who have already started to act like free and open source developers. -Before the summer starts, there are some preparatory tasks which are highly encouraged. First, if you aren't already, definitely start using Qubes as your primary OS as soon as possible! Also, it is encouraged that you become familiar and comfortable with the Qubes development workflow sooner than later. A good way to do this (and also a great way to stand out as an awesome applicant and make us want to accept you!) might be to pick up some issues from [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) (our issue-tracking repo) and submit some patches addressing them. Some suitable issues might be those with tags ["help wanted" and "P: minor"](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22P%3A%20minor%22%20label%3A%22help%20wanted%22) (although more significant things are also welcome, of course). Doing this will get you some practice with [qubes-builder](/doc/qubes-builder/), our code-signing policies, and some familiarity with our code base in general so you are ready to hit the ground running come summer. +Before the summer starts, there are some preparatory tasks which are highly encouraged. First, if you aren't already, definitely start using Qubes as your primary OS as soon as possible! Also, it is encouraged that you become familiar and comfortable with the Qubes development workflow sooner than later. A good way to do this (and also a great way to stand out as an awesome applicant and make us want to accept you!) might be to pick up some issues from [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) (our issue-tracking repo) and submit some patches addressing them. Some suitable issues might be those with tags ["help wanted" and "P: minor"](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22P%3A%20minor%22%20label%3A%22help%20wanted%22) (although more significant things are also welcome, of course). Doing this will get you some practice with [qubes-builder](/doc/qubes-builder-v2/), our code-signing policies, and some familiarity with our code base in general so you are ready to hit the ground running come summer. ### Contributor proposal guidelines @@ -422,7 +422,7 @@ for more information and qubes-specific background. **Difficulty**: medium -**Knowledge prerequisite**: qubes-builder [[1]](/doc/qubes-builder/) [[2]](/doc/qubes-builder-details/) [[3]](https://github.com/QubesOS/qubes-builder/tree/master/doc), and efficient at introspecting complex systems: comfortable with tracing and debugging tools, ability to quickly identify and locate issues within a large codebase (upstream build tools), etc. +**Knowledge prerequisite**: qubes-builder [[1]](/doc/qubes-builder-v2/) [[2]](https://github.com/QubesOS/qubes-builderv2), and efficient at introspecting complex systems: comfortable with tracing and debugging tools, ability to quickly identify and locate issues within a large codebase (upstream build tools), etc. **Size of the project**: 350 hours diff --git a/introduction/faq.md b/introduction/faq.md index 2258ee1b..f869f760 100644 --- a/introduction/faq.md +++ b/introduction/faq.md @@ -678,7 +678,7 @@ Any rpm-based, 64-bit environment, the preferred OS being Fedora. ### How do I build Qubes from sources? -See [these instructions](/doc/qubes-builder/). +See [these instructions](/doc/qubes-builder-v2/). ### How do I submit a patch? diff --git a/user/downloading-installing-upgrading/testing.md b/user/downloading-installing-upgrading/testing.md index d6e6339d..4353262f 100644 --- a/user/downloading-installing-upgrading/testing.md +++ b/user/downloading-installing-upgrading/testing.md @@ -17,7 +17,7 @@ How to test upcoming Qubes OS releases: - Test the latest release candidate (RC) on the [downloads](/downloads/) page, if one is currently available. (Or try an older RC from our [FTP server](https://ftp.qubes-os.org/iso/).) - Try the [signed weekly builds](https://qubes.notset.fr/iso/). ([Learn more](https://forum.qubes-os.org/t/16929) and [track their status](https://github.com/fepitre/updates-status-iso/issues).) -- Use [qubes-builder](/doc/qubes-builder/) to build the latest release yourself. +- Use [qubes-builder](/doc/qubes-builder-v2/) to build the latest release yourself. - (No support) Experiment with developer alpha ISOs found from time to time at [Qubes OpenQA](https://openqa.qubes-os.org/). Please make sure to [report any bugs you encounter](/doc/issue-tracking/). diff --git a/user/templates/templates.md b/user/templates/templates.md index 2f7ac64a..681a4951 100644 --- a/user/templates/templates.md +++ b/user/templates/templates.md @@ -429,8 +429,9 @@ this context: the same as their template filesystem, of course. * Some templates are available in ready-to-use binary form, but some of them are available only as source code, which can be built using the [Qubes - Builder](/doc/qubes-builder/). In particular, some template "flavors" are - available in source code form only. For the technical details of the template + Builder](https://github.com/QubesOS/qubes-builderv2/). In particular, some + template "flavors" are available in source code form only. For the + technical details of the template system, please see [Template Implementation](/doc/template-implementation/). - Take a look at the [Qubes Builder](/doc/qubes-builder/) documentation for + Take a look at the [Qubes Builder](/doc/qubes-builder-v2/) documentation for instructions on how to compile them. From e529345e72d4732daac512abb470950e38e680e1 Mon Sep 17 00:00:00 2001 From: garindean <31627216+garindean@users.noreply.github.com> Date: Wed, 2 Apr 2025 01:10:15 -0400 Subject: [PATCH 21/27] Update how-to-organize-your-qubes.md grammar --- user/how-to-guides/how-to-organize-your-qubes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user/how-to-guides/how-to-organize-your-qubes.md b/user/how-to-guides/how-to-organize-your-qubes.md index 677a3b1b..947312b9 100644 --- a/user/how-to-guides/how-to-organize-your-qubes.md +++ b/user/how-to-guides/how-to-organize-your-qubes.md @@ -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. From c4129f8852ed279b73ba76ea8d122570c9f17d94 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 9 Apr 2025 15:02:04 -0700 Subject: [PATCH 22/27] Fix dead links --- .../certified-hardware/certified-hardware.md | 26 +++++++++---------- .../dasharo-fidelisguard-z690.md | 12 ++++----- 2 files changed, 19 insertions(+), 19 deletions(-) diff --git a/user/hardware/certified-hardware/certified-hardware.md b/user/hardware/certified-hardware/certified-hardware.md index a98835a8..3067080b 100644 --- a/user/hardware/certified-hardware/certified-hardware.md +++ b/user/hardware/certified-hardware/certified-hardware.md @@ -25,19 +25,19 @@ Qubes-certified computers are certified for a [major release](/doc/version-schem The current Qubes-certified models are listed below in reverse chronological order of certification. -| Brand | Model | Certification details | -| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -| [NovaCustom](https://novacustom.com/) | [V54 Series](https://novacustom.com/product/v54-series/) | [Certification details](/doc/certified-hardware/novacustom-v54-series/) | -| [Nitrokey](https://www.nitrokey.com/) | [NitroPad V56](https://shop.nitrokey.com/shop/nitropad-v56-684) | [Certification details](/doc/certified-hardware/nitropad-v56/) | -| [NovaCustom](https://novacustom.com/) | [V56 Series](https://novacustom.com/product/v56-series/) | [Certification details](/doc/certified-hardware/novacustom-v56-series/) | -| [Nitrokey](https://www.nitrokey.com/) | [NitroPC Pro 2](https://shop.nitrokey.com/shop/nitropc-pro-2-523) | [Certification details](/doc/certified-hardware/nitropc-pro-2/) | -| [Star Labs](https://starlabs.systems/) | [StarBook](https://starlabs.systems/pages/starbook) | [Certification details](/doc/certified-hardware/starlabs-starbook/) | -| [Nitrokey](https://www.nitrokey.com/) | [NitroPC Pro](https://shop.nitrokey.com/shop/product/nitropc-pro-523) | [Certification details](/doc/certified-hardware/nitropc-pro/) | -| [NovaCustom](https://novacustom.com/) | [NV41 Series](https://novacustom.com/product/nv41-series/) | [Certification details](/doc/certified-hardware/novacustom-nv41-series/) | -| [3mdeb](https://3mdeb.com/) | [Dasharo FidelisGuard Z690](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) | [Certification details](/doc/certified-hardware/dasharo-fidelisguard-z690/) | -| [Nitrokey](https://www.nitrokey.com/) | [NitroPad T430](https://shop.nitrokey.com/shop/product/nitropad-t430-119) | [Certification details](/doc/certified-hardware/nitropad-t430/) | -| [Nitrokey](https://www.nitrokey.com/) | [NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67) | [Certification details](/doc/certified-hardware/nitropad-x230/) | -| [Insurgo](https://insurgo.ca/) | [PrivacyBeast X230](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/) | [Certification details](/doc/certified-hardware/insurgo-privacybeast-x230/) | +| Brand | Model | Certification details | +| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | +| [NovaCustom](https://novacustom.com/) | [V54 Series](https://novacustom.com/product/v54-series/) | [Certification details](/doc/certified-hardware/novacustom-v54-series/) | +| [Nitrokey](https://www.nitrokey.com/) | [NitroPad V56](https://shop.nitrokey.com/shop/nitropad-v56-684) | [Certification details](/doc/certified-hardware/nitropad-v56/) | +| [NovaCustom](https://novacustom.com/) | [V56 Series](https://novacustom.com/product/v56-series/) | [Certification details](/doc/certified-hardware/novacustom-v56-series/) | +| [Nitrokey](https://www.nitrokey.com/) | [NitroPC Pro 2](https://shop.nitrokey.com/shop/nitropc-pro-2-523) | [Certification details](/doc/certified-hardware/nitropc-pro-2/) | +| [Star Labs](https://starlabs.systems/) | [StarBook](https://starlabs.systems/pages/starbook) | [Certification details](/doc/certified-hardware/starlabs-starbook/) | +| [Nitrokey](https://www.nitrokey.com/) | [NitroPC Pro](https://shop.nitrokey.com/shop/product/nitropc-pro-523) | [Certification details](/doc/certified-hardware/nitropc-pro/) | +| [NovaCustom](https://novacustom.com/) | [NV41 Series](https://novacustom.com/product/nv41-series/) | [Certification details](/doc/certified-hardware/novacustom-nv41-series/) | +| [3mdeb](https://3mdeb.com/) | [Dasharo FidelisGuard Z690](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) | [Certification details](/doc/certified-hardware/dasharo-fidelisguard-z690/) | +| [Nitrokey](https://www.nitrokey.com/) | [NitroPad T430](https://shop.nitrokey.com/shop/product/nitropad-t430-119) | [Certification details](/doc/certified-hardware/nitropad-t430/) | +| [Nitrokey](https://www.nitrokey.com/) | [NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67) | [Certification details](/doc/certified-hardware/nitropad-x230/) | +| [Insurgo](https://insurgo.ca/) | [PrivacyBeast X230](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/) | [Certification details](/doc/certified-hardware/insurgo-privacybeast-x230/) | ## Become hardware certified diff --git a/user/hardware/certified-hardware/dasharo-fidelisguard-z690.md b/user/hardware/certified-hardware/dasharo-fidelisguard-z690.md index 88a10507..6c85d154 100644 --- a/user/hardware/certified-hardware/dasharo-fidelisguard-z690.md +++ b/user/hardware/certified-hardware/dasharo-fidelisguard-z690.md @@ -6,11 +6,11 @@ title: Dasharo FidelisGuard Z690 image: /attachment/posts/dasharo-fidelisguard-z690_2.jpg --- -The [Dasharo FidelisGuard Z690](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4. +The [Dasharo FidelisGuard Z690](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4. [![Photo of MSI PRO Z690-A DDR4 motherboard](/attachment/posts/dasharo-fidelisguard-z690_1.jpg)](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) -The [Dasharo FidelisGuard Z690](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is a full desktop PC build that brings the [Dasharo](https://dasharo.com/) open-source firmware distribution to the MSI PRO Z690-A DDR4 motherboard with Qubes OS preinstalled. The full configuration includes: +The [Dasharo FidelisGuard Z690](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is a full desktop PC build that brings the [Dasharo](https://dasharo.com/) open-source firmware distribution to the MSI PRO Z690-A DDR4 motherboard with Qubes OS preinstalled. The full configuration includes: | Part | Model Name | |------------- | -------------------------------------------------------------- | @@ -21,7 +21,7 @@ The [Dasharo FidelisGuard Z690](https://3mdeb.com/shop/open-source-hardware/dash | Storage | SSD Intel 670p 512 GB M.2 2280 PCI-E x4 Gen3 NVMe | | Enclosure | SilentiumPC Armis AR1 | -[![Photo of Dasharo FidelisGuard Z690 with open case](/attachment/posts/dasharo-fidelisguard-z690_2.jpg)](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) +[![Photo of Dasharo FidelisGuard Z690 with open case](/attachment/posts/dasharo-fidelisguard-z690_2.jpg)](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) This computer comes with a "Dasharo Supporters Entrance Subscription," which includes the following: @@ -31,8 +31,8 @@ This computer comes with a "Dasharo Supporters Entrance Subscription," which inc - Dasharo Premier Support through an invite-only Matrix channel - Influence on the Dasharo feature roadmap -[![Photo of Dasharo FidelisGuard Z690 with open case](/attachment/posts/dasharo-fidelisguard-z690_3.jpg)](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) +[![Photo of Dasharo FidelisGuard Z690 with open case](/attachment/posts/dasharo-fidelisguard-z690_3.jpg)](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) -For further details, please see the [Dasharo FidelisGuard Z690](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) product page. +For further details, please see the [Dasharo FidelisGuard Z690](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) product page. -[![Photo of the outside of the Dasharo FidelisGuard Z690](/attachment/posts/dasharo-fidelisguard-z690_4.jpg)](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) +[![Photo of the outside of the Dasharo FidelisGuard Z690](/attachment/posts/dasharo-fidelisguard-z690_4.jpg)](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) From 187db01576953444c708b5e3cea3edb2b88ddaa3 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 9 Apr 2025 15:43:48 -0700 Subject: [PATCH 23/27] Fix dead link --- user/hardware/certified-hardware/dasharo-fidelisguard-z690.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user/hardware/certified-hardware/dasharo-fidelisguard-z690.md b/user/hardware/certified-hardware/dasharo-fidelisguard-z690.md index 6c85d154..0ded8346 100644 --- a/user/hardware/certified-hardware/dasharo-fidelisguard-z690.md +++ b/user/hardware/certified-hardware/dasharo-fidelisguard-z690.md @@ -8,7 +8,7 @@ image: /attachment/posts/dasharo-fidelisguard-z690_2.jpg The [Dasharo FidelisGuard Z690](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4. -[![Photo of MSI PRO Z690-A DDR4 motherboard](/attachment/posts/dasharo-fidelisguard-z690_1.jpg)](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) +[![Photo of MSI PRO Z690-A DDR4 motherboard](/attachment/posts/dasharo-fidelisguard-z690_1.jpg)](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) The [Dasharo FidelisGuard Z690](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is a full desktop PC build that brings the [Dasharo](https://dasharo.com/) open-source firmware distribution to the MSI PRO Z690-A DDR4 motherboard with Qubes OS preinstalled. The full configuration includes: From 674f9b6dd20e8290ae9aa6031c1b615a47010238 Mon Sep 17 00:00:00 2001 From: unman Date: Thu, 10 Apr 2025 13:37:18 +0000 Subject: [PATCH 24/27] Fix dead link to Micah's video --- introduction/video-tours.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/introduction/video-tours.md b/introduction/video-tours.md index 575ba8af..94739397 100644 --- a/introduction/video-tours.md +++ b/introduction/video-tours.md @@ -22,7 +22,7 @@ Watch all the talks from Qubes OS Summit 2022, which took place September 9-11, ## Micah Lee presents "Qubes OS: The Operating System That Can Protect You Even If You Get Hacked" -[Micah Lee](https://micahflee.com/), a long-time Qubes [advocate](/endorsements/), presented [Qubes OS: The Operating System That Can Protect You Even If You Get Hacked](https://www.hope.net/schedule.html#-qubes-os-the-operating-system-that-can-protect-you-even-if-you-get-hacked-) at the [Circle of HOPE](https://www.hope.net/index.html) conference, which took place July 20-22, 2018 in New York City. +[Micah Lee](https://micahflee.com/), a long-time Qubes [advocate](/endorsements/), presented [Qubes OS: The Operating System That Can Protect You Even If You Get Hacked](https://archive.org/details/QubesOSTheOperatingSystemThatCanProtectYouEvenIfYouGetHackedTalkByMicahLee) at the Circle of HOPE conference, which took place July 20-22, 2018 in New York City.
From 81e4abc4160d56179f3229f2d7067b8907c207a4 Mon Sep 17 00:00:00 2001 From: unman Date: Sun, 13 Apr 2025 12:55:19 +0000 Subject: [PATCH 25/27] Minor changes to workflow.md using Builder v2 --- developer/building/development-workflow.md | 29 +++++++++++----------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/developer/building/development-workflow.md b/developer/building/development-workflow.md index e4967756..f125533f 100644 --- a/developer/building/development-workflow.md +++ b/developer/building/development-workflow.md @@ -12,17 +12,17 @@ title: Development workflow A workflow for developing Qubes OS+ -First things first, setup [QubesBuilder](/doc/qubes-builder-v2/). This guide +To begin, setup [QubesBuilder](/doc/qubes-builder-v2/). This guide assumes you're using qubes-builder v2 to build Qubes. ## Repositories and committing Code -Qubes is split into a bunch of git repos. These are all contained in the +Qubes source code is split into many git repos. These are all contained in the `artifacts/sources` directory under qubes-builder. Subdirectories there are separate components, stored in separate git repositories. The best way to write and contribute code is to create a git repo somewhere -(e.g., github) for the repo you are interested in editing (e.g., +(e.g., GitHub) for the repo you are interested in editing (e.g., `qubes-manager`, `core-agent-linux`, etc). To integrate your repo with the rest of Qubes, cd to the repo directory and add your repository as a remote in git @@ -30,18 +30,17 @@ of Qubes, cd to the repo directory and add your repository as a remote in git ~~~ $ cd qubes-builder/artifacts/sources/qubes-manager -$ git remote add abel git@github.com:abeluck/qubes-manager.git +$ git remote add abel git@GitHub.com:abeluck/qubes-manager.git ~~~ You can then proceed to easily develop in your own branches, pull in new -commits from the dev branches, merge them, and eventually push to your own repo -on github. +commits from the dev branches, merge them, and eventually push to your own repo. When you are ready to submit your changes to Qubes to be merged, push your changes, then create a signed git tag (using `git tag -s`). Finally, send a -letter to the Qubes listserv describing the changes and including the link to -your repository. You can also create pull request on github. Don't forget to -include your public PGP key you use to sign your tags. +letter to the Qubes listserv describing the changes, and including a link to +your repository. If you are using GitHub you can instead create a pull request. +Don't forget to include the public PGP key you use to sign your tags. ### Kernel-specific notes @@ -117,7 +116,7 @@ vi series.conf #### Building RPMs -Now it is a good moment to make sure you have changed kernel release name in +Now is a good moment to make sure you have changed the kernel release name in rel file. For example, if you change it to '1debug201211116c' the resulting RPMs will be named 'kernel-3.4.18-1debug20121116c.pvops.qubes.x86\_64.rpm'. This will help @@ -284,12 +283,12 @@ if [ "$1" = "tb" ]; then exit $? fi -git remote add $1 git@github.com:$1/qubes-`basename $PWD` +git remote add $1 git@GitHub.com:$1/qubes-`basename $PWD` ~~~ It should be executed from component top level directory. This script takes one argument - remote name. If it is `tb`, then it creates qrexec-based git remote -to `testbuilder` VM. Otherwise it creates remote pointing at github account of +to `testbuilder` VM. Otherwise it creates remote pointing at GitHub account of the same name. In any case it points at repository matching current directory name. @@ -308,7 +307,7 @@ current and current-testing). ### RPM packages - yum repo -In source VM, grab [linux-yum](https://github.com/QubesOS/qubes-linux-yum) repository (below is assumed you've made it in +In source VM, grab [linux-yum](https://GitHub.com/QubesOS/qubes-linux-yum) repository (below is assumed you've made it in `~/repo-yum-upload` directory) and replace `update_repo.sh` script with: ~~~ @@ -324,7 +323,7 @@ find -type f -name '*.rpm' -delete qrexec-client-vm $VMNAME local.UpdateYum ~~~ -In target VM, setup actual yum repository (also based on [linux-yum](https://github.com/QubesOS/qubes-linux-yum), this time +In target VM, setup actual yum repository (also based on [linux-yum](https://GitHub.com/QubesOS/qubes-linux-yum), this time without modifications). You will also need to setup some gpg key for signing packages (it is possible to force yum to install unsigned packages, but it isn't possible for `qubes-dom0-update` tool). Fill `~/.rpmmacros` with @@ -404,7 +403,7 @@ Remember to also import gpg public key using `rpm --import`. Steps are mostly the same as in the case of yum repo. The only details that differ: -- use [linux-deb](https://github.com/QubesOS/qubes-linux-deb) instead of [linux-yum](https://github.com/QubesOS/qubes-linux-yum) as a base - both in source and target VM +- use [linux-deb](https://GitHub.com/QubesOS/qubes-linux-deb) instead of [linux-yum](https://GitHub.com/QubesOS/qubes-linux-yum) as a base - both in source and target VM - use different `update_repo.sh` script in source VM (below) - use `local.UpdateApt` qrexec service in target VM (code below) - in target VM additionally place `update-local-repo.sh` script in repository dir (code below) From 63ad8ab1c1f094ae2cabbc55f5282952cbda887f Mon Sep 17 00:00:00 2001 From: unman Date: Sun, 13 Apr 2025 12:57:18 +0000 Subject: [PATCH 26/27] Minor changes to description of qubes-builder-v2 --- developer/building/qubes-builder-v2.md | 52 +++++++++++++------------- 1 file changed, 27 insertions(+), 25 deletions(-) diff --git a/developer/building/qubes-builder-v2.md b/developer/building/qubes-builder-v2.md index 79d85e21..1210910b 100644 --- a/developer/building/qubes-builder-v2.md +++ b/developer/building/qubes-builder-v2.md @@ -10,8 +10,8 @@ ref: 311 title: Qubes builder v2 --- -This is a brief introduction of using Qubes Builder v2 to work with Qubes OS -sources. It will walk you through installing and configuring Builder v2 and +This is a brief introduction to using Qubes Builder v2 to work with Qubes OS +sources. It will walk you through installing and configuring Builder v2, and using it to fetch and build Qubes OS packages. For details and customization, use [Qubes OS v2 builder documentation](https://github.com/QubesOS/qubes-builderv2/). @@ -30,25 +30,17 @@ uploading stages are executed locally outside a cage. # Setup -This is a simple setup for using a docker executor (a good default choice, -if you don't know which executor to use, use docker). +This is a simple setup using a docker executor. This is a good default choice; +if you don't know which executor to use, use docker. -1. First, decide what qube are you going to use for working with Qubes +1. First, decide what qube you are going to use when working with Qubes Builder v2. It can be an AppVM or a Standalone qube, with some steps different between the two. -2. Then, clone the qubes-builder v2 repository into a location of your - choice: - ```shell - git clone https://github.com/QubesOS/qubes-builderv2 - cd qubes-builderv2/ - ``` +2. Installing dependencies -3. Installing dependencies - - Dependencies need to be installed for the qube you want to be developing - using Qubes Builder v2 - either in its template, or in the qube itself, - if it's a standalone. + If you want to use an app qube for developing, install dependencies in the template. + If you are using a standalone, install them in the qube itself. Dependencies are specified in `dependencies-*. txt` files in the main builder directory, and you can install them easily in the following ways: @@ -64,7 +56,16 @@ if you don't know which executor to use, use docker). $ test -f /usr/share/qubes/marker-vm && sudo apt install qubes-gpg-split ``` -4. If you haven't used docker in the current qube, you need also to set up + If you have installed dependencies in the template, close it, and + (re)start the development qube. + +3. Clone the qubes-builder v2 repository into a location of your choice: + ```shell + git clone https://github.com/QubesOS/qubes-builderv2 + cd qubes-builderv2/ + ``` + +4. If you haven't previously used docker in the current qube, you need to set up some permissions. In particular, the user has to be added to the `docker` group: ```shell @@ -77,8 +78,8 @@ if you don't know which executor to use, use docker). $ tools/generate-container-image.sh docker ``` - In an AppVM, as `/var/lib/docker` is not persistent by default, you also - need to use bind-dirs to avoid repeating this step after reboot, adding + In an app qube, as `/var/lib/docker` is not persistent by default, you also + need to use [bind-dirs](/doc/bind-dirs/) to avoid repeating this step after reboot, adding the following to the `/rw/config/qubes-bind-dirs.d/docker.conf` file in this qube: @@ -148,13 +149,14 @@ using Fedora 37, `vm-fc40` would be a qube using Fedora 40 etc.), use: $ ./qb -c core-admin-client -d host-fc37 package fetch prep build ``` -If you want to fetch entire Qubes OS sources (caution: some repositories might -have additional requirements; you can disable repositories that are not -needed in the `example-configs/*.yml` file you are using by commenting them -out. In particular, `python-fido2`, `lvm` and `windows`-related repositories -have -special requirements), use the following: +If you want to fetch the entire Qubes OS source use the following: ```shell $ ./qb package fetch ``` + +**caution**: some repositories might have additional requirements. You can +disable repositories that are not needed in the `example-configs/*.yml` +file you are using by commenting them out. In particular, `python-fido2`, +`lvm` and `windows`-related repositories have special requirements. + From b9bec14ae44273d6fcac0f0294ca038122aa2d43 Mon Sep 17 00:00:00 2001 From: unman Date: Sun, 13 Apr 2025 14:37:15 +0000 Subject: [PATCH 27/27] Update firewall page to make sure sys-net rules are correctly specified --- user/security-in-qubes/firewall.md | 35 ++++++++++++++++++------------ 1 file changed, 21 insertions(+), 14 deletions(-) diff --git a/user/security-in-qubes/firewall.md b/user/security-in-qubes/firewall.md index 1289db7a..5af06ec4 100644 --- a/user/security-in-qubes/firewall.md +++ b/user/security-in-qubes/firewall.md @@ -269,7 +269,8 @@ As an example we can take the use case of qube QubeDest running a web server lis **1. Identify the IP addresses you will need to use for sys-net, sys-firewall and the destination qube.** -You can get this information using various methods, but only the first one can be used for `sys-net` outside world IP: +You can get this information using various methods. +Only the first method can be used for `sys-net` to find the external IP: - by running this command in each qube: `ip -4 -br a | grep UP` - using `qvm-ls -n` @@ -284,7 +285,12 @@ Note the IP addresses you will need, they will be required in the next steps. For the following example, we assume that the physical interface ens6 in sys-net is on the local network 192.168.x.y with the IP 192.168.x.n, and that the IP address of sys-firewall is 10.137.1.z. -In the sys-net VM's Terminal, the first step is to define an ntables chain that will receive DNAT rules to relay the network traffic on a given port to the qube NetVM, we recommend to define a new chain for each destination qube to ease rules management: +When writing rules in sys-net, you can use `iif` or `iifname`. +`iif` is faster, but can change where interfaces are dynamically created and destroyed, eg. ppp0. +In that case use `iifname`, like this `iifname ens6`. +`iifname` can also match wildcards - `iifname "eth*"` + +In the sys-net VM's Terminal, the first step is to define an nftables chain that will receive DNAT rules to relay the network traffic on a given port to the qube NetVM, we recommend to define a new chain for each destination qube to ease rules management: ``` nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }' @@ -292,25 +298,24 @@ nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority fi > Note: the name `custom-dnat-qubeDST` is arbitrary -> Note: while we use a DNAT chain for a single qube, it's totally possible to have a single DNAT chain for multiple qubes +> Note: while we use a DNAT chain for a single qube, it's possible to have a single DNAT chain for multiple qubes Second step, code a natting firewall rule to route traffic on the outside interface for the service to the sys-firewall VM ``` -nft add rule qubes custom-dnat-qubeDEST iifgroup 1 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z +nft add rule qubes custom-dnat-qubeDEST iifname ens6 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z ``` Third step, code the appropriate new filtering firewall rule to allow new connections for the service ``` -nft add rule qubes custom-forward iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept +nft add rule qubes custom-forward iifname ens6 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept ``` > Note: If you do not wish to limit the IP addresses connecting to the service, remove `ip saddr 192.168.x.y/24` from the rules +> If you want to expose the service on multiple interfaces, repeat steps 2 and 3 above, for each interface. Alternatively, you can leave out the interface completely. -> If you want to expose the service on multiple interfaces, repeat the steps 2 and 3 described above, for each interface. Alternatively, you can leave out the interface completely. - -Verify the rules on sys-net firewall correctly match the packets you want by looking at its counters, check for the counter lines in the chains `custom-forward` and `custom-dnat-qubeDEST`: +Verify the rules on the sys-net firewall correctly match the packets you want by looking at the counters: check for the counter lines in the chains `custom-forward` and `custom-dnat-qubeDEST`: ``` nft list table ip qubes @@ -320,12 +325,12 @@ In this example, we can see 7 packets in the forward rule, and 3 packets in the ``` chain custom-forward { - iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter packets 7 bytes 448 accept + iifname ens6 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter packets 7 bytes 448 accept } chain custom-dnat-qubeDEST { type nat hook prerouting priority filter + 1; policy accept; - iifgroup 1 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter packets 3 bytes 192 dnat to 10.138.33.59 + iifname ens6 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter packets 3 bytes 192 dnat to 10.138.33.59 } ``` @@ -351,18 +356,20 @@ Content of `/rw/config/qubes-firewall-user-script` in `sys-net`: if nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }' then # create the dnat rule - nft add rule qubes custom-dnat-qubeDEST iifgroup 1 saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z + nft add rule qubes custom-dnat-qubeDEST iifname ens6 saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z # allow forwarded traffic - nft add rule qubes custom-forward iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept + nft add rule qubes custom-forward iifname ens6 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept fi ~~~ **3. Route packets from the FirewallVM to the VM** -For the following example, we use the fact that the physical interface of sys-firewall, facing sys-net, is eth0. Furthermore, we assume that the target VM running the web server has the IP address 10.137.0.xx and that the IP address of sys-firewall is 10.137.1.z. +For the following example, we use the fact that the interface of sys-firewall facing sys-net, is eth0. +This is allocated to iifgroup 1. +Furthermore, we assume that the IP address of sys-firewall is 10.137.1.z, and the target VM running the web server has the IP address 10.137.0.xx. -In the sys-firewall VM's Terminal, add a DNAT chain that will contain routing rules: +In the sys-firewall Terminal, add a DNAT chain that will contain routing rules: ``` nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'