Update documentation for Qubes 4.1 #112

eloquence · 2022-07-07T00:29:30Z

This does not include hardware-specific documentation updates or screenshot updates.

Partially resolves #104 (except for hardware-specific updates)
Resolves #108
Resolves #110
Resolves #111

Status

Ready for review

Test plan

Review visually for inconsistencies, errors, or parts of https://workstation.securedrop.org/ that haven't been updated yet but should be.
Ideally, at least one person should try to perform a prod install following the revised docs.

eloquence · 2022-07-07T00:34:28Z

docs/admin/upgrading_fedora.rst

@@ -1,4 +1,4 @@
-Upgrading to Fedora 35
+Upgrading to Fedora 36


We can remove this section on 4.1.1, which ships with fedora-36. Unless 4.1.1 is released as this is being reviewed, I'd recommend merging this PR as-is, as it'll be useful to have this in the commit history in case we need to reinstate the section with the next version bump.

Also referred to in #109, which will need to be revised (or updated post-merge) if this section is removed for Qubes 4.1.1.

eloquence · 2022-07-07T00:35:11Z

docs/admin/install.rst

@@ -445,30 +461,6 @@ To revoke this configuration change later or correct a typo, you can use the ``d
 Troubleshooting installation errors
 -----------------------------------

-"Recurse failed: none of the specified sources were found"


As discussed, we have not had reports of this issue in quite some time, despite many install runs.

eloquence · 2022-07-07T00:35:43Z

docs/admin/install.rst

 ~~~~~~~~~~~~~~~~~~~~~~~~~~

 See :doc:`upgrading_fedora`.

-Install Whonix 16


Qubes 4.1 ships with Whonix 16.

eloquence · 2022-07-07T00:37:30Z

docs/admin/install.rst

+
+After the command exits, confirm that you see an entry "Service: sys-usb" in the Qubes menu.
+
+Apply ``dom0`` updates (estimated wait time: 15-30 minutes)


For 4.1.0 in particular, this is critical due to the broken update check logic. This should no longer be an issue on 4.1.1, but it still seems to me that having qubes-dom0-update as an independent step makes sense, just in case of any QSBs since the stable release.

eloquence · 2022-07-07T00:41:18Z

docs/admin/install.rst

+
+.. code-block:: sh
+
+  sudo qubesctl state.sls qvm.sys-usb


@creviera I've copied this command from freedomofpress/securedrop-workstation#769 (comment) but have not tested it. If I read the later comments correctly, we may also want to add a hint for USB keyboard users to run sudo qubesctl state.sls qvm.usb-keyboard?

this is worth clarifying - enabling USB keyboard support is risky security-wise (speaking as someone who managed to badUSB their own laptop by accident a while back!) and should only be done if absolutely necessary.

My workaround in freedomofpress/securedrop-workstation#769 (comment) is:

Just noting my workaround is to run sudo qubesctl state.sls qvm.sys-usb which uses the correct disposable template (for 4.1.1-rc this is fedora-26-dvm). And I also have to run sudo qubesctl state.sls qvm.usb-keyboard to fix Denied qubes.InputKeyboard from sys-usb to dom0 errors.

Reboot seems to be necessary for thumb drives to be show up in the Devices menu under the USB Devices section and to be able to attach drives to VMs.

Both steps were required for me to get around the issue. There may be a way to fix the mapping of internal hardware so that we don't have to run the keyboard salt state. Let me know if you'd like me to investigate next Monday (or potentially this Friday).

Or, let me clarify... there are two issues: (1) sys-usb is not created because the Qubes installer incorrectly thinks I have a USB keyboard attached (sudo qubesctl state.sls qvm.sys-usb fixes that one), and (2) error popups will appear from time to time that say Denied qubes.InputKeyboard from sys-usb to dom0 - I can troubleshoot to see if these popups only show up when we are attaching a thumb drive (sudo qubesctl state.sls qvm.usb-keyboard fixes that one but you're right that we will want to develop a safer workaround)

OK, I actually see those Denieds on my daily machine as well, on plugging in a Yubikey (haven't tried with just a usb stick). So the docs should include both.

I've added this additional step, plus a verification step for USB support, in 69ec8eb. (I've not further verified these commands.)

zenmonkeykstop

Changes look good on visual review - will do a run through of the installation before approving.

sssoleileraaa · 2022-07-07T20:31:57Z

Changes also look good to me @eloquence - I can troubleshoot #112 (comment) in the next few days.

This does not include hardware-specific documentation updates or screenshot updates.

eloquence · 2022-07-07T20:54:33Z

(Rebased to pick up screenshot updates in #113)

eloquence · 2022-07-07T23:44:09Z

The template configuration screen (where sys-usb etc. are configured) is available only after the install/reboot, on the first boot. Clarified this ordering in 3f4501c and addressed a couple of other ordering issues.

eloquence · 2022-07-08T00:26:39Z

In the default config (which we recommend), sys-usb and sys-firewall are disposable. Therefore, our previous migration guide for Fedora updates is incorrect on a fresh install -- users also have to manually create a fedora-36-dvm to switch from fedora-34-dvm to fedora-36-dvm.

I've clarified this in ed667e7. Once again, all those steps will not be required with Qubes 4.1.1 (but will be for any future version that ships with an EOL template).

eloquence · 2022-07-08T00:33:44Z

Because the default scrollback length is not very generous and easily exceeded by our Salt output, I've added an explicit step to enable infinite scrollback in 7b8edcf.

zenmonkeykstop · 2022-07-08T13:35:15Z

docs/admin/install.rst

@@ -291,7 +312,7 @@ With the key and configuration available in ``dom0``, you're ready to set up Sec

    [securedrop-workstation-temporary]
    enabled=1
-    baseurl=https://yum.securedrop.org/workstation/dom0/f25
+    baseurl=https://yum.securedrop.org/workstation/dom0/f32
    name=SecureDrop Workstation Qubes initial install bootstrap

 - Download the SecureDrop Workstation config package to the curent working directory with the command:


One difference here is that I get prompted to accept the import of the Qubes 4 release key:

dnf download securedrop-workstation-dom0-config Fedora 36 - x86_64 3.3 MB/s | 81 MB 00:24 Fedora 36 openh264 (From Cisco) - x86_64 1.8 kB/s | 2.5 kB 00:01 Fedora 36 - x86_64 - Updates 3.3 MB/s | 21 MB 00:06 Qubes OS Repository for VM (updates) 1.2 kB/s | 833 B 00:00 Qubes OS Repository for VM (updates) 2.3 MB/s | 2.3 kB 00:00 Importing GPG key 0x9E2795E9: Userid : "Qubes OS Release 4 Signing Key" Fingerprint: 5817 A43B 283D E5A9 181A 522E 1848 792F 9E27 95E9 From : /etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-4-primary Is this ok [y/N]: y Qubes OS Repository for VM (updates) 60 kB/s | 137 kB 00:02 SecureDrop Workstation Qubes initial install bo 436 B/s | 2.4 kB 00:05 securedrop-workstation-dom0-config-0.7.0-1.fc32 136 kB/s | 125 kB 00:00

seems like the right key, but it is an extra prompt.

Made note of the prompt in 69ec8eb

zenmonkeykstop · 2022-07-08T14:47:18Z

Instructions are working for me, holding off on approval until the optional USB steps are added (I didn't encounter the issue FWIW)

zenmonkeykstop

LGTM with changes - the usb keyboard workaround is sub-optimal, but that's not the docs' fault.

eloquence commented Jul 7, 2022

View reviewed changes

zenmonkeykstop self-assigned this Jul 7, 2022

zenmonkeykstop reviewed Jul 7, 2022

View reviewed changes

eloquence added 2 commits July 7, 2022 13:53

Update documentation for Qubes 4.1

6e56b96

This does not include hardware-specific documentation updates or screenshot updates.

Use 4.1.0 consistently

aca0c5e

eloquence force-pushed the install-docs-updates-41 branch from 7468333 to aca0c5e Compare July 7, 2022 20:54

eloquence added the qubes-4.1 label Jul 7, 2022

Fix some order of operations issues

3f4501c

Add instructions for creating and using fedora-36-dvm

ed667e7

Recommend infinite scrollback

7b8edcf

eloquence mentioned this pull request Jul 8, 2022

Support for Qubes 4.1 freedomofpress/securedrop-workstation#600

Closed

zenmonkeykstop reviewed Jul 8, 2022

View reviewed changes

Expand on USB troubleshooting; release key confirmation step

69ec8eb

eloquence force-pushed the install-docs-updates-41 branch from ed9dcfa to 69ec8eb Compare July 8, 2022 17:39

zenmonkeykstop approved these changes Jul 11, 2022

View reviewed changes

zenmonkeykstop merged commit f7500c8 into main Jul 11, 2022

eloquence mentioned this pull request Aug 1, 2022

Qubes 4.1 installer does not create sys-usb freedomofpress/securedrop-workstation#769

Open

eloquence deleted the install-docs-updates-41 branch August 24, 2022 17:03

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update documentation for Qubes 4.1 #112

Update documentation for Qubes 4.1 #112

eloquence commented Jul 7, 2022

eloquence Jul 7, 2022

cfm Jul 7, 2022

eloquence Jul 7, 2022

eloquence Jul 7, 2022

eloquence Jul 7, 2022

eloquence Jul 7, 2022

zenmonkeykstop Jul 7, 2022

sssoleileraaa Jul 7, 2022

sssoleileraaa Jul 7, 2022 •

edited

Loading

zenmonkeykstop Jul 8, 2022

eloquence Jul 8, 2022

zenmonkeykstop left a comment

sssoleileraaa commented Jul 7, 2022

eloquence commented Jul 7, 2022

eloquence commented Jul 7, 2022 •

edited

Loading

eloquence commented Jul 8, 2022

eloquence commented Jul 8, 2022

zenmonkeykstop Jul 8, 2022

eloquence Jul 8, 2022

zenmonkeykstop commented Jul 8, 2022

zenmonkeykstop left a comment


		After the command exits, confirm that you see an entry "Service: sys-usb" in the Qubes menu.

		Apply ``dom0`` updates (estimated wait time: 15-30 minutes)

Update documentation for Qubes 4.1 #112

Update documentation for Qubes 4.1 #112

Conversation

eloquence commented Jul 7, 2022

Status

Test plan

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sssoleileraaa Jul 7, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zenmonkeykstop left a comment

Choose a reason for hiding this comment

sssoleileraaa commented Jul 7, 2022

eloquence commented Jul 7, 2022

eloquence commented Jul 7, 2022 • edited Loading

eloquence commented Jul 8, 2022

eloquence commented Jul 8, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zenmonkeykstop commented Jul 8, 2022

zenmonkeykstop left a comment

Choose a reason for hiding this comment

sssoleileraaa Jul 7, 2022 •

edited

Loading

eloquence commented Jul 7, 2022 •

edited

Loading