Template upgrade: documentation further amendments

Templates | Qubes OS explains

In the App Menu, click on Terminal Emulator. Type the command below, substituting <SYS_USB_DISPOSABLE_TEMPLATE> with the name of the disposable template on which sys-usb is based, <NEW_TEMPLATE> with the name of the new template, and <USB_QUBE> with the name of your USB qube. Other than these substitutions, make sure to enter the command exactly as written.

<SYS_USB_DISPOSABLE_TEMPLATE> seems unclear. If fedora-01 refers to e.g. fedora-37 when updating to fedora-38, it is not apparent why the old disposable is based on the new template.

<SYS_USB_DISPOSABLE_TEMPLATE> is e.g. fedora-37-dvm and is a disposable template which is different from TemplateVM such as fedora-37:

The use of fedora-01 and -02 in the docs may be confusing. Whilst updating from 37 to 38, this is then the command of choice:

qvm-shutdown --wait --all; qvm-prefs fedora-38-dvm template fedora-38; qvm-start sys-usb

following the steps from the manual closely and understanding, it yields:

Cannot connect to grexex agent for 60 seconds...

Have I missed something?

I think the manual meant you have to do this:
qvm-shutdown --wait --all; qvm-prefs fedora-37-dvm template fedora-38; qvm-start sys-usb
But this shouldn’t be the reason as to why you get this error:
Cannot connect to grexex agent for 60 seconds...

Interestingly, using history the precise sequence and commands updating from 36 to 37 do not work for 37 to 38.

The man page of qvm-prefs is not easy to understand.

The old disposable template is based on the new template because these are instructions for switching everything to the new template. If you don’t switch the old disposable template to the new template, then it will still be on the old template. If you don’t want that, your only options are:

  1. Switch the old disposable template to the new template (which is exactly what these instructions do).
  2. Delete the old disposable template, then create a new disposable template based on the new template.

Since your only keyboard or mouse are connected through a USB qube, and that USB qube is disposable, option (2) is not easily available to you.[*] It’s simply not possible to delete a disposable template while a named disposable based on that disposable template still exists, and deleting both would lock you out of your system. This leaves option (1).

[*] If it’s just the mouse, that’s probably still doable, but no one has tested and documented that procedure, and I didn’t want to make the instructions even more complicated. If it’s the keyboard, I suppose it should technically be possible to write a long command or script to perform (2) while you’re locked out, but in that case, you might as well just do (1), since (2) is basically just a riskier and more difficult way to achieve the same result, assuming you still trust your old disposable template as much as you’d trust the new one.

I think you’re being misled by the version number in fedora-37-dvm into thinking that it’s an “old” disposable template, even after you base it on your new template (fedora-38), but the only thing “old” in this scenario is the version number in the name fedora-37-dvm. If you’ve followed all the instructions correctly, everything is now based on Fedora 38. Fedora 37 is out of the picture.

I anticipated this problem and discussed it with Marek on this PR:

Based on that discussion, I opened this issue:

This will avoid the problem in Qubes 4.2 and later.

The alternatives are:

  1. Figure out a way to update all the version numbers across all the documentation automatically every time new versions come out. (No one’s volunteered to even try. I’d have no idea how.)
  2. Write in real version numbers, then manually update all of them across all the documentation every time new versions come out. (Realistically, no one’s going to do this.)
  3. Write in real version numbers, then have outdated real version numbers whenever new versions come out. (This is how it was before.)

Realistically, the choice is between (3) and how it is now. In both cases, you have to mentally substitute the version numbers in the example with the real version numbers you want. The only difference is that (3) leads to the docs usually being out-of-date and needing to be updated manually from time to time, whenever someone gets around to it (before quickly going back to being outdated again for a long time), while the way it is now avoids all that,

Thanks to the inspiration, I was able to successfully upgrade several different machines using these notes-in-a-nutshell. dom0 commands are available to replace GUI, I assume. fedora-NN-dvm is an immutable name based on the installation version.

1. dom0

qvm-shutdown fedora-<old>
qvm-clone fedora-<old> fedora-<new>
qvm-run -a fedora-<new> gnome-terminal
sudo dnf -y --releasever=<new> --setopt=cachedir=/mnt/removable --best --allowerasing distro-sync

2. sys-usb

if sys-usb=0

qubes-prefs --set default_template fedora-<new>

if sys-usb=1

#step a: GUI

Applications Menu -> Qubes Tools -> Qubes Global Settings -> Default template

#step b: dom0

qvm-shutdown --wait --all; qvm-prefs fedora-NN-dvm template fedora-<new>; qvm-start sys-usb

#step c: GUI

1. Qube Manager, click on the Template heading to sort by template.
2. Select all the qubes based on the old template by clicking on the first one, holding shift, then clicking on the last one.
3. With multiple qubes selected, right-click on any of them, hover your cursor over Template
4. then click on the new template.

3. finalize

qvm-remove fedora-<old>