User guide for upgrading 4.1 -> 4.2 is outdated

[Warthog-Capital]

Qubes OS release

Qubes 4.1.2

Brief summary

When following the user guide for "clean installation" at https://www.qubes-os.org/doc/upgrade/4.2/#clean-installation step by step, the script qubes-dist-upgrade returns an error: "ERROR: Cannot continue to STAGE 4, dom0 is not R4.2 yet. Any error happened in previous stages?"

A similar problem was reported on the forum, with a suggested solution that has not been commented or approved: https://forum.qubes-os.org/t/downgrading-template-standalone-upgrade-for-clean-install-r4-2/27028

Steps to reproduce

I am on Qubes 4.1.2 and followed the instructions at https://www.qubes-os.org/doc/upgrade/4.2/#clean-installation to the "T". Here is the resulting console log:

[user@dom0 ~]$ sudo qubes-dom0-update qubes-dist-upgrade
Using sys-firewall as UpdateVM to download updates for Dom0; this may take some time...
Qubes OS Repository for Dom0                    2.9 MB/s | 3.0 kB     00:00    
Qubes OS Repository for Dom0                     65 kB/s | 918  B     00:00    
Dependencies resolved.
================================================================================
 Package                Arch       Version          Repository             Size
================================================================================
Installing:
 qubes-dist-upgrade     noarch     4.1.6-1.fc32     qubes-dom0-cached      13 k

Transaction Summary
================================================================================
Install  1 Package

Total size: 13 k
Installed size: 23 k
Is this ok [y/N]: y
Downloading Packages:
Running transaction check
Transaction check succeeded.
Running transaction test
Transaction test succeeded.
Running transaction
  Preparing        :                                                        1/1 
  Installing       : qubes-dist-upgrade-4.1.6-1.fc32.noarch                 1/1 
  Running scriptlet: qubes-dist-upgrade-4.1.6-1.fc32.noarch                 1/1 
  Verifying        : qubes-dist-upgrade-4.1.6-1.fc32.noarch                 1/1 

Installed:
  qubes-dist-upgrade-4.1.6-1.fc32.noarch                                        

Complete!
[user@dom0 ~]$ qubes-dist-upgrade --template-standalone-upgrade
ERROR: This script must be run with root permissions
[user@dom0 ~]$ sudo qubes-dist-upgrade --template-standalone-upgrade
INFO: Please wait while running pre-checks...
INFO: Found sys-usb providing input devices. It will be kept running.
WARNING: /!\ MAKE SURE YOU HAVE MADE A BACKUP OF ALL YOUR VMs AND dom0 DATA /!\
-> Launch upgrade process? [y/N] y
---> Allow shutdown of unnecessary VM (use --keep-running to exclude some): xxx yyy zzz? [y/N] 
[user@dom0 ~]$ sudo qubes-dist-upgrade --template-standalone-upgrade
INFO: Please wait while running pre-checks...
INFO: Found sys-usb providing input devices. It will be kept running.
WARNING: /!\ MAKE SURE YOU HAVE MADE A BACKUP OF ALL YOUR VMs AND dom0 DATA /!\
-> Launch upgrade process? [y/N] y
ERROR: Cannot continue to STAGE 4, dom0 is not R4.2 yet. Any error happened in previous stages?

Expected behavior

1. There should be no unexpected interactions not covered in the user guide
2. The script should upgrade the templates as described in the user guide

Actual behavior

The following interactions are unexpected deviations from the user guide:

• requirement to run the script as sudo
• requirement to shut down all AppVMs (including the AppVM that is used to display the user guide), since otherwise the script will exit
• The script does not do what is described in the user guide. Instead of upgrading the templates, it simply exits with an error message.

Recommendation

Instead of downgrading the qubes-dist-upgrade tool as suggested in the forum (link above), the user guide should be fixed to work with the most recent version of the tool.

[alimirjamali]

@Warthog-Capital since r4.1 has been End-of-Life for over a month and its extended security support also ended yesterday, there is a chance that the guide would be eventually phased out from the website and r4.1 support related issues to be provided only via community. Similar to how the upgrade guides for the older releases (e.g. 4.0, 3.2, ...) might not be available on the website anymore.

I have created a topic on forum dedicated to your issues. You are more than welcome to join.

[github-actions[bot]]

This issue is being closed because:

• This issue is believed to affect only Qubes OS 4.1 (and possibly earlier).
• Qubes OS 4.1 has reached end-of-life (EOL).

If anyone believes that this issue should be reopened, please leave a comment saying so. (For example, if a bug still affects Qubes OS 4.2, then the comment "Affects 4.2" will suffice.)

[unman]

I think it is too early to close this. Some users will finally make the transition to 4.2 and we should support them in this.

[alimirjamali]

I think it is too early to close this. Some users will finally make the transition to 4.2 and we should support them in this.

Okay

[Warthog-Capital]

To clarify, since @alimirjamali 's comment on the forum seems to be mislead on the actual issue:

When following the user guide for "clean installation" at https://www.qubes-os.org/doc/upgrade/4.2/#clean-installation step by step,

I am trying to make a clean installation. I do NOT want to make an in-place upgrade.

The user guide for clean installation clearly states:

2. Install the qubes-dist-upgrade tool. This is the inplace upgrade tool, which is not what we’re doing. However it will be needed in order to prepare the templates for the 4.2 version. You install it with the following command in the dom0 terminal:

sudo qubes-dom0-update -y qubes-dist-upgrade

3. Change your templates to use the 4.2 repositories instead of the 4.1 ones. You do this with the following command in the dom0 terminal:

qubes-dist-upgrade --template-standalone-upgrade

Note: This step is critical to ensure the templates will receive updates once Qubes 4.1 reaches end-of-life (EOL) and was missing in previous clean installation instructions.

It is the third step that is explicitly noted as CRITICAL that doesn't work as instructed.

[alimirjamali]

I am trying to make a clean installation. I do NOT want to make an in-place upgrade.

Ok. Good luck

[h01ger]

On Thu, Aug 01, 2024 at 06:45:42AM -0700, unman wrote:

I think it is too early to close this. Some users will finally make the transition to 4.2 and we should support them in this.

absolutly.

-- cheers, Holger

⢀⣴⠾⠻⢶⣦⠀ ⣾⠁⢠⠒⠀⣿⡁ holger@(debian|reproducible-builds|layer-acht).org ⢿⡄⠘⠷⠚⠋⠀ OpenPGP: B8BF54137B09D35CF026FE9D 091AB856069AAA1C ⠈⠳⣄

Covid. Changing hearts and minds since 2019. @.***)

[github-actions[bot]]

This issue is being closed because:

• This issue is believed to affect only Qubes OS 4.1 (and possibly earlier).
• Qubes OS 4.1 has reached end-of-life (EOL).

If anyone believes that this issue should be reopened, please leave a comment saying so. (For example, if a bug still affects Qubes OS 4.2, then the comment "Affects 4.2" will suffice.)